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
Download patch file Download diff file Expand all files Collapse all files

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>