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

Add documentation about the Ports Management (portmgr) team.

Browse source 
policies.sgml gathers together the various policies that portmgr has
promulgated in the past to try to assure the integrity of the Ports
Collection.  It is indexed more-or-less in order of the responsibilities
listed in charter.sgml.

qa.sgml explains the work that portmgr does for Quality Assurance (QA)
for the ports collection, both during and between release cycles, to
help increase the visibility of its role.

The portmgr team requests that they be allowed a courtesy review of any
proposed changes to these files.
This commit is contained in:
Mark Linimon 2005-03-12 07:30:25 +00:00
parent 7b7912487d
commit 280592133a
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/www/; revision=24064
4 changed files with 530 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
en/portmgr/Makefile Normal file
View file

@ -0,0 +1,12 @@
# $FreeBSD$
.if exists(../Makefile.conf)
.include "../Makefile.conf"
.endif
.if exists(../Makefile.inc)
.include "../Makefile.inc"
.endif
DOCS?= index.sgml charter.sgml policies.sgml qa.sgml
.include "${WEB_PREFIX}/share/mk/web.site.mk"

114
en/portmgr/index.sgml Normal file
View file

@ -0,0 +1,114 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY email 'portmgr'>
<!ENTITY title "Ports Management Team">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
<!ENTITY % developers SYSTEM "../developers.sgml"> %developers;
<!ENTITY contact.re '<a href="mailto:re@FreeBSD.org">re@FreeBSD.org</a>'>
<!ENTITY contact.so '<a href="mailto:security-officer@FreeBSD.org">security-officer@FreeBSD.org</a>'>
<!ENTITY contact.portmgr '<a href="mailto:portmgr@FreeBSD.org">portmgr@FreeBSD.org</a>'>
]>
<html>
&header;
<p>The FreeBSD Ports Management Team (also known as <tt>portmgr</tt>
due to its email alias) is responsible for issues relating to the
<a href="http://www.FreeBSD.org/ports">FreeBSD Ports Collection</a>.</p>
<h3><a href="charter.html">Charter</a></h3>
<p>Discusses the goals, rights, and responsibilities of the team.
The contents of this document are (XXX to be) approved by the FreeBSD
Core Team.</p>
<h3><a href="policies.html">Policies</a></h3>
<p>Discusses current policies that the team has adopted to meet
its goals.</p>
<h3><a href="qa.html">Quality Assurance Activities</a></h3>
<p>A behind-the-scenes look at the efforts that are made to ensure that
the Ports Collection works as well as it possibly can.</p>
<h3>Team Members</h3>
<p><a href="mailto:portmgr@FreeBSD.org">portmgr@FreeBSD.org</a>:
&a.kris;, &a.marcus;, &a.linimon;, &a.eik;, &a.krion;</p>
<p>Secretary: <!-- missing: &a.erwin; -->Erwin Lansing</p>
<h3>Related Documentation</h3>
<ul>
<li>
<p><a href="&base;/doc/en_US.ISO8859-1/books/porters-handbook/index.html">
FreeBSD Porter's Handbook</a><br>
<small>A general guide for FreeBSD ports committers, including both
technical information and policy guidelines.</small></p>
</li>
<!-- future document: "Rights And Responsibilities of FreeBSD Ports
Maintainers and Committers" -->
<li>
<p><a href="http://pointyhat.FreeBSD.org">FreeBSD Ports Build
Cluster</a><br>
<small>These machines continually build packages on all possible
combinations of OS release and CPU architecture (in our terminology,
<tt>build environments</tt>), and produce error logs of problems
that are encountered along the way.</small></p>
</li>
<li>
<p><a
href="&base;/doc/en_US.ISO8859-1/articles/portbuild/index.html">
FreeBSD Package Building Procedures</a><br>
<small>Describes the technical operation of the build cluster.</small>
</p>
</li>
<li>
<p><a
href="&base;/doc/en_US.ISO8859-1/articles/releng-packages/index.html">
FreeBSD Release Engineering for Third Party Packages</a><br>
<small>Describes the approach used by the FreeBSD release
engineering team to produce a high quality package set
suitable for official FreeBSD release media, with specific
emphasis on how to split up the packages for the release
media, and how to verify that a package set is
consistent.</small></p>
</li>
<!-- arguably the following should be added here:
portsmon; FreshPorts; fenner's list; PR statistics; GNATS -->
<li>
<p><a
href="&base;/doc/en_US.ISO8859-1/articles/committers-guide/index.html">
FreeBSD Committer's Guide</a><br>
<small>Includes a discussion of policies and issues that are particular
interest to committers to the ports tree.</small></p>
</li>
<li>
<p><a href="&base;/doc/en_US.ISO8859-1/books/pr-guidelines/index.html">
Problem Report Handling Guidelines</a><br>
<small>While primarily aimed at FreeBSD committers, this should
also be read by users interested in how best to attract attention
to their PRs.</small></p>
</li>
</ul>
&footer;
</body>
</html>

