Project:Proxy Maintainers/User Guide

Proxied Maintainer gets

 * ability to maintain ebuilds directly in the Gentoo repository for all our users to use;
 * coverage from our teams: QA, security;
 * coverage by package-oriented services: euscan, qa-reports, repology;
 * ability to request keywording on additional architectures (but note that most of arch teams are against proactive keywording) and to request stabilization;
 * quality reviews from our proxy-maint team and other Gentoo developers,
 * training and credibility needed to become a Gentoo developer.

A Proxied Maintainer does not get

 * ability to commit straight into the repository — all commits need to be reviewed and pushed by us,
 * full decision power — we reserve the right to reject or override your decisions at the review level,
 * ability to reject other maintainers — we encourage cooperation, not seclusion.

The responsibility is to maintain the package, that is

 * address bugs reported against the package to the best of your skills,
 * bump the package to new versions in a reasonable time,
 * ensure that the package complies to the modern ebuild quality standards and follows the best development practices (preferably of your own accord) — i.e. uses the newest EAPI, has no QA issues,
 * clean old versions of the package up, request stabilization of new versions (if the package is stable),
 * inform us when you are no longer willing to maintain the package (retirement).

The proxy-maint team is willing to help you with all those tasks. However, we expect that you at least keep the basic communication with us.

Adding a new package
As a proxied maintainer, you can add new packages to Gentoo, as long as you're willing to maintain them afterwards. In order to do so, please submit the initial package files using one of the submission methods. Make sure to include yourself and the proxy-maint project in the files.

Our team will review the submitted files and help you bring them to the top quality. Once the package is ready, we will merge it and close the relevant bugs (if there are any).

Please note that we reserve the right to reject new packages, especially if they would otherwise qualify for removal per our quality standards. Example reasons for rejection include:
 * having known major bugs or security issues that you are unable to fix,
 * having inactive upstream and maintaining them would require a lot of effort,
 * requiring specific knowledge which we lack and which makes it inappropriate for us to review them (e.g. core system packages),
 * having no usefulness for Gentoo users (this only applies to extreme cases).

Taking over an existing package
As a proxied maintainer, you can also (co-)maintain existing Gentoo packages. If you decide to do that, there are a few things to consider first:
 * 1) If the package has an existing maintainer, you should communicate with him first. He needs to approve of your co-maintainer role, and he might give you a specific task to do first.
 * 2) If the package has major bugs (esp. if they quality it for removal), you will need to provide fixes for at least some of them before your request is approved. When in doubt, contact us first to suggest specific bugs to fix first.
 * 3) If you do not have a few prior contributions as a proxied maintainer and neither of the above applied, you will need to provide some meaningful update to the ebuild. This usually involves bump to a newer EAPI, QA fixes, bug fixes — anything that could prove that you can write ebuilds. When in doubt, contact us first and we'll try to find you something to do.

Once you've established what needs to be done, please submit a commit adding yourself to as a (co-)maintainer, followed by the specific commits required to fix the package and/or prove your skills.

Readding a removed package
If you wish to readd a package that has been removed recently, please explicitly note that on your submission. The procedure for readding a package combines the requirements for adding a new package and taking over an unmaintained package. Thus, you are required to:
 * submit a good quality ebuild (either a new one or based on the old one), and
 * fix the issues that prompted the package removal in the first place.

GitHub pull requests
The most efficient way of submitting your contributions is through pull requests on our GitHub repository. At the moment, it gives the best response time, the widest audience for reviews and some nice scripting (including CI) to help.

In order to submit a pull request, fork the repository, create a new branch and commit your changes there. Afterwards, create a pull request.

Once the pull request is created, our tooling will automatically CC the relevant people (maintainers and/or proxy-maint team) and perform basic QA checks via pkgcheck. If any issues are reported, please fix them or explicitly ask for help. Our reviewers may skip pull requests which are marked as not passing CI.

Afterwards, follow the suggestions given by reviewers and push updates until the pull request is fully approved. If you do not receive a reply within a reasonable time, please make sure to ping us on the pull request. When it's ready and approved, we'll merge it.

It is recommended that you try to keep the same commit structure as you'd use when committing straight to Gentoo as a developer, and follow the best git practices (atomic changes, proper commit messages). For smaller changes, we can squash and reword the commits for you. However, if you're going to actively maintain multiple packages or submit larger changes, we will require you to squash, split and word your commits appropriately. Please see the git documentation on rewriting history. Once you've got updated commit set, use  to overwrite your previous commits on the pull request branch.

Mailing list patches
One of the alternatives to GitHub is to use the gentoo-proxy-maint@lists.gentoo.org mailing list. In order to use the list, you need to [mailto:gentoo-proxy-maint+subscribe@lists.gentoo.org subscribe] first. Once you've confirmed your subscription, you should be able to send patches for review.

Please prepare your commits just like you would for a pull request. Afterwards, use git send-email -U9999 to send them to the mailing list (use -U9999 to include as much context as possible). For help on it, please see how to use git send-email (a good guide from pulseaudio wiki — please remember to correct the mailing list address).

Once your initial patch set is submitted, the proxy-maint team members will reply with their review comments. Once you address a particular set of issues, please update the commits and send another batch of patches in reply to the original message (using the --in-reply-to option), using the next version number. It is important that you follow this practice so that everyone can find the newest version of the commits easily.

Similar practices as with GitHub pull requests apply — try to keep the commit structure clean and suitable for direct merge. Similarly to pull requests, this method can preserve commit structure and attribution but it does not support automatic assignment or CI.

Bug reports
The classical method of submitting your changes is to attach them to the bugs. Please make sure that the proxy-maint project is in CC of the bugs related to proxy-maintained packages.

