diff --git a/en/portmgr/Makefile b/en/portmgr/Makefile index f5def09fba..89205a1c35 100644 --- a/en/portmgr/Makefile +++ b/en/portmgr/Makefile @@ -1,12 +1,18 @@ -# $FreeBSD$ +# $FreeBSD: www/en/portmgr/Makefile,v 1.1 2005/03/12 07:30:25 linimon Exp $ .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 +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" diff --git a/en/portmgr/implementation.sgml b/en/portmgr/implementation.sgml new file mode 100644 index 0000000000..1f29d72cac --- /dev/null +++ b/en/portmgr/implementation.sgml @@ -0,0 +1,120 @@ + + + + %navincludes; + %includes; +]> + + +&header; + +

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:

+ + + +

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.

+ + + +

The following do not fall into the above category:

+ + + +

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

+ +&footer; + + diff --git a/en/portmgr/index.sgml b/en/portmgr/index.sgml index 21ad91e139..58ae6cf172 100644 --- a/en/portmgr/index.sgml +++ b/en/portmgr/index.sgml @@ -1,147 +1,158 @@ - + %navincludes; %includes; %developers; re@FreeBSD.org'> security-officer@FreeBSD.org'> portmgr@FreeBSD.org'> ]> &header;

The FreeBSD Ports Management Team (also known as portmgr due to its email alias) is responsible for issues relating to the FreeBSD Ports Collection.

Charter

Discusses the goals, rights, and responsibilities of the team. The contents of this document are approved by the FreeBSD Core Team.

Policies

Discusses current policies that the team has adopted to meet -its goals.

+its goals, such as +timeouts for inactivity and +when commits are allowed.

+ +

Implementation Issues

+ +

Discusses how that the way that the Ports Collection is implemented +affects the above policies, and, in particular, such concepts as + +changes that require regression tests +and +sweeping changes.

Quality Assurance Activities

A behind-the-scenes look at the efforts that are made to ensure that the Ports Collection works as well as it possibly can.

Team Members

portmgr@FreeBSD.org: &a.portmgr;

Secretary: &a.erwin;

Resources Of Interest To FreeBSD Contributors and Developers

Resources Of General Interest

&footer; diff --git a/en/portmgr/policies.sgml b/en/portmgr/policies.sgml index a4da0ec7e3..4a772d0607 100644 --- a/en/portmgr/policies.sgml +++ b/en/portmgr/policies.sgml @@ -1,216 +1,229 @@ - + %navincludes; %includes; ]> &header;

In accordance with its Charter, the Ports Management Team has adopted certain policies to try to meet each of its goals.

Assure The Integrity Of The Ports Collection

To help assure the integrity of the Ports Collection, portmgr acts as sole committer for certain files that are integral to it, such as bsd.port.mk. 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.

portmgr also runs periodic builds of proposed large changes to the Ports Collection on a dedicated area of the automated ports building cluster. Examples of changes that should be tested here before committing include:

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.

+

At other times, especially during the preparations for a new release, + there are + other restrictions on when commits are allowed.

+

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.

Maintain The Automated Ports Building Cluster

portmgr maintains a set of machines that automatically build packages on combinations of FreeBSD source tree versus CPU architecture (in our terminology, build environments or buildenvs). 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.

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.

Work With The FreeBSD Security Team

Work with FreeBSD Ports and Documentation Committers

portmgr will attempt to help keep the FreeBSD Porter's Handbook up to date with what it believes to be the "best practices" for individual ports.

(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 bsd.*.mk 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.)

portmgr is not the sole owner of the Porter's Handbook, as it is actually in the doc/ tree. We welcome PR submitters and doc 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.

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.

-

portmgr also is responsible for certain other documentation such - as ports-specific portions of the Committer's Guide.

+

portmgr also is responsible for certain other documentation such as the + + ports-specific portions of the Committer's Guide and the + + Contributing to the FreeBSD Ports Collection article.

Respect The Legal Rights Of Authors Whose Works Are Installed Via The Ports Collection

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 ports/LEGAL and to the makevars that control package building and thus automated distribution of binaries.

In rare cases this may also require removing a port and all distfiles and binaries if the original author demands it.

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.

Act As Arbiter Of First Resort For Disputes Between FreeBSD Community Members Such As Maintainers And Committers

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.

Manage CVS Commit Access To The Ports Tree

The FreeBSD Core Team has delegated the responsibility to manage CVS commit access to the ports/ tree to portmgr. Core reviews granting and revocation of commit bits and has final authority over the entire FreeBSD CVS repository.

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.

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.

In accordance with practice elsewhere in the project, inactive - Ports Committers are periodically contacted to enquire about + 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.

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.

Establish Guidelines And Policies Governing The Rights And Responsibilities Of Ports Committers And Maintainers

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.

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

+ being committed by another committer via a + "maintainer timeout". + 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.

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

+ maintainer timeouts, and unresolved build problems.

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.

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.

Help Prioritize Future Directions For The Overall Ports Collection

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.

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.

&footer; diff --git a/en/portmgr/policies_committing.sgml b/en/portmgr/policies_committing.sgml new file mode 100644 index 0000000000..783c4ff58c --- /dev/null +++ b/en/portmgr/policies_committing.sgml @@ -0,0 +1,48 @@ + + + + %navincludes; + %includes; +]> + + +&header; + +

These are the specific policies that the Ports Management Team has + adopted regarding commits to the ports tree.

+ +

Changes to bsd.port.mk

+ +

portmgr acts as sole committer for bsd.port.mk at all times. +Proposed changes must be submitted as PRs and assigned to portmgr.

+ +

Changes when the tree is open

+ +

Open to everything that would not + require a + regression test.

+ +

Changes when the tree is frozen

+ +

All changes must be approved by portmgr. In general, only + the following will be accepted:

+ + + +

Changes when the tree is thawed

+ +

No sweeping changes. +This is to prevent possibly having to rebuild all the release packages.

+ +&footer; + + diff --git a/en/portmgr/policies_contributors.sgml b/en/portmgr/policies_contributors.sgml new file mode 100644 index 0000000000..2dfbbb6f66 --- /dev/null +++ b/en/portmgr/policies_contributors.sgml @@ -0,0 +1,51 @@ + + + + %navincludes; + %includes; +]> + + +&header; + +

These are the time periods that apply to maintainer and committer +responses to issues brought to their attention via email.

+ + +

Problem Report (PR) Timeouts

+ +

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.

+ +

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.

+ + +

Maintainer Reset

+ +

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.

+ +

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

+ + +

Commit Privileges

+ +

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.

+ +&footer ; + + diff --git a/en/portmgr/qa.sgml b/en/portmgr/qa.sgml index b3819a0872..02c43ec79d 100644 --- a/en/portmgr/qa.sgml +++ b/en/portmgr/qa.sgml @@ -1,188 +1,181 @@ - + %navincludes; %includes; ]> &header;

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: activities during a release cycle and activities between release cycles.

Activities During a Release Cycle

Activities Between Release Cycles

&footer;