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