docs/155391: [patch] add notes about the doc slush to the committer handbook

Eitan Adler eadler at FreeBSD.org
Wed Mar 9 01:20:08 UTC 2011


>Number:         155391
>Category:       docs
>Synopsis:       [patch] add notes about the doc slush to the committer handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Mar 09 01:20:07 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator:     Eitan Adler
>Release:        
>Organization:
>Environment:
>Description:
The attached patch was discussed on #bsddoc and #bsdports
>How-To-Repeat:

>Fix:


Patch attached with submission follows:

Index: article.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
retrieving revision 1.294
diff -u -r1.294 article.sgml
--- article.sgml	8 Mar 2011 09:47:13 -0000	1.294
+++ article.sgml	9 Mar 2011 00:39:53 -0000
@@ -2803,135 +2803,177 @@
 
 	<qandaentry>
 	  <question>
-	    <para>How long is a ports freeze?</para>
+	    <para>What is a <quote>ports slush</quote> or
+	      <quote>feature freeze</quote>?</para>
 	  </question>
-
-	  <answer>
-	    <para>Usually a week or two.</para>
-	  </answer>
-	</qandaentry>
-
-	<qandaentry>
-	  <question>
-	    <para>What does it mean to me?</para>
-	  </question>
-
 	  <answer>
-	    <para>During the ports freeze, you are not allowed to
-	      commit anything to the tree without explicit approval
-	      from the Ports Management Team.  <quote>Explicit
-	      approval</quote> here means that you send a patch to
-	      the Ports Management Team for review and get a reply
-	      saying, <quote>Go ahead and commit it.</quote> 
+	    <para>
+	      During a release cycle the ports tree may be in a  
+	      <quote>slush</quote> state instead of in a hard freeze.
+	      The goal during a slush is to reach a stable ports tree
+	      to avoid rebuilding large sets of packages for the
+	      release and to tag the tree. During this time
+	      <quote>sweeping changes</quote> are prohibited unless
+	      specifically permitted by portmgr. Complete details
+	      about what consitutes a sweeping change can be found
+	      on the <ulink 
+	      url="&url.base/portmgr/implementation.html">Portmgr
+	      Implementation page</ulink>.
 	    </para>
-
-	    <para>Not everything is allowed to be committed during
-	      a freeze.  Please see the <ulink
-		url="&url.base/portmgr/qa.html">Portmgr Quality
-		Assurance page</ulink> for more information.
-	    </para>
-
-	    <para>Note that you do not have implicit permission to fix
-	      a port during the freeze just because it is
-	      broken.</para>
-	  </answer>
-	</qandaentry>
-
-	<qandaentry>
-	  <question>
-	    <para>How do I know when the ports freeze starts?</para>
-	  </question>
-
-	  <answer>
-	    <para>The ports management team will send out warning
-	      messages to the &a.ports; and &a.committers;
-	      announcing the start of the impending release, usually
-	      two or three weeks in advance.  The exact starting time
-	      will not be determined until a few days before the
-	      actual release.  This is because the ports freeze has to
-	      be synchronized with the release, and it is usually not
-	      known until then when exactly the release will be
-	      rolled.</para>
-
-	    <para>When the freeze starts, there will be another
-	      announcement to the &a.ports; and &a.committers;, of course.</para>
-	  </answer>
-	</qandaentry>
-
-	<qandaentry>
-	  <question>
-	    <para>How do I know when the ports freeze ends?</para>
-	  </question>
-
-	  <answer>
-	    <para>A few hours after the release, the ports management team
-	      will send out a mail to the &a.ports; and &a.committers;
-	      announcing the end of the ports freeze.  Note that the
-	      release being cut does not automatically end the freeze.
-	      We have to make sure there will not be any last minute
-	      snafus that result in an immediate re-rolling of the
-	      release.</para>
+	    <para>
+	      The benefit of using a slush as opposed to a
+	      complete freeze is that allows maintainers to continue 
+	      adding new ports, making routine version updates and 
+	      bug fixes to most existing ports, and otherwise
+	      improving the tree without destabilizing things with
+	      sweeping changes that have effects far beyond the
+	      ports that are changed. For example, updating the
+	      shared library version on a port that many other
+	      ports depend on.
 	  </answer>
 	</qandaentry>
-      </qandadiv>
-
-      <qandadiv>
-	<title>Creating a New Category</title>
 
 	<qandaentry>
 	  <question>
-	    <para>What is the procedure for creating a new category?</para>
+	    <para>How long is a ports freeze or slush?</para>
 	  </question>
 
 	  <answer>