215
en/portmgr/policies.sgml Normal file
View file

@ -0,0 +1,215 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "Charter for the Ports Management Team">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<html>
&header;
<p>In accordance with its <a href="charter.html">Charter</a>, the
Ports Management Team has adopted certain policies to try to meet
each of its goals.</p>
<h3>Assure The Integrity Of The Ports Collection</h3>
<p>To help assure the integrity of the Ports Collection, portmgr
acts as sole committer for certain files that are integral to it,
such as <tt>bsd.port.mk</tt>. Since the ports tree is not
branched (unlike some of the other BSD projects), any fatal
error in these files will be quickly picked up by the many
users who run automated updates of their ports.</p>
<p>portmgr also runs periodic builds of proposed large changes to the
Ports Collection on a dedicated area of the automated
<a href="http://pointyhat.FreeBSD.org">ports building cluster</a>.
Examples of changes that should be tested here before committing
include:</p>
<ul>
<li><p>changes to <tt>bsd.port.mk</tt></p></li>
<li><p>changes to packages with many dependencies, including
X11 servers, GNOME, KDE, 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>Again, since the ports CVS tree is not branched, any large-scale
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>
<p>portmgr reserves the right to act as final arbiter of other
commits in certain unusual cases, such as: commits that in their
opinion destabilize the Ports Collection; violate POLA (the
Principle Of Least Astonishment) for FreeBSD's users; or in cases
of inter-committer disputes that can not be solved among the
committers themselves.</p>
<h3>Maintain The Automated <a href="http://pointyhat.FreeBSD.org">
Ports Building Cluster</a></h3>
<p>portmgr maintains a set of machines that automatically build
packages on combinations of FreeBSD source tree versus CPU
architecture (in our terminology, <tt>build environments</tt> or
<tt>buildenv</tt>s). Where license distribution permits, the
resulting packages are regularly uploaded to the main FTP mirror
as the "new latest package" so that they are available for download
by FreeBSD users. Port build failures are reported to the responsible
maintainers and/or committers for the appropriate corrective action.</p>
<p>In some cases ports may become broken by changes to the FreeBSD base
system (src/ tree). In such a case, the Ports Management Team expects
the responsible Source Committer to develop fixes to the affected ports,
in consultation with the relevant port maintainers.</p>
<h3>Work With The FreeBSD Security Team</h3>
<!-- nothing specific; the header is left to cross-reference the charter -->
<h3>Work with FreeBSD Ports and Documentation Committers</h3>
<p>portmgr will attempt to help keep the
<a href="&base;/doc/en_US.ISO8859-1/books/porters-handbook/index.html">
FreeBSD Porter's Handbook</a> up to date with what it believes to be
the "best practices" for individual ports.</p>
<p>(The intent is not just to lay down 'rules' but to say 'here is
why something that we advocate as The Right Thing in the ports
Makefiles is done.' In particular, there are a number of
"edge cases" that <tt>bsd.*.mk</tt> has some very convoluted
code to handle -- such as ensuring that ports can be installed
from CDROM, over NFS, and so forth -- and failing to understand
these issues can lead to maintainers using shortcuts that will
not work in these edge cases.)</p>
<p>portmgr is not the sole owner of the Porter's Handbook, as it is
actually in the <tt>doc/</tt> tree. We welcome PR submitters and
<tt>doc</tt> committers to work on it to add documentation that helps
to clarify existing practice. However, we would like to request,
as a courtesy, the right to review any changes that would seem to
change existing practice.</p>
<p>In addition, there has been recent discussion about creating a
"Rights And Responsibilities of FreeBSD Ports Maintainers and Committers"
document. portmgr supports this effort and looks forward to being
able to review any drafts.</p>
<p>portmgr also is responsible for certain other documentation such
as ports-specific portions of the Committer's Guide.</p>
<h3>Respect The Legal Rights Of Authors Whose Works Are Installed Via
The Ports Collection</h3>
<p>To the extent possible with a volunteer project, portmgr will work
to ensure that the legal rights of authors whose works are installed
via the Ports Collection are respected. This includes making sure that
the appropriate entries are made to <tt>ports/LEGAL</tt> and to
the <tt>makevars</tt> that control package building and thus automated
distribution of binaries.</p>
<p>In rare cases this may also require removing a port and all distfiles
and binaries if the original author demands it.</p>
<p>portmgr asks our volunteer committers to carefully consider authors'
licensing restrictions when committing new ports, since it is infeasible
for the members of portmgr to do so themselves due to the huge number
of ports.</p>
<h3>Act As Arbiter Of First Resort For Disputes Between FreeBSD
Community Members Such As Maintainers And Committers</h3>
<p>portmgr encourages members of the FreeBSD community to work
together in accordance with the principles set out in the
Committer's Guide. In case of disputes, it reserves the right
to abitrate, subject to review by the Core Team.</p>
<h3>Manage CVS Commit Access To The Ports Tree</h3>
<p>The FreeBSD Core Team has delegated the responsibility to manage
CVS commit access to the <tt>ports/</tt> tree to portmgr. Core
reviews granting and revocation of commit bits and has final
authority over the entire FreeBSD CVS repository.</p>
<p>New Ports Committers are proposed by an existing Ports Committer
who wishes to act as a mentor. The proposals should include a brief
summary of the history of contributions made by the proposed new
committer such as number of PRs submitted, number of ports currently
maintained, and existing commit bits in other trees, if any.</p>
<p>In its votes the team will consider that history as well as any other
relevant factors. The results of the votes are made available to
the FreeBSD developer community.</p>
<p>In accordance with practice elsewhere in the project, inactive
Ports Committers are periodically contacted to enquire about
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
negative, have their commit bits reclaimed for safekeeping.
Currrently, this period is one year.</p>
<p>In unusual cases it may become necessary to remove Ports Committers
for other reasons. This will only be done after serious deliberation,
and is subject to review by Core.</p>
<h3>Establish Guidelines And Policies Governing The Rights And
Responsibilities Of Ports Committers And Maintainers</h3>
<p>portmgr has the responsibility to establish guidelines and policies
governing the rights and responsibilities of Ports Committers and
maintainers, such as expected standards of maintainership, conditions
under which maintainers may be overridden or removed, and other
policies.</p>
<p>To ensure that ports Problem Reports are handled in a timely
manner, portmgr has established a guideline about how long a PR
assigned to a committer may remain open before being eligible for
being committed by another committer via a "maintainer timeout".
Currently this is set at two weeks (not counting ports freezes and
generally recognized holidays.)</p>
<p>In addition, to ensure that ports are maintained in a timely
fashion, portmgr has established a guideline about how long a port
maintainer may be inactive before forfeiting maintainership.
"inactive" is not interpreted strictly, but is intended to encompass
such things as unresolved open PRs, commits made by others via
maintainer timeouts, and unresolved build problems. Currently this
is defined to be three months.</p>
<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
Collection undergoes rapid development that is outside FreeBSD's
control. Part of the responsibility that a ports maintainer
accepts is to try to keep a port working and as up-to-date as
feasible. It is unfair to our users to let unfixed problems
languish and stale versions remain. However, we also recognize
that all of our maintainers and committers are volunteers just
as we are, and that as with any volunteer project, it is easy to
overcommit, or lose interest in a particular port.</p>
<p>Maintainers and committers who feel overcommitted or have lost
interest in any particular port should feel free to ask for new
volunteers and/or reassignment of the port back to the general
pool. Not only will this help keep the Ports Collection current,
but hopefully will help prevent volunteer burnout.</p>
<h3>Help Prioritize Future Directions For The Overall Ports Collection</h3>
<p>portmgr recognizes that the development and evolution of the Ports
Collection is primarily driven by the work of community members.
However, due to the unbranched nature of the Ports Collection,
it is sometimes necessary to coordinate, or even choose among, any
proposed changes.</p>
<p>To some extent this involves choosing which patches are adopted
for testing on the build cluster, but it also involves such issues
as working to build consensus over architectural decisions,
creating lists of "interesting projects", and so forth.</p>
&footer;
</body>
</html>

