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

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 14101 bytes --]

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


Content:

==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 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
{{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:
* 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 {{Path|metadata.xml}} 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.

==How to submit package updates==
===GitHub pull requests===
The preferred way of submitting your contributions is through [https://g
ithub.com/gentoo/gentoo/pulls 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, [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.}}

The alternative to GitHub is to use the [https://archives.gentoo.org/gen
too-proxy-maint/ 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 <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==
===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 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@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>}}

===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 change your Bugzilla e-mail address, please remember to
submit an update to your package {{Path|metadata.xml}} files. We will
also note the new e-mail 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.
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.
# 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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

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

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 2698 bytes --]

Thanks for doing this work Michał,

On 07/20/2017 10:02 AM, Michał Górny wrote:
> Please note that we reserve the right to reject new packages, especially
> if they would otherwise qualify for removal per our quality standards:

Should we add something about the usefulness of packages for other
users? As stated earlier, by being in main tree (and in particular part
of stable set) there is support form other projects, any new package
addition adds overhead.

On 07/20/2017 10:02 AM, Michał Górny wrote:
> ===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.

In the case of already maintained packages, they likely should
communicate with the original maintainers first. Although I see you're
touching upon it in next paragraph, the workflow seems to be
communication after having worked up a patch and submitted it?

On 07/20/2017 10:02 AM, Michał Górny wrote:
> 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.

They don't really need good reasons

On 07/20/2017 10:02 AM, Michał Górny wrote:
> ===GitHub pull requests===
> The preferred way of submitting your contributions is through [https://g
> ithub.com/gentoo/gentoo/pulls pull requests on our GitHub repository].

Preferred by whom? (The preferred way to submit patches to gentoo
proxied maintainer project...?)

On 07/20/2017 10:02 AM, Michał Górny wrote:
> ===Bug reports===
> The classical method of submitting your changes is to attach them to the
Would likely flip the order, since this is the classical way

On 07/20/2017 10:02 AM, Michał Górny wrote:
> ==Being a proxied maintainer==

Should we add something on proper commit messages? And atomic changes
per commit etc.

On 07/20/2017 10:02 AM, Michał Górny wrote:
> The skipped profiles include:
... profiles at the time of writing include..

On 07/20/2017 10:02 AM, Michał Górny wrote:
> ===Proxied maintainer in metadata.xml===

mention of bugzilla account requirement?

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 4704 bytes --]

On czw, 2017-07-20 at 10:33 +0200, Kristian Fiskerstrand wrote:
> Thanks for doing this work Michał,
> 
> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > Please note that we reserve the right to reject new packages, especially
> > if they would otherwise qualify for removal per our quality standards:
> 
> Should we add something about the usefulness of packages for other
> users? As stated earlier, by being in main tree (and in particular part
> of stable set) there is support form other projects, any new package
> addition adds overhead.

I was thinking about that but I couldn't figure out a sane way to word
it. After all, I don't want to sound like we will judge every submission
for its usefulness to Gentoo users. And I certainly don't want to sound
like we're going to reject packages if e.g. they apply only to some rare
hardware.

I agree with your point but I'm just not sure if we should explicitly
mention it. After all, it still falls into 'rejecting at our own
discretion'.

> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > ===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.
> 
> In the case of already maintained packages, they likely should
> communicate with the original maintainers first. Although I see you're
> touching upon it in next paragraph, the workflow seems to be
> communication after having worked up a patch and submitted it?

I will think how to improve this. Basically the intent was to emphasize
that we don't want people who just claim to maintain stuff; we want
people who are actually going to do it, and they are supposed to prove
it via fixing some issue.

Strictly speaking, it would probably be better to talk to the current
maintainer first. However, I would like to avoid a situation when
the other maintainer says 'fine', then the proxied maintainer demands
being added because of maintainer approval without actually proving
anything.

> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > 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.
> 
> They don't really need good reasons

Yes, they do. I'm against Gentoo where maintainers just reject everyone
because they like working alone. Think of the games team.

> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > ===GitHub pull requests===
> > The preferred way of submitting your contributions is through [https://g
> > ithub.com/gentoo/gentoo/pulls pull requests on our GitHub repository].
> 
> Preferred by whom? (The preferred way to submit patches to gentoo
> proxied maintainer project...?)

