Date: Wed, 9 Mar 2011 01:15:53 GMT From: Eitan Adler <eadler@FreeBSD.org> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/155391: [patch] add notes about the doc slush to the committer handbook Message-ID: <201103090115.p291Fr5B053485@red.freebsd.org> Resent-Message-ID: <201103090120.p291K7rj020100@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201103090115.p291Fr5B053485>