Package maintainer's responsibilities

This page Article description::aids developers in getting familiar with the tasks and responsibilities of a package maintainer in Gentoo. It may be found useful for community members who are curious about stepping up as a maintainer, returning from a long hiatus, or those who are simply looking for tips.

Not everything listed in here need to be incorporated to a workflow, but following these steps should keep the Gentoo repository in a clean working state, keep your activity up, and ease maintainer tasks.

General responsibilities as a maintainer consist of: keeping ebuilds up-to-date with upstream releases, responding to and fixing assigned bugs, and handling possible stabilization of packages in time. It is also important to keep up with the Python, Ruby, PHP, etc. ecosystems in Gentoo.

''Rationale: If a package has existing stable keywords you must request stabilization of a newer version within a reasonable time frame (usually at least 30 days, but see the stabilization section in devmanual), provided there are no regressions compared to the last stable version. This prevents stable users from being stuck on old versions of the package with no justification.''

''Rationale: It is also important to add the latest e.g. Python versions which a package supports as soon as possible to avoid conflicts for users when the default Python target in the Gentoo profiles changes. See'' Daily / Occasional pkgcheck scans for a tip to quickly check for a PYTHON_COMPAT update in packages.

Bugzilla
Gentoo's Bugzilla is still the main communication channel to reach you with your package state. When a bug report gets assigned to a developer, the first thing you should attempt to do is to confirm and replicate it with the information attached to the bug. You should then either mark the bug as "CONFIRMED", or provide a comment that you can't.

Keep an eye out for CI/tinderbox-style bugs too, which are found by testing the latest ebuilds (by commit) and random packages, respectively. They reveal breakages on different systems, mostly missing dependencies, and make you face issues you perhaps hadn't thought of before.

When you make a commit to Gentoo's git tree, please remember to reference or close a single bug, or multiple bugs, by using Bug: or Closes: tag in your git commit message's footer area. See an example, and more documentation.

Stabilization can be done by a maintainer who is also a developer, and owns relevant hardware. It can also be requested through Bugzilla for arch teams to handle, even for your own packages.

It is recommended to set up your mail client's filtering properly. Separating Bugzilla mail from generic alias mail, mailing lists, GitHub etc, helps to create an organized workflow and time usage.

A simple alias separation, for example, is done by simple filters:

To-contains: example@gentoo.org From-is: bugzilla-daemon@gentoo.org
 * 1) example project, Bugzilla mail

To-contains: example@gentoo.org From-isn't: bugzilla-daemon@gentoo.org
 * 1) example project, alias mail

And a separate personal Bugzilla email such as:

To-is: developer@gentoo.org From-is: bugzilla-daemon@gentoo.org
 * 1) Personal Bugzilla mail

You can separate mailing list e-mails similarly, etc. See Project:Infrastructure/Developer_E-Mail/Sieve_Example for an example.

Any GitHub pull requests linked to your bugs are shown in the "See also" field. See the Github pull requests section below.

Check bugs assigned to you by searching. You can also see them in Bugzilla's front page after logging in, "Open bugs assigned to me". And also in Package_maintainer%27s_responsibilities.

Ebuilds and git workflow
See the devmanual's Git for Gentoo Developers page for git configuration help.

When writing and pushing ebuilds to Gentoo's ebuild repository (and why not to any overlay as well) QA tools should be utilized whenever possible. and are the two available choices for developers, however some developers use custom scripts. They can both be found and installed from gentoo:: with their respective names.

Make sure you don't blindly copy-paste an old ebuild and try to push that. Always take a look and try to spot the obvious outdated parts - such as old EAPI, unguarded external tool calls, new Python compatibility update, etc.

After an ebuild or file has need modified, run  and/or  in the package directory to perform QA checks.

and will not catch every issue. So watch out for common mistakes when writing ebuilds. In general, familiarize yourself with the Quality Assurance's Policy guide and if writing Python ebuilds, the Python project's Python guide.

When committing changes, or  (from the  package) can be used. They will properly sign-off the commits with accordance to Gentoo's GLEP 76 requirements. These tools will also append the correct, GLEP 66 compliant summary and fix or wrong copyright headers automatically.

Commits also need to be PGP-signed, so keep encryption keys up-to-date and available in Gentoo's infra.

After committing, use for a final check before issuing  or. Of course, before pushing does not hurt either. will help confirm no other files have been accidentally modified, or uncommitted work (like a file) before pushing. Those unfamiliar with git can review "A better ebuild workflow with pure git and pkgcheck" blog entry for a short guide.

Gentoo's CI system runs pkgcheck, so familiarizing one's self with pkgcheck and its warnings is encouraged. If you add a new warning to the tree, you will get an e-mail from "repomirrorci@g.o" with the warning, and this could most likely have been prevented by running before pushing the changes. A new CI error will prevent metadata being generated to Gentoo's sync-repositories, and therefore deny users the latest updates until the CI error is fixed. Note the difference in severity between warnings and errors.

By default enables a lot of checks. Some of them are more useful than the others. pkgcheck can be configured via the file. For example, a sane configuration could look like this:

Refer to the official pkgcheck documentation for all options and edit as needed.

It is also possible enable the desired checks from the command line each time pkgcheck is called however, this will become repetitive and tedious, e.g.,. More on that below.

When unsure of the meaning or how to fix a warning, be sure to ask fellow developer for assistance. If in doubt about who to ask, head to the, , or (for non-developers too) IRC channels. You can, and you should, of course, ask before pushing if something is not fully clear.

GitHub pull requests
Some developers may find themselves in a position where users provide contributions to their ebuilds via GitHub pull requests. As GitHub is a popular platform, Gentoo is seeing many contributions pushed there. That being said, using GitHub is not mandatory and Bugzilla is still the main channel for reporting enhancements to the Gentoo ebuild repository.

Joining the Gentoo GitHub organization: To join the Gentoo GitHub organization, make sure the  LDAP attribute has been set in infrastructures dev.gentoo.org's LDAP record. Join on the Libera IRC network to ask for a manual re-sync, and you will be added to the Gentoo organization in GitHub. You should be automatically added to teams you're part of. Remember to once again update your mail filters so you can organize incoming mail from GitHub better.

The CI check in GitHub: GitHub pull requests feature a powerful CI check to ensure the commits won't break repository's integrity. As said, a new CI error will prevent metadata being generated thus denying users the latest updates, until the CI error is fixed. Every pull request gets tested, and you'll see @gentoo-repo-qa-bot commenting whether the pull requests passes or fails the CI check with a Pull request CI report comment. Pay attention to this report, as it shows very clearly where and why the PR fails, if it fails. You can utilize this CI check even for your own commits if you're afraid it's going to break something - e.g. when doing updates. Just open a pull request of your own against our gentoo/gentoo GitHub mirror.

Reviewing pull requests: GitHub's Web UI provides an easy interface to review individual commits, or all changes at once. Make sure you thoroughly read through all parts of the contribution and hold it to the same standards as your own work, i.e., latest EAPI, updated Python compatibility, missing  etc. And again,  and  do not catch everything a human does (and vice versa).

Alternatively, can be used to work with pull requests.

Testing pull requests: All contributions should be tested. Even though the ebuild looks fine, unpredictable issues may be encountered, like changed SRC_URI, missing DEPEND , etc.

You can easily and quickly do the basic testing by merging it to a local repository, then running against affected package(s). More thorough testing can be done via different chroots, containers, and virtual machines, but setting them up for a one-time run might be a bit much. is a great tool for situations like that. For continuous involvement with GitHub contributions, it is recommended to set up a more permanent test environment. See also Package testing.

Merging pull requests: Since the gentoo/gentoo GitHub repository is just a mirror, we can't actually merge these in GitHub. So we merge the raw files to our own git.gentoo.org repository.

can be used, but there are also tools to help you merge GitHub pull requests, and/or Bugzilla files. See or  for more information. At this point you can also fix any malformed commit summaries, messages etc. that do not adhere to Gentoo's GLEPS 66 and 76 requirements. If the author has added their sign-off to their contribution, per GLEP-76 their copyrighted work can not be modified. So perform the additional fixes and updates in a separate commit. Make sure to review the contribution so that broken ebuilds are not pushed and then fixing them afterwards, since it's also a learning experience for the contributor.

External tools
If you are in doubt whether there is "anything for you to do" with your packages, use these external tools / resources to check state of your packages. And if these tools still report you have nothing to do, extend the checks to the projects you're involved with 😉

Package updates, and bugs
packages.gentoo.org provides a Repology integration, which shows which of your packages don't have the latest versions available in Gentoo's package repository. You can find it under the "Outdated" tab of your maintainer page,. You can also find open bugs assigned to you from this page behind the "Bugs" tab.

Repology itself provides an RSS feed to follow per maintainer, so if you search for "Maintainer: developer@gentoo.org", and get to  page, you can find HTML and RSS feeds on the rightmost pane. These will announce when a package maintained by you gets a new version flagged in Repology.

CI issues with packages
Our QA reports page reports all currently available CI issues within the main repository. You can filter this CI report page by appending  matching the address listed in  file. For example,  would show all CI issues for packages assigned to. This works with projects and proxied maintainers alike.

More verbose checks can be obtained by adding to the URL.

Daily / Occasional pkgcheck scans
provides a tool to quickly check the overall state of your packages. To check for pending stabilizations, you can use something like can be ran in the root of the git tree.

To see packages with identical KEYWORDS, which means some older versions can be cleaned from the tree, use:

Finally, to combine these checks, run:

These two above checks are also shown in your maintainer page on packages.gentoo.org.

One more: check available PYTHON_COMPAT updates to packages with:

External resources

 * A better ebuild workflow with pure git and pkgcheck
 * Generating GLEP 63 based OpenPGPkeys
 * Gentoo GitHub - How to make a pull request
 * Gentoo Python's guide
 * Gentoo QA's Policy Guide
 * Package testing
 * QA reports
 * Repology
 * Test environment
 * Ultimate guide to EAPI-7
 * Ultimate guide to EAPI-8