-	    <para>Please see
-	      <ulink url="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES">
-	      Proposing a New Category</ulink> in the Porter's Handbook.
-	      Once that procedure has been followed and the PR has been
-	      assigned to &a.portmgr;, it is their decision whether or
-	      not to approve it.  If they do, it is their responsibility
-	      to do the following:</para>
-
-	    <procedure>
-	      <step>
-		<para>Perform any needed repocopies.  (This only applies
-		  to physical categories.)</para>
-	      </step>
-
-	      <step>
-		<para>Update the <makevar>VALID_CATEGORIES</makevar>
-		  definition in <filename>ports/Mk/bsd.port.mk</filename>.
-		</para>
-	      </step>
-
-	      <step>
-		<para>Assign the PR back to you.</para>
-	      </step>
-	    </procedure>
-	  </answer>
-	</qandaentry>
+	    <para>A freeze only lasts long enough to 
+	      tag the tree. A slush usually lasts a week or two,
+		but may last longer.</para>
+	    </answer>
+	  </qandaentry>
+
+	  <qandaentry>
+	    <question>
+	      <para>What does it mean to me?</para>
+	    </question>
+
+	    <answer>
+	      <para>During a ports freeze, you are not allowed to
+		commit anything to the tree without explicit approval
+		from the Ports Management Team.  <quote>Explicit
+		approval</quote> here means that you send a patch to
+		the Ports Management Team for review and get a reply
+		saying, <quote>Go ahead and commit it.</quote> 
+	      </para>
+
+	      <para>Not everything is allowed to be committed during
+		a freeze.  Please see the <ulink
+		  url="&url.base/portmgr/qa.html">Portmgr Quality
+		  Assurance page</ulink> for more information.
+	      </para>
+
+	      <para>Note that you do not have implicit permission to fix
+		a port during the freeze just because it is
+		broken.
+	      </para>
+		  
+	      <para>During a ports slush, you are still allowed to
+	       commit but must excersise more caution in what you
+	       commit. Furthermore a special note (typically <quote>Feature
+	       Safe: yes</quote>) must be added to the commit message.
+	      </para>
+
+	    </answer>
+	  </qandaentry>
+
+	  <qandaentry>
+	    <question>
+	      <para>How do I know when the ports slush starts?</para>
+	    </question>
+
+	    <answer>
+	      <para>The ports management team will send out warning
+		messages to the &a.ports; and &a.committers;
+		announcing the start of the impending release, usually
+		two or three weeks in advance.  The exact starting time
+		will not be determined until a few days before the
+		actual release.  This is because the ports slush has to
+		be synchronized with the release, and it is usually not
+		known until then when exactly the release will be
+		rolled.</para>
+
+	      <para>When the slush starts, there will be another
+		announcement to the &a.ports; and &a.committers;, of course.</para>
+	    </answer>
+	  </qandaentry>
+
+	  <qandaentry>
+	    <question>
+	      <para>How do I know when the freeze or slush ends?</para>
+	    </question>
+
+	    <answer>
+	      <para>A few hours after the release, the ports management team
+		will send out a mail to the &a.ports; and &a.committers;
+		announcing the end of the ports freeze or slush.  Note that the
+		release being cut does not automatically indicate the end. 
+		We have to make sure there will not be any last minute
+		snafus that result in an immediate re-rolling of the
+		release.</para>
+	    </answer>
+	  </qandaentry>
+	</qandadiv>
+
+	<qandadiv>
+	  <title>Creating a New Category</title>
+
+	  <qandaentry>
+	    <question>
+	      <para>What is the procedure for creating a new category?</para>
+	    </question>
+
+	    <answer>
+	      <para>Please see
+		<ulink url="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES">
+		Proposing a New Category</ulink> in the Porter's Handbook.
+		Once that procedure has been followed and the PR has been
+		assigned to &a.portmgr;, it is their decision whether or
+		not to approve it.  If they do, it is their responsibility
+		to do the following:</para>
 
-	<qandaentry>
-	  <question>
-	    <para>What do I need to do to implement a new physical
-	      category?</para>
-	  </question>
+	      <procedure>
+		<step>
+		  <para>Perform any needed repocopies.  (This only applies
+		    to physical categories.)</para>
+		</step>
 
-	  <answer>
-	    <para>The procedure is a strict superset of the one to
-	      repocopy individual ports (see above).</para>
+		<step>
+		  <para>Update the <makevar>VALID_CATEGORIES</makevar>
+		    definition in <filename>ports/Mk/bsd.port.mk</filename>.
+		  </para>
+		</step>
 
-	      <procedure>
 		<step>
-		  <para>Upgrade each copied port's
-		    <filename>Makefile</filename>.  Do not connect the
-		    new category to the build yet.</para>
+		  <para>Assign the PR back to you.</para>
+		</step>
+	      </procedure>
+	    </answer>
+	  </qandaentry>
 
-		  <para>To do this, you will need to:</para>
-		    <procedure>
-		      <step>
-			<para>Change the port's <makevar>CATEGORIES</makevar>
-			  (this was the point of the exercise, remember?)
+	  <qandaentry>
+	    <question>
+	      <para>What do I need to do to implement a new physical
+		category?</para>
+	    </question>
+
+	    <answer>
+	      <para>The procedure is a strict superset of the one to
+		repocopy individual ports (see above).</para>
+
+		<procedure>
+		  <step>
+		    <para>Upgrade each copied port's
+		      <filename>Makefile</filename>.  Do not connect the
+		      new category to the build yet.</para>
+
+		    <para>To do this, you will need to:</para>
+		      <procedure>
+			<step>
+			  <para>Change the port's <makevar>CATEGORIES</makevar>
+			    (this was the point of the exercise, remember?)
 			  The new category should be listed
 			  <emphasis>first</emphasis>.  This will help to
 			  ensure that the <makevar>PKGORIGIN</makevar>


>Release-Note:
>Audit-Trail:
>Unformatted:



More information about the freebsd-doc mailing list