GLEP67, or how packages are going to be maintained

The way packages are maintained in Gentoo have been evolving for quite some time already. So far all of that has been happening on top of old file formats which slowly started to diverge from the needs of Gentoo developers, and become partially broken. The concept of herds has become blurry, with confusion in definition between different developers and partial assumption about their deprecation. Maintenance of herd by project has been broken by moving projects to the Wiki. Some projects have stopped using herds, others have been declaring them in metadata.xml in different ways.

The problem has finally reached the Gentoo Council and has been discussed on 2015-10-25 meeting (note: no summary still…). The Council attempted to address different problems by votes, and create a new solution by combining the results of votes. However, finally it decided that it is not possible to create a good specification this way. Instead, the meeting has brought two major points. Firstly, herds are definitely deprecated. Secondly, someone needs to provide a complete, consistent replacement in GLEP form.

This is how GLEP 67 came to be. It was based on results of previous discussion, Council votes and thorough analysis of different problems. It provides a complete, consistent system for maintaining packages and expressing the maintenance information. It has been approved by the Council on 2016-01-10, with two week deadline on preparing to the switch.

Therefore, on 2016-01-24 Gentoo is going to switch to the new maintenance structure described in GLEP 67 completely. The announcement with transition details has been sent already. Instead, I’d like to focus on describing how things are going to work starting from the day GLEP 67 becomes implemented.

Who is going to maintain packages?

Before getting into technical details, GLEP 67 starts by limiting possible package maintainer entries. Until now, metadata files were allowed to list practically any e-mail addresses for package maintainers. From now on, only real people (either developers or proxied maintainers) and projects (meeting the requirements of GLEP 39, in particular having a Wiki page) are allowed to be maintainers. All maintainers are identified by e-mail addresses which are required to be unique (i.e. sharing the same address between multiple projects is forbidden) and registered on bugs.g.o.

This supports the two major goals behind maintainer specifications: bug assignment and responsibility assignment. The former is rather obvious — Bugzilla is the most reliable communication platform for both Gentoo developers and users. Therefore, it is important that the bugs can be assigned to appropriate entities without any issues. The latter aims to address the problem of unclear ‘ownership’ of some packages, and packages maintained by ‘dead’ e-mail aliases.

In other words, from now on we require that for every maintained package in Gentoo, we need to be able to obtain a complete, clear list of people maintaining it (directly and via projects). We no longer accept ‘dumb’ e-mail aliases that make it impossible to distinguish real maintainers from people who are simply following bugs. This gives three important advantages:

  1. we can actually ping the correct people on IRC without having to go through hoops,
  2. we can determine whether a package is actually maintained by someone, rather than assigned to an alias from which nobody reads bug mail anymore,
  3. we can clearly determine who is responsible for a package and who is the appropriate person to acknowledge changes.

Changes for maintainer-needed packages

The new requirements brought a new issue: maintainer-needed@g.o. The specific use of this e-mail alias did not really seem to suit a project. Creating a ‘maintainer-needed project’ would either imply creating a dead entity or assigning actual maintainers to supposedly-unmaintained packages. On the other hand, I did not really want to introduce special cases in the specification.

Instead, I have decided that the best way forward is to remove it. In other words, unmaintained packages now explicitly list no maintainers. The assignment to maintainer-needed@g.o will be done implicitly, and is a rule specific to the Gentoo repository. Other repositories may use different policies for packages with no explicit maintainers (like assigning to the repository owner).

The metadata.xml and projects.xml files

The changes to metadata.xml are really minimal, and backwards compatible. The <herd/> element is no longer used, and will be prohibited. Instead, <maintainer/> elements are going to be used for all kinds of maintainers. There are no incompatible changes in those elements, therefore existing tools will not be broken.

The <maintainer/> element gets a new obligatory type attribute that needs to either be person or project. The latter value may cause tools to look the project up (by e-mail) in projects.xml.

The projects.xml file (unlike past herds.xml) is clearly defined in the repository scope. In particular, the tools must not assume it always comes out of Gentoo repository. Other repositories are allowed to define their own projects (though overriding projects is not allowed), and project lookup needs to respect masters= setting in repositories.

For the Gentoo repository, projects.xml is generated automatically from the Wiki project pages, and distributed both via api.gentoo.org and via the usual repository distribution means (the rsync and git mirrors).

Summary

A quick summary for Gentoo developers of how things look like with GLEP 67:

  1. Only people and projects can maintain packages. If you want to maintain packages in an organized group, you have to create a project — with Wiki page, unique e-mail address and bugs.g.o account.
  2. Only the explicitly listed project members (and subproject members whenever member inheritance is enabled) are considered maintainers of the package. Other people subscribing the e-mail alias are not counted.
  3. Packages with no maintainers have no <maintainer/> elements. The bugs are still implicitly assigned to maintainer-needed@g.o but this e-mail alias is no longer used in metadata.xml.
  4. <herd/> elements are no longer used, <maintainer/>s are used instead.
  5. <maintainer/> requires a new type attribute that takes either person or project value.