os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Refactor these pages and add new text about the following:

Browse source 
- implementation details of the Ports Collection.  This is necessary
   background to understand why certain policy decisions have been made.

 - definitions and clarification of policies for maintainer timeouts,
   "sweeping changes", and related matters.  This text has been separated
   out into smaller pages (policies_*) for easier reference.

Reviewed by:	portmgr team
This commit is contained in:
Mark Linimon 2005-12-15 01:10:43 +00:00
parent 7eab8c769a
commit edc8db8f30
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/www/; revision=26602
7 changed files with 268 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
en/portmgr/Makefile
View file

@ -1,4 +1,4 @@
# $FreeBSD$ # $FreeBSD: www/en/portmgr/Makefile,v 1.1 2005/03/12 07:30:25 linimon Exp $
.if exists(../Makefile.conf) .if exists(../Makefile.conf)
.include "../Makefile.conf" .include "../Makefile.conf"
@ -7,6 +7,12 @@
.include "../Makefile.inc" .include "../Makefile.inc"
.endif .endif
DOCS?= index.sgml charter.sgml policies.sgml qa.sgml DOCS?= index.sgml
DOCS+= charter.sgml
DOCS+= implementation.sgml
DOCS+= policies.sgml
DOCS+= policies_committing.sgml
DOCS+= policies_contributors.sgml
DOCS+= qa.sgml
.include "${WEB_PREFIX}/share/mk/web.site.mk" .include "${WEB_PREFIX}/share/mk/web.site.mk"

120
en/portmgr/implementation.sgml Normal file
View file

@ -0,0 +1,120 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "Implementation Issues Involving the Ports Collection">
<!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes;
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<html>
&header;
<h3>The Ports Tree Is Not Branched</h3>
<p>Unlike the <tt>src</tt> tree, the FreeBSD ports tree is
<strong>not</strong> branched. It has always been felt that there
are too few volunteers to be able to handle the work of merging
hundreds of changes from the latest tree into various branches.</p>
<h3>Practical Considerations</h3>
<p>There are thousands, if not tens of thousands, of user installations
that track the ports tree on a daily basis, rather than relying on the
packages that shipped with the most current FreeBSD release. Accordingly,
any fatal error in the ports framework will immediately affect all of
these sites. This is why commits to <tt>bsd.port.mk</tt> are only
allowed with portmgr approval. Except in unusual cases, this approval
is only granted after a regression test has been run on a dedicated
area of the automated
<a href="http://pointyhat.FreeBSD.org">ports building cluster</a>.
Typically, a dozen or more proposed changes to the infrastructure are
tested at the same time, and only after a build of the entire ports
tree succeeds will portmgr commit the changes.</p>
<a name="requires_regression_test"></a>
<h3>Changes That Require Regression Tests</h3>
<p>Changes to <tt>bsd.port.mk</tt> are not the only commits that can
have a drastic effect on the tree. We request that any such changes
also be tested on the cluster. Examples of such changes that should
be tested before committing include:</p>
<ul>
<li><p>changes to packages with many dependencies, including
X11 servers, GNOME, KDE, gettext, autotools, and so forth</p></li>
<li><p>changes that change the "accepted best practice" for
ports Makefiles, such as definitions or usage of common make
variables (or <tt>Makevar</tt>s). (e.g. consolidation of
various implementations of USE_*, WITH_*, and so forth)</p></li>
<li><p>large repocopies (such as when an existing port category
is divided up)</p></li>
</ul>
<p>If you are unsure of whether your proposed change will require
a regression test, please send email to portmgr@FreeBSD.org.</p>
<h3>Implications for the Release Cycle</h3>
<p>When a new release of FreeBSD is upcoming, committers are asked to
shift their emphasis away from introducing new ports and features and
instead focus on fixing existing problems. At some time during the
release, the tree is <tt>tagged</tt> and packages are created from
each of the ports, for each of the architectures. Due to the large
number of ports and the speed of the slower architectures, the build
process takes several days.</p>
<p>In an ideal world, these would be the packages that went on the
release CDs, and the time from the creation of the packages to the time
of the actual release would be just long enough to test them and no
longer. However, in practice, problems are found with both the ports
and with the source tree as the QA effort continues. But to be able
to release in a timely manner, only certain port changes will be merged
back into the actual (tagged) tree, and the affected packages will
be rebuilt. Only severe security problems and licensing issues will
have their tags slipped in this manner.</p>
<p>Since the release period can take weeks, it is unrealistic not
to allow any commit to the ports tree during this time. The problem
with allowing unrestricted commits at that time is that it becomes
impossible to separate out only the critical changes so that they,
and only they, can have their affected tags slipped. The terminology
for changes that are not allowed is <tt>sweeping changes</tt>.</p>
<a name="sweeping_changes"></a>
<h3>What Is A Sweeping Change?</h3>
<p>A <tt>sweeping change</tt> is a commit that would affect a non-trivial
number of packages in a way such that any other change (such as fixing a
single security problem) would mean that we would have to rebuild the
entire set of packages, which would delay the upcoming release, possibly
by weeks, because the set of changes overlap.</p>
<p>Here is an incomplete list. If you are unsure that your proposed
change falls into this categorization, you <strong>must</strong>
ask portmgr before committing.</p>
<ul>
<li><p>any commit to <tt>bsd.*.mk</tt></p></li>
<li><p>anything else that would normally require a
<a href="#requires_regression_test">regression test</a></p></li>
<li><p>shared library version bumps</p></li>
<li><p>repocopies involving multiple ports</p></li>
</ul>
<p>The following do not fall into the above category:</p>
<ul>
<li><p>commits to leaf ports (i.e. ports upon which no other port
depends)</p></li>
<li><p>cosmetic changes that would not affect the package (such
as changes to <tt>pkg_descr</tt>)</p></li>
<li><p>new ports</p></li>
<li><p>repocopies of individual ports</p></li>
</ul>
<p>To summarize: the basic test is <strong>will this change affect other
packages?</strong>.</p>
&footer;
</body>
</html>

