Project:Proxy Maintainers/User Guide

Privileges and responsibilities of proxied maintainers

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.

How to become a proxied maintainer

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 metadata.xml 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:

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.
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.
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 metadata.xml 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.

How to ensure that your changes are merged promptly

The proxy maintainers team has a lot of work and historically there have been frequent cases of pull requests waiting months for review. Here are a few suggestions that could help you get your pull request merged promptly:

Try to flesh out the ebuild before submitting it. There have been cases of proxied maintainers submitting ebuilds copied from various sources, of very bad quality, with obvious errors and typos. Pointing all those mistakes out takes a lot of developer's time and some developers are discouraged by them. Therefore, it is best to try to look critically at your work and flesh it out before submitting. You can try to get help on IRC or other support channels.
Test your ebuild after every change. Use repoman. Mistakes happen. Developers can also be wrong. If you change anything in the ebuild, go through the complete testing procedure to make sure it's not broken. This avoids ping-pong of developer having to point out the breakage instead of merging it.
Watch out for bad commits. Write good commit messages. Many of the problems pointed out by developers are badly split commits, bad commit messages or git pull merge commits. Some of them we can fix for you, some we can't. Please try to avoid us having to repeat ourselves.
Rebase proactively, especially if the pull request is sitting there for a while. Sometimes changes in Gentoo prevent us from merging the ebuild. It's better if you notice it first and rebase it before we have to ask you for it ;-).
Ping us if your ebuild does not get attention. We can miss your pull request, or the mail that you have updated it. If you finished implementing requested changes, please say so in a comment (one comment is enough, you don't have to reply to every request). If we are still not responding, please just leave a ping comment and GitHub should mail us again.
Finally, you can try to set up review session on IRC. With many pull requests requiring our attention and different times of availability, it's often hard to ensure a prompt review. Instead of waiting, you can come to IRC and try to find someone who's around at the time and is willing to give you his full attention. If you both focus on the PR, you can get it merged during one session.

However, please note that the above applies to submissions suitable for proxied maintenance. We do not review pull requests aimed at packages maintained purely by Gentoo developers.

Handling disagreements with proxy-maint members

First of all, please understand that we're all humans and we can make mistakes. ^[1] If you have any doubts about our suggestions or you simply believe that they are wrong, please try to verify it and express your concerns. Discussion is an important part of learning, and if you blindly follow our suggestions, you may end up having to revert the changes afterwards. Please also note that if you ignore our suggestions rather than replying why you are not following them, we may end up waiting for your reply forever.

However, it is important to keep the discussion civil and factual, and to support your claims with appropriate research. If you behave inappropriately towards Proxy Maintainer team members, you discourage them from reviewing your pull request, and effectively reduce the changes of it being merged. We also reserve the right to reject your contributions or request a disciplinary action if we believe that your behavior makes it impossible to work with you long-term.

The existing Gentoo policies and good practices are binding to you. if you believe that they are wrong, you are expected to follow the appropriate procedure to suggest changes to them, and not plain ignore them. If you refuse to follow the policies without explanation satisfactory to your reviewer, we may reject your contribution or modify it appropriately. If you disagree with us altering your contributions, please do not submit them.

It is also possible for different proxy-maint reviewers to disagree with one another, ask you to fix something that has been approved previously, or even to give you contradictory requests. As said above, we can also make mistakes or fail to notice something. Sometimes we also deliberately defer some minor issues to future reviews, to avoid delaying the pull requests too much. Finally, some developers have different preferences, and try suggesting their preference to you. In any case, we are sorry that this will sometimes happen. If there is no doubt that the 'new' suggestion is valid, please follow it. If there's any doubt, please discuss it with the reviewers. In case it's merely a matter of preference and not policy, you are free to follow your own judgment.

How to submit package updates

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.

Tip
Once you push your new branch, visit the GitHub page of your fork. GitHub will show you a banner suggesting creating a pull request. Using it, you can avoid the necessity of specifying the fork and branch manually.

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.

Please keep the same commit structure as you would 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 are 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 git push --force to overwrite your previous commits on the pull request branch.

For step-by-step instructions, see GitHub Pull Requests.

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 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

Warning
Patch submissions via bug reports are not processed timely. If you'd like to see your contribution merged within a reasonable timeframe, please use GitHub.

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.

Being a proxied maintainer

Copyright

The Gentoo copyright policy is detailed in GLEP 76. The article 'new Gentoo copyright policy explained' may also be of help.

The most important points of relevance to submitting ebuilds are:

All ebuilds must be licensed GPL-2, and associated copyrightable files (e.g. init.d scripts, patches) must use a GPL-compatible license as defined by FSF.
You must be legally entitled to submit them under those licenses, and acknowledge this by signing off the Gentoo Certificate of Origin in all your commits/patches.
The copyright headers in ebuilds (and other files suitable to hold those headers) need to follow a strict format, and attribute copyright to Gentoo Authors.

The copyright header looks like the following (square brackets indicating parts to omitted when irrelevant):

CODE Copyright header for ebuilds

# Copyright [2016-]2018 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

Best git practices

Please 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.

There is also GLEP 66 which lists the most important points in commit standards.

Testing

Note
Since 3 Feb 2018, sys-apps/portage has an additional gentoo-dev USE flag that enables more strict mode intended for use by developers. Please enable this flag in your development environment to ensure that your ebuilds are tested properly.

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:

run repoman full -d -x (or equivalent) before submission,
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 sys-apps/portage and app-portage/repoman 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

Warning
If your pull request is flagged with CI issues, please look into them. We tend not to review pull requests that have pending issues flagged. If you need help, please tell us so.

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 metadata.xml 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 at last, since it does not maintain the package on its own.

FILE metadata.xmlExample metadata.xml for a package that is co-maintained by a proxied maintainer (primary) and Perl project (co-maintainer)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">

<pkgmetadata>
	<maintainer type="person">
		<email>author@example.com</email>
		<name>A. U. Thor</name>
	</maintainer>
        <maintainer type="project">
                <email>perl@gentoo.org</email>
                <name>>Gentoo Perl Project</name>
	</maintainer>
	<maintainer type="project">
		<email>proxy-maint@gentoo.org</email>
		<name>Proxy Maintainers</name>
	</maintainer>
</pkgmetadata>

Note
We do no longer use redundant descriptions like

CODE

<description>Proxied maintainer; set to assignee in all bugs</description>

This Information is already given by the email and makes automatic bug assignment slow and difficult.

Tip
The e-mail address used in metadata.xml is used to assign bugs to the proxied maintainer, and therefore must correspond to a registered Gentoo Bugzilla account.

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, please ask one of the proxy-maint team members (or a regular developers) to confirm them 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 obsolete 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.

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 need to change your Bugzilla e-mail address, please leave a comment with your new address on the maintainer bug. Then submit an update to your package metadata.xml files and wait until it is merged before updating Bugzilla as otherwise we will temporarily be unable to assign bugs properly.

If you 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 with regard to handling the bugs on your packages (i.e. whether other developers should merge fixes in your absence). Example: Away from 2017-01-02 till 2017-03-01, Larry takes care of my packages.

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:

If you are the last maintainer of some of the packages (not counting proxy-maint project), please send an email to 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.
Submit a patch removing yourself from the metadata.xml files of the packages:
- If you are the last proxied maintainer of the package, remove the proxy-maint project along with you.
- 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.

↑ Please note that this haven't been thoroughly verified yet, and by implication of the sentence itself we may be mistaken in that.

[1] Please note that this haven't been thoroughly verified yet, and by implication of the sentence itself we may be mistaken in that.

[1]