189
en/portmgr/qa.sgml Normal file
View file

@ -0,0 +1,189 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "Quality Assurance Tasks for the Ports Management Team">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<html>
&header;
<p>There are a number of tasks that the Ports Management Team undertakes
to try to improve the quality of the Ports Collection. These fall into
two main categories:
<a href="#qa-before-release">activities during a release cycle</a> and
<a href="#qa-between-releases">activities between release cycles</a>.
</p>
<h3><a name="qa-before-release">Activities During a Release Cycle</a></h3>
<ul>
<li>
<p>Work with the
<a href="../releng/index.html">Release Engineering Team</a>
to coordinate the release schedule.</p>
</li>
<li>
<p>Work with the RE team to determine which pre-built packages
can be included on the default install ISOs.</p>
</li>
<li>
<p>Manage commits to the CVS tree for package builds via the
following steps:</p>
<ol>
<li>
<p>Institute a freeze and produce packages for all the
appropriate architectures. Often this process has to be
repeated because either bugs are identified in various ports,
or changes to the src tree create a risk that the packages
that have already been built would not work with those
changes.</p>
<p>Although the freeze is advisory (not enforced through
CVS), committers are asked to respect the freeze so that
the package builds can be consistent and correct, and
instead clear all proposed changes through portmgr. The
changes that are generally approved are:</p>
<ul>
<li><p>fixes to make a package build at all;</p></li>
<li><p>security fixes to critical packages;</p></li>
<li><p>problems that are noticed with licensing issues.</p></li>
</ul>
<p>Unfortunately, due to the sheer size of the Ports Collection
and the speed that applications are developed, it is
impossible to fix every single problem for a release.</p>
</li>
<li>
<p>The tree is then locked for all commits and a CVS tag is laid
down.</p>
</li>
<li>
<p>The tree is then unlocked and a <tt>slush</tt> is
announced. The intent of this state is to allow routine
changes to be made to the Ports Collection, but with the note
that these changes will not ship on the release ISOs. Commits
that should be avoided are such things as:</p>
<ul>
<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
of show-stopper problem is found (either security- or license-
related) such that we need to make a change that can go on
the release ISOs, we will need to slip the CVS tag on the
changed file(s). By allowing unlimited commits, the risk is
high that any such change would involve having to recreate all
the packages all over again, resulting in an endless release
cycle.</p>
</li>
</ol>
<p>Only once the RE team and portmgr are happy with the final
state of the release ISOs is the ports tree completely available
for commits again.</p>
</li>
</ul>
<h3><a name="qa-between-releases">Activities Between Release Cycles</a></h3>
<ul>
<li>
<p>Manage the <a href="http://pointyhat.FreeBSD.org">Ports Build
Cluster</a> machines. These machines continually build packages
on all possible combinations of OS release and CPU architecture
(in our terminology, <tt>build environments</tt>.)</p>
<p>These builds also produce error logs for packages that do not
build correctly (see the above URL). Periodically, the team
marks these ports as BROKEN so that maintainers may be notified.
(See below.)</p>
<p>Successfully built packages (at least, the ones that are freely
redistributable) are also copied to the master FTP server and thus
become the default &quot;latest package&quot; for installations
that use packages rather than ports.</p>
</li>
<li>
<p>Notify the FreeBSD community of problems within the Ports
Collection so that problems do not get overlooked. To do this,
there are a number of emailed reports. Ones marked
<tt>public</tt> are posted to freebsd-ports.</p>
<ul>
<li><p>a public list of all ports to be removed due to security
problems, build failures, or general obsolescence, unless they
are fixed first.</p></li>
<li><p>private email to all maintainers of the affected ports
(including ports dependent on the above).</p></li>
<li><p>private email to all maintainers of ports that are already
marked BROKEN and/or FORBIDDEN.</p></li>
<li><p>private email to maintainers who are not committers, who have
PRs filed against their ports (to flag PRs that might never have
been Cc:ed to them).</p></li>
<li><p>public email about port commits that break building of
INDEX.</p></li>
<li><p>public email about port commits that send the revision
metadata backwards (and thus confuse tools like portupgrade).</p></li>
<li><p>a public list of all ports that have at least one file
that fails to fetch from any non-FreeBSD mastersite. For the
complete list of results for all files versus all mastersites,
see <a href="http://people.FreeBSD.org/~fenner/portsurvey/">
Bill Fenner's port survey</a>.</p></li>
<li><p>private email to an affected port maintainer when a port
is about to be marked BROKEN, Cc:ed to the last committer to
the port. (This email is not automated but it should be sent
as a courtesy.)</p></li>
<li><p>a list of ports that do not set NO_LATEST_LINK. (Ports
that have a stable version, and a development version, will
generally have the development version set to a later revision.
If it is desireable that users should install the stable version
from packages, rather than the development version, this flag
should be set; otherwise, users will get the latest version by
default.)</p></li>
</ul>
</li>
<li>
<p>Remove expired ports. Ports that have been marked BROKEN for
some time are marked DEPRECATED (with an EXPIRATION_DATE) and then
are removed if no one has fixed them by that time. The intent of
this this process is to try to insure that if a user installs a port,
there is the best possible change that it can be made to work.</p>
<p>In other cases, ports are marked DEPRECATED when they have been
replaced by a newer version and the older version is no longer
maintained by the authors. The EXPIRATION_DATE should generally
be set at least two months in the future to allow everyone sufficient
time to upgrade.</p>
</li>
</ul>
&footer;
</body>
</html>