15
en/portmgr/index.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
<!ENTITY base CDATA ".."> <!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD: www/en/portmgr/index.sgml,v 1.5 2005/10/04 19:43:49 hrs Exp $"> <!ENTITY date "$FreeBSD: www/en/portmgr/index.sgml,v 1.6 2005/10/19 22:43:31 linimon Exp $">
<!ENTITY email 'portmgr'> <!ENTITY email 'portmgr'>
<!ENTITY title "Ports Management Team"> <!ENTITY title "Ports Management Team">
<!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes; <!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes;
@ -27,7 +27,18 @@ Core Team.</p>
<h3><a href="policies.html">Policies</a></h3> <h3><a href="policies.html">Policies</a></h3>
<p>Discusses current policies that the team has adopted to meet <p>Discusses current policies that the team has adopted to meet
its goals.</p> its goals, such as
<a href="policies_contributors.html">timeouts for inactivity</a> and
<a href="policies_committing.html">when commits are allowed</a>.</p>
<h3><a href="implementation.html">Implementation Issues</a></h3>
<p>Discusses how that the way that the Ports Collection is implemented
affects the above policies, and, in particular, such concepts as
<a href="implementation.html#requires_regression_test">
changes that require regression tests</a>
and
<a href="implementation.html#sweeping_changes">sweeping changes</a>.</p>
<h3><a href="qa.html">Quality Assurance Activities</a></h3> <h3><a href="qa.html">Quality Assurance Activities</a></h3>

