Package maintainer's responsibilities

Package maintainer's responsibilities in Gentoo Linux

This page aids you in getting familiar with the "everyday" tasks and responsibilites of a package maintainer in Gentoo. You may find this page useful if you're curious about stepping up as a maintainer, returning from a long hiatus, or simply looking for tips.

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

Your general responsibilities as a maintainer consist of: keeping your packages up-to-date with upstream releases, responding to and fixing bugs assigned to you, and handling possible stabilization of your packages in time. You also need to keep up with the Python, Ruby, PHP, etc. ecosystems in Gentoo.

''Rationale: If your package has existing stable keywords you must request stabilization of a newer version within a reasonable timeframe (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's also important to add the latest e.g. Python versions which your package supports as soon as possible to avoid conflicts for users when the default Python target in the Gentoo profiles changes. See'' Daily / Occassional pkgcheck scans for a tip to quickly check for a PYTHON_COMPAT update in your 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 you, 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 organize your 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 separate your personal Bugzilla mail 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 & git workflow
See Git for Gentoo Developers for configuration help.

When writing and pushing ebuilds to Gentoo's repository tree (and why not to any overlay as well) you should definitely take advantage of the available QA tools. and being your choices here. They can both be found and installed from the main Gentoo repository 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 you've edited an ebuild or file, run  and/or  in the package directory.

and won't 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 your changes, or  (from the dev-util/pkgdev 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 your keys up-to-date and available in Gentoo's infra.

After committing, use for a final check before issuing  or. Of course, before pushing doesn't hurt either. will help you check that you don't have any modified, uncommited work (like a file) before pushing. "A better ebuild workflow with pure git and pkgcheck" guide if you're not too familiar with git.

Gentoo's CI system runs pkgcheck, so familiarizing yourself 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 your 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:

[DEFAULT] checks = -ImlateCheck,-RedundantVersionCheck,-UnstableOnlyCheck
 * 1) ~/.config/pkgcheck/pkgcheck.conf
 * 2) -ImlateCheck = PotentialStable, all of these checks are just noise.
 * 1) -ImlateCheck = PotentialStable, all of these checks are just noise.

Refer to the official documentation of the flags and edit to your needs.

You can also just enable the checks you wish from the command line, e.g.,. More on that below.

Ask a fellow developer if you're unsure of the meaning or how to fix a warning. If in doubt about who to ask, head to the #gentoo-dev, #gentoo-qa, or #gentoo-dev-help (for non-developers too) IRC channels. You can, and you should, of course ask before pushing if something is not fully clear to you.

GitHub pull requests
You may find yourself in a position where users provide contributions to your packages 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 your packages.

Joining the Gentoo GitHub organization: To join the Gentoo GitHub organization, make sure you've set your  attribute in 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  don't catch everything a human does (and vice versa).

Alternatively, dev-util/github-cli can be used to work with pull requests.

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

You can easily and quickly do the basic testing by merging it to your own 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. dev-util/ebuildtester is a great tool for situations like that. For continuous involvment with GitHub contributions, it's 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   repository.

can be used, but there are also tools to help you merge GitHub pull requests, and/or Bugzilla files. See app-portage/pram or dev-perl/Gentoo-App-Pram for more information. At this point you can also fix any misformed commit summaries, messages etc. that don't adhere to Gentoo's GLEPS 66 and 76 requirements. If the author has added their sign-off to their contribution, per GLEP-76 you can not modify their copyrighted work. So do your additional fixes and updates in a separate commit. Make sure to review the contribution so you're not pushing broken ebuilds and 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 your 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.

You can get a more verbose check results by adding  to the URL.

Daily / Occassional pkgcheck scans
provides a tool to quickly check the overall state of your packages. To check for pending stabilizations, you can use something like:

in the root of the git tree.

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

and finally, to combine these checks, you can do:

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

One more: check available PYTHON_COMPAT updates to your 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