From fea803df3de147ea1d31f016a6bc9e29667bc788 Mon Sep 17 00:00:00 2001
From: Mark Linimon <linimon@FreeBSD.org>
Date: Thu, 27 Oct 2011 09:05:07 +0000
Subject: [PATCH] Add a how-to on creating a new branch with the new codebase. 
 While here, add some notes about how to delete out-of-support branches.

---
 .../articles/portbuild/article.sgml           | 80 +++++++++++++++++--
 1 file changed, 74 insertions(+), 6 deletions(-)

diff --git a/en_US.ISO8859-1/articles/portbuild/article.sgml b/en_US.ISO8859-1/articles/portbuild/article.sgml
index ff8333df98..30764f0907 100644
--- a/en_US.ISO8859-1/articles/portbuild/article.sgml
+++ b/en_US.ISO8859-1/articles/portbuild/article.sgml
@@ -2088,30 +2088,64 @@ ssh_cmd="/usr/local/bin/ssh"
 
     <itemizedlist>
       <listitem>
-	<para>Create a new <application>zfs</application> filesystem
+	<para>(new codebase) Edit <filename>/var/portbuild/conf/server.conf</filename>
+	  with the following changes:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>Add <replaceable>new-branch</replaceable> to
+	      <makevar>SRC_BRANCHES</makevar>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>For what was previously head, change
+	      <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_TAG</makevar> to
+	      <literal>RELENG_<replaceable>branch</replaceable>_0</literal>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Add
+	      <makevar>SRC_BRANCH_<replaceable>new-branch</replaceable>_TAG</makevar>
+	      <literal>=.</literal>.</para>
+	  </listitem>
+	</itemizedlist>
+      </listitem>
+
+      <listitem>
+	<para>(new codebase) Run <command>
+/var/portbuild/updatesnap</command> manually.</para>
+      </listitem>
+
+      <listitem>
+	<para>(Only for old codebase)
+	  Create a new <application>zfs</application> filesystem
 	  for sources:
 	  <screen>zfs create a/snap/src-<replaceable>branch</replaceable></screen>
 	</para>
       </listitem>
 
       <listitem>
-	<para>Checkout a <literal>src</literal> tree in the new filesystem:
+	<para>(Only necessary for old codebase):
+	  Checkout a <literal>src</literal> tree in the new filesystem:
 	  <screen>cvs -Rq -d /r/ncvs co -d src-<replaceable>branch</replaceable>-r RELENG_<replaceable>branch</replaceable></screen>
 	</para>
       </listitem>
 
       <listitem>
-	<para>Edit the master copy of
+	<para>(Only necessary for old codebase):
+	  Edit the master copy of
 	  <filename>Tools/portbuild/portbuild.conf</filename>.</para>
       </listitem>
 
       <listitem>
-	<para>For each arch, edit its copy of the above in
+	<para>(Only necessary for old codebase):
+	  For each arch, edit its copy of the above in
 	  <filename>/var/portbuild/<replaceable>arch</replaceable>/portbuild.conf</filename>.</para>
       </listitem>
 
       <listitem>
-	<para>Edit <filename>/var/portbuild/scripts/buildenv</filename>.</para>
+	<para>(Only necessary for old codebase):
+	  Edit <filename>/var/portbuild/scripts/buildenv</filename>.</para>
       </listitem>
 
       <listitem>
@@ -2122,7 +2156,8 @@ ssh_cmd="/usr/local/bin/ssh"
       </listitem>
 
       <listitem>
-	<para>Modify <makevar>HEAD_BRANCH</makevar> and
+	<para>(Only necessary for old codebase):
+	  Modify <makevar>HEAD_BRANCH</makevar> and
 	  <makevar>NON_HEAD_BRANCHES</makevar> in
 	  <filename>/var/portbuild/scripts/updatesnap</filename>.</para>
       </listitem>
@@ -2159,6 +2194,39 @@ ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/build
     </itemizedlist>
   </sect1>
 
+  <sect1 id="old-branch">
+    <title>How to delete an unsupported &os; branch</title>
+
+    <para>When an old branch goes out of support, there are some
+      things to garbage-collect.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>(new codebase) Edit <filename>/var/portbuild/conf/server.conf</filename>
+	  with the following changes:</para>
+	  <itemizedlist>
+	    <listitem>
+	      <para>Delete <replaceable>new-branch</replaceable> from
+		<makevar>SRC_BRANCHES</makevar>.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>Delete
+		<makevar>SRC_BRANCH_<replaceable>old-branch</replaceable>_TAG</makevar>
+		<literal>=<replaceable>whatever</replaceable></literal></para>
+	    </listitem>
+	  </itemizedlist>
+      </listitem>
+
+      <listitem>
+	<para>(both):
+<command>umount a/snap/src-<replaceable>old-branch</replaceable>/src;
+umount a/snap/src-<replaceable>old-branch</replaceable>;
+zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></command></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
   <sect1 id="new-arch">
     <title>How to configure a new architecture</title>