diff --git a/en/portmgr/Makefile b/en/portmgr/Makefile new file mode 100644 index 0000000000..f5def09fba --- /dev/null +++ b/en/portmgr/Makefile @@ -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" diff --git a/en/portmgr/index.sgml b/en/portmgr/index.sgml new file mode 100644 index 0000000000..bf0570e519 --- /dev/null +++ b/en/portmgr/index.sgml @@ -0,0 +1,114 @@ + + + + + %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 (XXX to be) approved by the FreeBSD +Core Team.

+ +

Policies

+ +

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

+ +

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.kris;, &a.marcus;, &a.linimon;, &a.eik;, &a.krion;

+ +

Secretary: Erwin Lansing

+ +

Related Documentation

+ + + +&footer; + + diff --git a/en/portmgr/policies.sgml b/en/portmgr/policies.sgml new file mode 100644 index 0000000000..26e988c20c --- /dev/null +++ b/en/portmgr/policies.sgml @@ -0,0 +1,215 @@ + + + + %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.

+ +

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.

+ +

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

+ +

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.

+ +

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/qa.sgml b/en/portmgr/qa.sgml new file mode 100644 index 0000000000..0b161059ec --- /dev/null +++ b/en/portmgr/qa.sgml @@ -0,0 +1,189 @@ + + + + %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; + +