This is proxy maintainers project documentation, so yes, it's about the
proxy maintainers team. If you don't want 'preferred', please suggest
a better word. The fact is, pull requests are handled more timely than
bugs (think of all the bugs that are still waiting for someone to take 
a look at them), and have CI coverage.

> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > ===Bug reports===
> > The classical method of submitting your changes is to attach them to the
> 
> Would likely flip the order, since this is the classical way

Flipping the order would mean people read this first. This would mean
they're more likely to actually do it this way. Which in turn would mean
they will hit sheer frustration when someone asks them to file a pull
request instead if they don't want to wait months for someone to take
a look at it.

> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > ==Being a proxied maintainer==
> 
> Should we add something on proper commit messages? And atomic changes
> per commit etc.

This really belongs in generic Gentoo documentation. I think linking
the 'Gentoo GitHub' page as the most current policy reference would
help.

> 
> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > The skipped profiles include:
> 
> ... profiles at the time of writing include..

Done.

> 
> On 07/20/2017 10:02 AM, Michał Górny wrote:
> > ===Proxied maintainer in metadata.xml===
> 
> mention of bugzilla account requirement?

Done.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

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

[Sam Jorna]

[-- Attachment #1.1: Type: text/plain, Size: 4577 bytes --]

On 20/07/17 18:02, Michał Górny wrote:
> * ability to request keywording on additional architectures (but note
> that most of arch teams are against proactive keywording) and to request
> stabilization;

Stabilisation requests can also be filed by users per [1] without being
the maintainer.

> * full decision power — we restrict the right to reject or override your
> decisions at the review level,

s:restrict:reserve:

> * ensure that the package follows the best practices (preferably of our
> own accord),

I'm not sure what this wording is supposed to mean.

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

Perhaps just "You are assigned as the maintainer when your first commit
is merged". Might also be worth suggesting the first commit be to update
metadata.xml.

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

The bugs should probably be assigned to the maintainer for them to close
(if suitable) or otherwise deal with, as described below.

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

Other Gentoo devs can also proxy commits in-place of Proxy Maintainers,
as in proxy-maint is not included at all, at the other developers
discretion.

> ===GitHub pull requests===
> The preferred way of submitting your contributions is through [https://g
> ithub.com/gentoo/gentoo/pulls pull requests on our GitHub repository].
> At the moment, it gives the best response time, and the widest audience
> for reviews.

Unless we're actively pushing for Github over other methods, I'd avoid
"preferred"; but I'm not overly fussed either way.

> 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

A link to [2] or [3] may be useful here (or, at least, /somewhere/).

> The alternative to GitHub is to use the [https://archives.gentoo.org/gen

s:The:One of the:

> You need to explicitly use <kbd>repoman full -e y</kbd> to verify the
> experimental profiles.

What about developer profiles (`repoman full -d`) and checking metadata
(`repoman full -x`)?

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

As mentioned previously, others can request stabilisation as well.

> ===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 change your Bugzilla e-mail address, please remember to
> submit an update to your package {{Path|metadata.xml}} files. We will
> also note the new e-mail address on the maintainer bug.

This implies maintainer address and bugzilla address may be different,
which will annoy bug wranglers to no end.

> proxy-maint project), please send an email to [[mailto:gentoo-dev@lists.
> gentoo.org gentoo-dev@lists.gentoo.org] mailing list titled 'Packages up

Something is off with the email syntax here - it's not rendering
properly. Also, CC proxy-maint@lists.g.o?

It might also be good to finish with a list of links to resources, such
as the references below, devmanual, and maybe PMS.

Otherwise, comments aside, looks good to me - certainly less cumbersome
than the beast I created.

Good work, and thanks.

[1] https://wiki.gentoo.org/wiki/Stable_request
[2] https://wiki.gentoo.org/wiki/Gentoo_git_workflow
[3] https://wiki.gentoo.org/wiki/Gentoo_GitHub

-- 
Sam Jorna (wraeth) <wraeth@gentoo.org>
GnuPG Key: D6180C26


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 6400 bytes --]

On czw, 2017-07-20 at 19:36 +1000, Sam Jorna wrote:
> On 20/07/17 18:02, Michał Górny wrote:
> > * ability to request keywording on additional architectures (but note
> > that most of arch teams are against proactive keywording) and to request
> > stabilization;
> 
> Stabilisation requests can also be filed by users per [1] without being
> the maintainer.

This is not the point. The point is, you can't file
a keywordreq/stablereq against a package that's not in ::gentoo. So
being a proxied maintainer means you can submit a package that will go
stable.

> > * full decision power — we restrict the right to reject or override your
> > decisions at the review level,
> 
> s:restrict:reserve:

Good catch.

> 
> > * ensure that the package follows the best practices (preferably of our
> > own accord),
> 
> I'm not sure what this wording is supposed to mean.

That was supposed to be 'your own accord'. The generic idea is that we
want proxied maintainers to use newest EAPI, follow current policies
and so on. Should I give those examples in the doc?

> > ==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.
> 
> Perhaps just "You are assigned as the maintainer when your first commit
> is merged". Might also be worth suggesting the first commit be to update
> metadata.xml.

I'll think how to reword that.

> 
> > 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).
> 
> The bugs should probably be assigned to the maintainer for them to close
> (if suitable) or otherwise deal with, as described below.

