Project:Proxy Maintainers/User Guide

Privileges and responsibilities of proxied maintainers
What you get as a proxied maintainer:
 * 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.

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

Your 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 follows the best practices (preferably of our own accord),
 * 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.

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.

How to become a proxied maintainer
There is no special process for becoming a proxied maintainer — you become one when your first commit is merged.

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:
 * they have known major bugs or security issues that you are unable to fix,
 * they have inactive upstream and maintaining them would require a lot of effort,
 * they require specific knowledge which we lack and which makes it inappropriate for us to review them (e.g. core system packages).

Taking over an existing package
As a proxied maintainer, you can also (co-)maintain existing Gentoo packages (both those with no maintainer, maintained by other proxied maintainers and maintained by Gentoo developers/projects). In order to take over the maintenance of a package, submit a commit adding yourself to the files. Usually, this commit will be included along with other changes to the package.

There are a few points to consider:
 * If the package has an existing maintainer, he will be asked to ACK your changes and approve your request. Gentoo developers can reject a proxied maintainer if they have a good reason to do so.
 * If the package has major bugs qualifying it for removal (esp. if you're taking over maintenance in reply to last rites), you will be required to provide a fix at least for the most nagging issues.
 * If you do not have major prior contributions as a proxied maintainer, you will be required to do some additional changes to the package — for example, fix some bug(s) and/or update the package to the modern coding standards.

GitHub pull requests
The preferred way of submitting your contributions is through pull requests on our GitHub repository. At the moment, it gives the best response time, and the widest audience for reviews.

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
The alternative 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 to send them to the mailing list. 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. 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.