Restore the Using FreeBSD-Stable section, which somehow got accidentally

deleted ten months ago and nobody noticed until now.

Reported by:	AMDmi3 on IRC
Sponsored by:	iXsystems

1 files changed, 92 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
index 147cd93532..ff3644025d 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
@@ -1067,6 +1067,98 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	</listitem>
       </orderedlist>
     </sect2>
+
+    <sect2 xml:id="stable">
+      <title>Using &os.stable;</title>
+
+      <para>&os.stable; is the development branch from which major
+	releases are made.  Changes go into this branch at a slower
+	pace and with the general assumption that they have first been
+	tested in &os.current;.  This is <emphasis>still</emphasis> a
+	development branch and, at any given time, the sources for
+	&os.stable; may or may not be suitable for general use.  It is
+	simply another engineering development track, not a resource
+	for end-users.  Users who do not have the resources to perform
+	testing should instead run the most recent release of
+	&os;.</para>
+
+      <para>Those interested in tracking or contributing to the &os;
+	development process, especially as it relates to the next
+	release of &os;, should consider following &os.stable;.</para>
+
+      <para>While the &os.stable; branch should compile and run at all
+	times, this cannot be guaranteed.  Since more people run
+	&os.stable; than &os.current;, it is inevitable that bugs and
+	corner cases will sometimes be found in &os.stable; that were
+	not apparent in &os.current;.  For this reason, one should not
+	blindly track &os.stable;.  It is particularly important
+	<emphasis>not</emphasis> to update any production servers to
+	&os.stable; without thoroughly testing the code in a
+	development or testing environment.</para>
+
+      <para>To track &os.stable;:</para>
+
+      <indexterm>
+	<primary>-STABLE</primary>
+	  <secondary>using</secondary>
+      </indexterm>
+      <orderedlist>
+	<listitem>
+	  <para>Join the &a.stable.name; list in order to stay
+	    informed of build dependencies that may appear in
+	    &os.stable; or any other issues requiring special
+	    attention.  Developers will also make announcements in
+	    this mailing list when they are contemplating some
+	    controversial fix or update, giving the users a chance to
+	    respond if they have any issues to raise concerning the
+	    proposed change.</para>
+
+	  <para>Join the relevant <application>svn</application> list
+	    for the branch being tracked.  For example, users
+	    tracking the 9-STABLE branch should join the
+	    &a.svn-src-stable-9.name; list.  This list records the
+	    commit log entry for each change as it is made, along
+	    with any pertinent information on possible
+	    side effects.</para>
+
+	  <para>To join these lists, go to &a.mailman.lists.link;,
+	    click on the list to subscribe to, and follow the
+	    instructions.  In order to track changes for the whole
+	    source tree, subscribe to &a.svn-src-all.name;.</para>
+	</listitem>
+
+	<listitem>
+	  <para>To install a new &os.stable; system, install the most
+	    recent &os.stable; release from the <link
+	      linkend="mirrors">&os; mirror sites</link> or use a
+	    monthly snapshot built from &os.stable;.  Refer to <link
+	      xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots</link>
+	    for more information about snapshots.</para>
+
+	  <para>To compile or upgrade to an existing &os; system to
+	    &os.stable;, use <link linkend="svn">svn</link>
+	      <indexterm>
+		<primary>Subversion</primary>
+	      </indexterm> to check out the source for the desired
+	    branch.  Branch names, such as
+	    <literal>stable/9</literal>, are listed at <link
+	      xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Before compiling or upgrading to &os.stable;
+	    <indexterm>
+	      <primary>-STABLE</primary>
+		<secondary>compiling</secondary>
+	    </indexterm>, read <filename>/usr/src/Makefile</filename>
+	    carefully and follow the instructions in <xref
+	      linkend="makeworld"/>.  Read the &a.stable; and
+	    <filename>/usr/src/UPDATING</filename> to keep up-to-date
+	    on other bootstrapping procedures that sometimes become
+	    necessary on the road to the next release.</para>
+	</listitem>
+      </orderedlist>
+    </sect2>
   </sect1>
 
   <sect1 xml:id="makeworld">