Re: [gentoo-proxy-maint] [RFC] New doc & policy

[Michał Górny]

On czw, 2017-07-20 at 10:02 +0200, Michał Górny wrote:
> Hi,
>
> As suggested earlier, here's a new doc&policy for review. Please do not
> edit the wiki page. I'm inlining the text in the mail to facilitate
> replying with quotations since our crappy wiki lacks any review system.
>
> https://wiki.gentoo.org/wiki/User:MGorny/Extra_proxy-maint_guide
>

Here's v2, taking into account suggestions from k_f and wraeth:

==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: [http://euscan.gentooexperiment
al.org euscan], [https://qa-reports.gentoo.org/ qa-reports],
[https://repology.org/ 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 reserve 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 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.

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
{{Path|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 (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 {{Path|metadata.xml}} files. Usually, this commit will be
included along with other changes to the package.

There are a few points to consider first:
* If the package has an existing maintainer, it is best to communicate
with him prior to submitting anything. When you submit your request, we
will ask him to review it 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.

==How to submit package updates==
===GitHub pull requests===
The most efficient way of submitting your contributions is through [http
s://github.com/gentoo/gentoo/pulls 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, [https://help.github.c
om/articles/creating-a-pull-request/ create a pull request].

{{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 [https://github.com/pkgcore/pkgcheck 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 [https://git-scm.com/
book/en/v2/Git-Tools-Rewriting-History rewriting history]. Once you've
got updated commit set, use <code>git push --force</code> to overwrite
your previous commits on the pull request branch.

===Mailing list patches===
{{Note|This variant has not been tested by anyone yet.}}

One of the alternatives to GitHub is to use the [https://archives.gentoo
.org/gentoo-proxy-maint/ gentoo-proxy-maint@l.g.o] mailing
list. In order to use the list, you need to [mailto:gentoo-proxy-
maint+subscribe@l.g.o 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 <kbd>git send-email</kbd> to send them to the mailing
list. For help on it, please see [https://www.freedesktop.org/wiki/Softw
are/PulseAudio/HowToUseGitSendEmail/ 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 <kbd>--in-reply-
to</kbd> 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 <kbd>git format-patch</kbd>. 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==
===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).

===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 <kbd>repoman full -e y</kbd> to verify the
experimental profiles.

===Proxied maintainer in metadata.xml===
Proxied maintainers are listed in {{Path|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 ''after'' proxied
maintainers since it does not maintain the package on its own.

{{FileBox|title=Example metadata.xml for a package that is co-maintained 
by a proxied maintainer (primary) and Perl project (co-
maintainer)|filename=metadata.xml|lang=xml|1=<?xml version="1.0"
encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">;

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

Please note that the e-mail address used in {{Path|metadata.xml}} is
used to assign bugs to the proxied maintainer, and therefore must
correspond to a registered [https://bugs.gentoo.org 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 [https://devmanual.gentoo.org/k
eywording/index.html 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 {{Path|metadata.xml}} 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:
# 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.g
entoo.org gentoo-dev@l.g.o] 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 {{Path|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:
#*:<pre><nowiki><!--maintainer-needed--></nowiki></pre>
#*:in the place of maintainers. This will help other developers to grep
packages with no maintainers.

-- 
Best regards,
Michał Górny