33
en/portmgr/policies.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA ".."> <!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD: www/en/portmgr/policies.sgml,v 1.2 2005/03/21 02:29:26 linimon Exp $"> <!ENTITY date "$FreeBSD: www/en/portmgr/policies.sgml,v 1.3 2005/10/04 19:43:49 hrs Exp $">
<!ENTITY title "Policies of the Ports Management Team"> <!ENTITY title "Policies of the Ports Management Team">
<!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes; <!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes;
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes; <!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
@ -44,6 +44,10 @@
failures that might be caused by any of the above need to be caught failures that might be caused by any of the above need to be caught
first before a large number of user installations are affected.</p> first before a large number of user installations are affected.</p>
<p>At other times, especially during the preparations for a new release,
there are <a href="policies_committing.html">
other restrictions on when commits are allowed</a>.</p>
<p>portmgr reserves the right to act as final arbiter of other <p>portmgr reserves the right to act as final arbiter of other
commits in certain unusual cases, such as: commits that in their commits in certain unusual cases, such as: commits that in their
opinion destabilize the Ports Collection; violate POLA (the opinion destabilize the Ports Collection; violate POLA (the
@ -100,8 +104,11 @@
document. portmgr supports this effort and looks forward to being document. portmgr supports this effort and looks forward to being
able to review any drafts.</p> able to review any drafts.</p>
<p>portmgr also is responsible for certain other documentation such <p>portmgr also is responsible for certain other documentation such as the
as ports-specific portions of the Committer's Guide.</p> <a href="&base;/doc/en_US.ISO8859-1/articles/committers-guide/ports.html">
ports-specific portions of the Committer's Guide</a> and the
<a href="&base;/doc/en_US.ISO8859-1/articles/contributing-ports/">
Contributing to the FreeBSD Ports Collection</a> article.</p>
<h3>Respect The Legal Rights Of Authors Whose Works Are Installed Via <h3>Respect The Legal Rights Of Authors Whose Works Are Installed Via
The Ports Collection</h3> The Ports Collection</h3>
@ -147,7 +154,9 @@
the FreeBSD developer community.</p> the FreeBSD developer community.</p>
<p>In accordance with practice elsewhere in the project, inactive <p>In accordance with practice elsewhere in the project, inactive
Ports Committers are periodically contacted to enquire about Ports Committers are
<a href="policies_contributors.html#commit_privileges">
periodically contacted</a> to enquire about
their status and interest in continuing to work with the ports tree. their status and interest in continuing to work with the ports tree.
Committers who do not respond to such email, or who respond in the Committers who do not respond to such email, or who respond in the
negative, have their commit bits reclaimed for safekeeping. negative, have their commit bits reclaimed for safekeeping.
@ -169,17 +178,21 @@
<p>To ensure that ports Problem Reports are handled in a timely <p>To ensure that ports Problem Reports are handled in a timely
manner, portmgr has established a guideline about how long a PR manner, portmgr has established a guideline about how long a PR
assigned to a committer may remain open before being eligible for assigned to a committer may remain open before being eligible for
being committed by another committer via a "maintainer timeout". being committed by another committer via a
Currently this is set at two weeks (not counting ports freezes and <a href="policies_contributors.html#pr_timeout">"maintainer timeout"</a>.
generally recognized holidays.)</p> This time period applies to such things as updates that do not require
a regression run; for other updates, please contact portmgr directly.
The time period does not count ports freezes and
generally recognized holidays.</p>
<p>In addition, to ensure that ports are maintained in a timely <p>In addition, to ensure that ports are maintained in a timely
fashion, portmgr has established a guideline about how long a port fashion, portmgr has established a guideline about how long a port
maintainer may be inactive before forfeiting maintainership. maintainer may be inactive before
<a href="policies_contributors.html#maintainer_reset">
forfeiting maintainership</a>.
"inactive" is not interpreted strictly, but is intended to encompass "inactive" is not interpreted strictly, but is intended to encompass
such things as unresolved open PRs, commits made by others via such things as unresolved open PRs, commits made by others via
maintainer timeouts, and unresolved build problems. Currently this maintainer timeouts, and unresolved build problems.</p>
is defined to be three months.</p>
<p>The intent of these policies is not to assign punishment or blame, <p>The intent of these policies is not to assign punishment or blame,
but to reflect the fact that the software installed by the Ports but to reflect the fact that the software installed by the Ports

48
en/portmgr/policies_committing.sgml Normal file
View file

@ -0,0 +1,48 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "Policies of the Ports Management Team: Committing To The Tree">
<!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes;
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<html>
&header;
<p>These are the specific policies that the Ports Management Team has
adopted regarding commits to the ports tree.</p>
<h3>Changes to <tt>bsd.port.mk</tt></h3>
<p>portmgr acts as sole committer for <tt>bsd.port.mk</tt> at all times.
Proposed changes must be submitted as PRs and assigned to portmgr.</p>
<h3>Changes when the tree is open</h3>
<p>Open to everything that would not
<a href="implementation.html#requires_regression_test">require a
regression test</a>.</p>
<h3>Changes when the tree is frozen</h3>
<p>All changes must be approved by portmgr. In general, only
the following will be accepted:</p>
<ul>
<li><p>fixes that would prevent a port from installing or deinstalling
properly for the <strong>upcoming</strong> release.</p></li>
<li><p>security problems. If sufficiently severe, these may imply the
need to create a slipped tag.</p></li>
<li><p>licensing issues. These require a slipped tag.</p></li>
</ul>
<h3>Changes when the tree is thawed</h3>
<p>No <a href="implementation.html#sweeping_changes">sweeping changes</a>.
This is to prevent possibly having to rebuild all the release packages.</p>
&footer;
</body>
</html>

51
en/portmgr/policies_contributors.sgml Normal file
View file

@ -0,0 +1,51 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "Policies of the Ports Management Team: Maintainers and Committers">
<!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes;
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<html>
&header;
<p>These are the time periods that apply to maintainer and committer
responses to issues brought to their attention via email.</p>
<a name="pr_timeout"></a>
<h3>Problem Report (PR) Timeouts</h3>
<p>The time limit for a maintainer to respond to a PR is two weeks.
After that period, if it is a minor change, any ports committer can
commit the change. If it is a major change (e.g. would require a
regression run), please contact portmgr first.</p>
<p>Since GNATS does not automatically notify maintainers of PRs, please
check to see whether or not the maintainer knows about the PR before
declaring a timeout. You can generally tell this from the Audit-Trail
and Cc: lines in the PR.</p>
<a name="maintainer_reset"></a>
<h3>Maintainer Reset</h3>
<p>The time limit for a maintainer to respond to port problems (such
as build errors, PRs, and needed updates) is three months. After that
period, any ports committer can reset the maintainer. If you are
a committer and concerned about whether you are doing the right
thing, please contact portmgr.</p>
<p>This period may be shortened by portmgr if the email address returns
with a hard bounce. In this case, it is probably desirable to reset
all the maintainer's ports and change any PRs set to 'feedback' back
to 'open'.</p>
<a name="commit_privileges"></a>
<h3>Commit Privileges</h3>
<p>The time limit for a committer to keep commit rights within the
ports tree ("commit bit") is one year. portmgr will contact the
committer by email before invoking this limit.</p>
&footer ;
</body>
</html>

17
en/portmgr/qa.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA ".."> <!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD: www/en/portmgr/qa.sgml,v 1.2 2005/08/02 18:24:13 erwin Exp $"> <!ENTITY date "$FreeBSD: www/en/portmgr/qa.sgml,v 1.3 2005/10/04 19:43:49 hrs Exp $">
<!ENTITY title "Quality Assurance Tasks for the Ports Management Team"> <!ENTITY title "Quality Assurance Tasks for the Ports Management Team">
<!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes; <!ENTITY % navincludes SYSTEM "../includes.navabout.sgml"> %navincludes;
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes; <!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
@ -67,17 +67,10 @@ two main categories:
<p>The tree is then unlocked and a <tt>slush</tt> is <p>The tree is then unlocked and a <tt>slush</tt> is
announced. The intent of this state is to allow routine announced. The intent of this state is to allow routine
changes to be made to the Ports Collection, but with the note changes to be made to the Ports Collection, but with the note
that these changes will not ship on the release ISOs. Commits that these changes will not ship on the release ISOs. What
that should be avoided are such things as:</p> we particularly want to avoid is
<a href="implementation.html#sweeping_changes">
<ul> sweeping changes</a>.</p>
<li><p>updates to ports with many dependencies, such as X11
servers, KDE, and GNOME;</p><li>
<li><p>repocopies involving multiple ports;</p><li>
<li><p>and so forth.</p><li>
</ul>
<p>The reason we want to avoid these commits is if some kind <p>The reason we want to avoid these commits is if some kind
of show-stopper problem is found (either security- or license- of show-stopper problem is found (either security- or license-