FreeBSD The Power to Serve

Implementation Issues Involving the Ports Collection

The Ports Tree Is Not Branched

Unlike the src tree, the FreeBSD ports tree is not 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.

Practical Considerations

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 bsd.port.mk 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 ports building cluster. 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.

Changes That Require Regression Tests

Changes to bsd.port.mk 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:

  • changes to packages with many dependencies, including X11 servers, GNOME, KDE, gettext, autotools, and so forth

  • changes that change the "accepted best practice" for ports Makefiles, such as definitions or usage of common make variables (or `Makevar`s). (e.g. consolidation of various implementations of USE_*, WITH_*, and so forth)

  • large repocopies (such as when an existing port category is divided up)

If you are unsure of whether your proposed change will require a regression test, please send email to portmgr@FreeBSD.org.

Implications for the Release Cycle

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 tagged 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.

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.

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 sweeping changes.

What Is A Sweeping Change?

A sweeping change 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.

Here is an incomplete list. If you are unsure that your proposed change falls into this categorization, you must ask portmgr before committing.

  • any commit to bsd.*.mk

  • anything else that would normally require a regression test

  • shared library version bumps

  • repocopies involving multiple ports

The following do not fall into the above category:

  • commits to leaf ports (i.e. ports upon which no other port depends)

  • cosmetic changes that would not affect the package (such as changes to pkg_descr)

  • new ports

  • repocopies of individual ports

To summarize: the basic test is will this change affect other packages?.


Last modified on: February 21, 2021 by Danilo G. Baio