It's about maintainer-wanted bugs. I don't really see a reason to
reassign this kind of bug and tell maintainer to close it afterwards.

> > * 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.
> 
> Other Gentoo devs can also proxy commits in-place of Proxy Maintainers,
> as in proxy-maint is not included at all, at the other developers
> discretion.

This is documentation of proxy-maint project, so working outside proxy-
maint is really irrelevant here.

> > ===GitHub pull requests===
> > The preferred way of submitting your contributions is through [https://g
> > ithub.com/gentoo/gentoo/pulls pull requests on our GitHub repository].
> > At the moment, it gives the best response time, and the widest audience
> > for reviews.
> 
> Unless we're actively pushing for Github over other methods, I'd avoid
> "preferred"; but I'm not overly fussed either way.

I can make it 'most efficient' if that makes you sleep better. Fact is,
pull request can get reviewed and merged within a few days. Bugs rot.

> > 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
> 
> A link to [2] or [3] may be useful here (or, at least, /somewhere/).

Yeah, I'm still thinking of how to solve this best. Maybe a separate
section on git with links would be helpful, since right now things seem
to be a little split between the three methods.

> > The alternative to GitHub is to use the [https://archives.gentoo.org/gen
> 
> s:The:One of the:

Done.

> 
> > You need to explicitly use <kbd>repoman full -e y</kbd> to verify the
> > experimental profiles.
> 
> What about developer profiles (`repoman full -d`) and checking metadata
> (`repoman full -x`)?

Out of scope. I wanted only to give the generic note that things won't
work out of the box for the common case of ~arm64.

It's first time I hear that I need '-x' for anything. Why is that?

> > ===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.
> 
> As mentioned previously, others can request stabilisation as well.

The point is that you need approval from proxy-maint. Compare with
today's bug when an user CC-ed arches on a bug that hasn't even been
assigned.

> > ===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 change your Bugzilla e-mail address, please remember to
> > submit an update to your package {{Path|metadata.xml}} files. We will
> > also note the new e-mail address on the maintainer bug.
> 
> This implies maintainer address and bugzilla address may be different,
> which will annoy bug wranglers to no end.

Are you suggesting that I make it 'submit an update ... first'?

> > proxy-maint project), please send an email to [[mailto:gentoo-dev@lists.
> > gentoo.org gentoo-dev@lists.gentoo.org] mailing list titled 'Packages up
> 
> Something is off with the email syntax here - it's not rendering
> properly. Also, CC proxy-maint@lists.g.o?

Yeah, extraneous '['. Fixed now.

> It might also be good to finish with a list of links to resources, such
> as the references below, devmanual, and maybe PMS.

I was thinking about it but I think they'd be better on top-level proxy-
maint project page.

> Otherwise, comments aside, looks good to me - certainly less cumbersome
> than the beast I created.
> 
> Good work, and thanks.
> 
> [1] https://wiki.gentoo.org/wiki/Stable_request
> [2] https://wiki.gentoo.org/wiki/Gentoo_git_workflow
> [3] https://wiki.gentoo.org/wiki/Gentoo_GitHub
> 

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

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

[Sam Jorna (wraeth)]

[-- Attachment #1.1: Type: text/plain, Size: 4357 bytes --]

On 21/07/17 01:15, Michał Górny wrote:
> On czw, 2017-07-20 at 19:36 +1000, Sam Jorna wrote:
>> On 20/07/17 18:02, Michał Górny wrote:
>>> * ability to request keywording on additional architectures (but note
>>> that most of arch teams are against proactive keywording) and to request
>>> stabilization;
>>
>> Stabilisation requests can also be filed by users per [1] without being
>> the maintainer.
> 
> This is not the point. The point is, you can't file
> a keywordreq/stablereq against a package that's not in ::gentoo. So
> being a proxied maintainer means you can submit a package that will go
> stable.

Fair enough, just was worried it was a "you get <this thing> that you
can already do anyway".

>>> * ensure that the package follows the best practices (preferably of our
>>> own accord),
>>
>> I'm not sure what this wording is supposed to mean.
> 
> That was supposed to be 'your own accord'. The generic idea is that we
> want proxied maintainers to use newest EAPI, follow current policies
> and so on. Should I give those examples in the doc?

I think how you have it now (v2) is good.

>>> 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).
>>
>> The bugs should probably be assigned to the maintainer for them to close
>> (if suitable) or otherwise deal with, as described below.
> 
> It's about maintainer-wanted bugs. I don't really see a reason to
> reassign this kind of bug and tell maintainer to close it afterwards.

Right, I was thinking maintainer-needed.

>>> 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
>>
>> A link to [2] or [3] may be useful here (or, at least, /somewhere/).
> 
> Yeah, I'm still thinking of how to solve this best. Maybe a separate
> section on git with links would be helpful, since right now things seem
> to be a little split between the three methods.

The links that are there at present, plus your suggestion about a
reference list on the main page below, should be enough I think.

>>> You need to explicitly use <kbd>repoman full -e y</kbd> to verify the
>>> experimental profiles.
>>
>> What about developer profiles (`repoman full -d`) and checking metadata
>> (`repoman full -x`)?
> 
> Out of scope. I wanted only to give the generic note that things won't
> work out of the box for the common case of ~arm64.
> 
> It's first time I hear that I need '-x' for anything. Why is that?

I remember reading somewhere that repoman didn't check metadata.xml by
default, though I can't find that reference any more. It could be
out-of-date information, or I may have mis-remembered.

>>> ===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.
>>
>> As mentioned previously, others can request stabilisation as well.
> 
> The point is that you need approval from proxy-maint. Compare with
> today's bug when an user CC-ed arches on a bug that hasn't even been
> assigned.

A previous incarnation of the stablereq policy had users CC'ing relevant
teams after a timeout. How that works with the bot now I'm not sure.
Either way, I'm happy with how this is now.

>>> If you ever change your Bugzilla e-mail address, please remember to
>>> submit an update to your package {{Path|metadata.xml}} files. We will
>>> also note the new e-mail address on the maintainer bug.
>>
>> This implies maintainer address and bugzilla address may be different,
>> which will annoy bug wranglers to no end.
> 
> Are you suggesting that I make it 'submit an update ... first'?

No, it came across as that your Bugzilla address and maintainer address
per metadata.xml did not have to be the same, so long as you added a
comment to the bug noting your maintainer address. I think this is
adequately covered now.

-- 
Sam Jorna (wraeth)
GnuPG ID: D6180C26


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 858 bytes --]

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 15269 bytes --]

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

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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

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