Preferably, structure your changes as git commits and attach patches created using git format-patch -U9999. Attaching single files is inconvenient for the developers who have to review and download every file separately. Attaching tarballs is strongly discouraged as it makes review with quotation impossible.

When you have attached changes that are ready for review, please make sure to mark the bug with both EBUILD and PATCH keywords.

Copyright
Gentoo currently requires that for all copyrightable material submitted, the copyright is transferred to the Gentoo Foundation (where possible in the local legislation) and that the content is subsequently released as GPL-2. This is explicitly indicated by the following header in ebuilds, init.d files, etc.:

This header needs to be reproduced exactly, preserving complete date range and not adding any additional copyrights.

By submitting the files or patches to files with this copyright you acknowledge that you agree with those terms and that you are legally entitled to do that. If you are submitting derived work, you need to ensure that all the original authors agree with that as well.

Best git practices
While preparing your submissions, we strongly encourage you to follow the same git practices that our regular developers are expected to follow. This ensures that we can merge your changes quickly, and with as little modification as necessary. You can find a short set of good git practices in our Gentoo GitHub article (it is not specific to GitHub).

There is also GLEP 66 which lists the most important points in commit standards. However, it does not have an associated detailed guide yet.

Testing
You are expected to test all the changes you're submitting. The scope of testing depends on the package in question and the likeliness of breakage. At the very least, you need to:
 * 1) run repoman full (or equivalent) for all modified ebuilds,
 * 2) build all the ebuilds that had any non-trivial changes made with FEATURES=test (or equivalent).

Note that sometimes even most obvious fixes can accidentally break something or uncover some previously hidden breakage. If possible, try to build multiple USE flag combinations, especially focusing on those that could catch breakage.

It is recommended to use git versions (-9999) of and  to do the testing, as they may contain new QA checks and strictness improvements that could catch additional issues. Using other package managers is also acceptable, however you need to be more careful to catch all the issues yourself.

CI vs repoman
If you are using the pull request workflow, your submissions are verified by the CI system. Nevertheless, you are still expected to use repoman to commit or verify your ebuilds before/after committing.

Note that both CI and repoman do not test experimental (and developer) profiles by default. The skipped profiles at the time of writing include:
 * all profiles for arm64, m68k, mips, nios2, riscv, s390, sh,
 * all profiles for FreeBSD and Prefix,
 * some less common profiles, e.g. no-multilib amd64 or x32 profiles.

You need to explicitly use repoman full -e y to verify the experimental profiles.

Proxied maintainer in metadata.xml
Proxied maintainers are listed in like any other maintainers. The only difference is that since they can not commit on their own, the proxy-maint project is listed as well to facilitate committing. The proxy-maint project is always listed after proxied maintainers since it does not maintain the package on its own.

Resolving bugs
As a proxied maintainer, you are expected to handle bugs against your packages yourself. This includes resolving them once your fix is merged by a proxy maintainer or rejecting them based on your own judgment.

The Bugzilla permissions for regular users allow them to resolve only bugs that they are either assignee or reporter of. At the same time, it permits only one assignee meaning that the remaining assignees are added to the CC field. If that is the case for you, you will have to ask us to close the bug for you.

Once you have a few good contributions, we can vouch for providing the editbugs group membership to you. It will allow you to edit all Gentoo bugs, including resolving and reassigning them.

Keywording & stabilization
As a proxied maintainer, you can request keywording and stabilization of your packages. However, all those requests need to be approved by proxy-maint team member (or a regular developer co-maintainer) first.

Cleaning up old ebuilds
To avoid cluttering the repository with old ebuilds, it is recommended that you clean them up either periodically or on version bumps (if you do not expect to stabilize the specific old version). Please remember to remove old patches and other misc files along with the old versions, and to verify that the package has no reverse dependencies that depend on the old version.

If you are using the GitHub pull request workflow, then the CI will verify that your commits do not break reverse dependencies on major profiles. However, note that experimental and developer profiles are not tested currently.

The maintainer bug
Since proxied maintainers do not have full access to the Gentoo developer services, the proxy-maint project is using maintainer bugs to track status of the proxied maintainers.

Once your first contribution is merged, we will create the maintainer bug for you. We will note your name and/or nickname (for communication purposes) and your e-mail address used in metadata.xml. We will afterwards use the bug to track the changes in your e-mail address and your contributor status.

If you ever need to change your Bugzilla e-mail address, please remember to submit an update to your package files first. Preferably, wait till it is merged before updating Bugzilla as otherwise we will temporarily be unable to assign bugs properly. Please also leave a comment with your new address on the maintainer bug.

If you go on vacation or otherwise expect to be unavailable for a period of time, please note that on the maintainer bug. You can use the whiteboard field to provide the expected return date and any requests wrt handling the bugs on your packages (i.e. whether other developers should merge fixes in your absence).

How to step down as a proxied maintainer
If you decide that you don't want to maintain some of your packages anymore, please follow the following procedure:
 * 1) If you are the last maintainer of some of the packages (not counting proxy-maint project), please send an email to [mailto:gentoo-dev@lists.gentoo.org gentoo-dev@lists.gentoo.org] mailing list titled 'Packages up for grabs: …' and listing all packages that you are no longer willing to maintain. It is usually a good idea to shortly describe the state of packages, i.e. whether the packages have open bugs, whether they are hard to maintain etc.
 * 2) Submit a patch removing yourself from the  files of the packages:
 * 3) * If you are the last proxied maintainer of the package, remove the proxy-maint project along with you.
 * 4) * If you are the last maintainer of the package, please insert a comment stating exactly:
 * in the place of maintainers. This will help other developers to grep packages with no maintainers.
 * in the place of maintainers. This will help other developers to grep packages with no maintainers.