[Sam Jorna (wraeth)]

[-- Attachment #1.1: Type: text/plain, Size: 541 bytes --]

On 21/07/17 07:06, Michał Górny wrote:
> 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:

+1

-- 
Sam Jorna (wraeth)
GnuPG ID: D6180C26


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 858 bytes --]

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

[M. J. Everitt]

[-- Attachment #1.1: Type: text/plain, Size: 1411 bytes --]

On 20/07/17 22:06, Michał Górny wrote:
>
> 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;
<snip>
It's a subtle point, but it's one I think that can be fixed with a
wording tweak - I get wraeth's point about users requesting
stabilisation of a package, which is quite true .. so I think the
wording of the final point here might be better as something like "...
to request stabilisation of a package by the Arch Teams" or such.

After all, we're basically talking about the correct authority to CC the
arch teams on the stabilisation bugs, vs filing a stabilisation bug,
right? [which also might warrant mentioning/clarifying at another stage].

It's a minor point, but may be clearer exactly what's being indicated,
rather than creating confusion or misinterpretation.

HTH,
MJE



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 862 bytes --]

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

[Philippe Chaintreuil]

[-- Attachment #1.1: Type: text/plain, Size: 1445 bytes --]

On 7/20/2017 5:06 PM, Michał Górny wrote:
> On czw, 2017-07-20 at 10:02 +0200, Michał Górny wrote:
> Here's v2, taking into account suggestions from k_f and wraeth:


> ==How to become a proxied maintainer==

	This whole section seems to assume a lot of knowledge of infrastructure
that I don't think someone wanting become a proxy-maintainer will have.
It also seems to me that it has a lot of "all you need to do is this one
simple thing", followed by 3-4 reasons there will be other things you
need to do before that one simple thing.  This section would do better
with a checklist of steps followed by explanations of "why" as needed in
my opinion.

	Imagine being a total neophyte and seeing "maintainer needed" on a
package you have a vested interest in.  What is your first step of
contact?  The current text makes me think that it's a cold-called
Pull-Request planting your flag in the metadata.xml.  Is that the
intention?  Or should people be joining this mailing list and getting a
list of things that will need to be fixed before that pull-request?

	Also, if proxy-maintainers taking control of existing packages are more
common than creating new packages, it would seem to me that section
should come first.



	Additionally, I'd like to see a section on what a new proxy-maintainer
should do when they need help.  Especially when working in
"maintainer-needed" ebuilds where it's not obvious.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 2131 bytes --]

On pią, 2017-07-21 at 10:36 -0400, Philippe Chaintreuil wrote:
> On 7/20/2017 5:06 PM, Michał Górny wrote:
> > On czw, 2017-07-20 at 10:02 +0200, Michał Górny wrote:
> > Here's v2, taking into account suggestions from k_f and wraeth:
> 
> 
> > ==How to become a proxied maintainer==
> 
> 	This whole section seems to assume a lot of knowledge of infrastructure
> that I don't think someone wanting become a proxy-maintainer will have.
> It also seems to me that it has a lot of "all you need to do is this one
> simple thing", followed by 3-4 reasons there will be other things you
> need to do before that one simple thing.  This section would do better
> with a checklist of steps followed by explanations of "why" as needed in
> my opinion.
> 
> 	Imagine being a total neophyte and seeing "maintainer needed" on a
> package you have a vested interest in.  What is your first step of
> contact?  The current text makes me think that it's a cold-called
> Pull-Request planting your flag in the metadata.xml.  Is that the
> intention?  Or should people be joining this mailing list and getting a
> list of things that will need to be fixed before that pull-request?

I will try to reword but I can't promise I will achieve much. I'd like
to avoid starting with a lot of 'if's.

> 	Also, if proxy-maintainers taking control of existing packages are more
> common than creating new packages, it would seem to me that section
> should come first.

I don't want to prioritize either. Right now the order is purely
lexical.

> 	Additionally, I'd like to see a section on what a new proxy-maintainer
> should do when they need help.  Especially when working in
> "maintainer-needed" ebuilds where it's not obvious.

Isn't the team contact data (IRC, e-mail) enough on the top project
page? Remember that this is the page you would supposedly hit second,
after reading the top project page [1]. Note that the section on getting
started there will be updated to match the changes in this doc.

[1]:https://wiki.gentoo.org/wiki/Project:Proxy_Maintainers

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

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

[Philippe Chaintreuil]

[-- Attachment #1.1: Type: text/plain, Size: 754 bytes --]

On 7/21/2017 2:16 PM, Michał Górny wrote:
>> 	Additionally, I'd like to see a section on what a new proxy-maintainer
>> should do when they need help.  Especially when working in
>> "maintainer-needed" ebuilds where it's not obvious.
> 
> Isn't the team contact data (IRC, e-mail) enough on the top project
> page? Remember that this is the page you would supposedly hit second,
> after reading the top project page [1]. Note that the section on getting
> started there will be updated to match the changes in this doc.
> 
> [1]:https://wiki.gentoo.org/wiki/Project:Proxy_Maintainers

	Apologies, I thought this was replacing that page too.  If that's the
case, then it greatly alleviates my worries from the previous e-mail.

				



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]