[bug#48696,1/3] doc: Structure the "Commit Access" section.

* doc/contributing.texi (Commit Access): Add introduction and section
heading.  Separate OpenPGP setup from commit policy.
---
 doc/contributing.texi | 59 ++++++++++++++++++++++++++++---------------
 1 file changed, 38 insertions(+), 21 deletions(-)

Le 27 mai 2021 08:35:52 GMT-04:00, "Ludovic Courtès" <ludo@gnu.org> a écrit :
>* doc/contributing.texi (Commit Access): Add introduction and section
>heading.  Separate OpenPGP setup from commit policy.
>---
> doc/contributing.texi | 59 ++++++++++++++++++++++++++++---------------
> 1 file changed, 38 insertions(+), 21 deletions(-)
>
>diff --git a/doc/contributing.texi b/doc/contributing.texi
>index cfcae22502..7dc912b4de 100644
>--- a/doc/contributing.texi
>+++ b/doc/contributing.texi
>@@ -1258,8 +1258,19 @@ this nifty tool!
> @section Commit Access
> 
> @cindex commit access, for developers
>-For frequent contributors, having write access to the repository is
>-convenient.  When you deem it necessary, consider applying for commit
>+Everyone can contribute to Guix without having commit access
>+(@pxref{Submitting Patches}).  However, for frequent contributors,
>+having write access to the repository can be convenient.  Commit
>access
>+should not be thought of as a ``badge of honor'' but rather as a
>+responsibility a contributor is willing to take to help the project.
>+
>+The following sections explain how to get commit access, how to be
>ready
>+to push commits, and the policies and community expectations for
>commits
>+pushed upstream.
>+
>+@subsection Applying for Commit Access
>+
>+When you deem it necessary, consider applying for commit
> access by following these steps:
> 
> @enumerate
>@@ -1331,6 +1342,27 @@ review and merging system, which, as a
>consequence, may lead us to have
> fewer people with commit access to the main repository.  Stay tuned!
> @end quotation
> 
>+All commits that are pushed to the central repository on Savannah must
>+be signed with an OpenPGP key, and the public key should be uploaded
>to
>+your user account on Savannah and to public key servers, such as
>+@code{keys.openpgp.org}.  To configure Git to automatically sign
>+commits, run:
>+
>+@example
>+git config commit.gpgsign true
>+git config user.signingkey CABBA6EA1DC0FF33
>+@end example
>+
>+You can prevent yourself from accidentally pushing unsigned commits to
>+Savannah by using the pre-push Git hook called located at
>+@file{etc/git/pre-push}:

This sentence sounds weird. Isn't "called" superfluous?

>+
>+@example
>+cp etc/git/pre-push .git/hooks/pre-push
>+@end example
>+
>+@subsection Commit Policy
>+
> If you get commit access, please make sure to follow
> the policy below (discussions of the policy can take place on
> @email{guix-devel@@gnu.org}).
>@@ -1349,25 +1381,6 @@ mailing list for commit notifications
>(@email{guix-commits@@gnu.org}),
> so people can notice.  Before pushing your changes, make sure to run
> @code{git pull --rebase}.
> 
>-All commits that are pushed to the central repository on Savannah must
>-be signed with an OpenPGP key, and the public key should be uploaded
>to
>-your user account on Savannah and to public key servers, such as
>-@code{keys.openpgp.org}.  To configure Git to automatically sign
>-commits, run:
>-
>-@example
>-git config commit.gpgsign true
>-git config user.signingkey CABBA6EA1DC0FF33
>-@end example
>-
>-You can prevent yourself from accidentally pushing unsigned commits to
>-Savannah by using the pre-push Git hook called located at
>-@file{etc/git/pre-push}:
>-
>-@example
>-cp etc/git/pre-push .git/hooks/pre-push
>-@end example
>-
> When pushing a commit on behalf of somebody else, please add a
> @code{Signed-off-by} line at the end of the commit log message---e.g.,
> with @command{git am --signoff}.  This improves tracking of who did
>@@ -1389,12 +1402,16 @@ you're confident, it's OK to commit.
>That last part is subject to being adjusted, allowing individuals to
>commit
> directly on non-controversial changes on parts they’re familiar with.
> 
>+@subsection Commit Revocation
>+
> In order to reduce the possibility of mistakes, committers will have
>their Savannah account removed from the Guix Savannah project and their
> key removed from @file{.guix-authorizations} after 12 months of
> inactivity; they can ask to regain commit access by emailing the
> maintainers, without going through the vouching process.
> 
>+@subsection Helping Out
>+
>One last thing: the project keeps moving forward because committers not
> only push their own awesome changes, but also offer some of their time
> @emph{reviewing} and pushing other people's changes.  As a committer,

Ludovic Courtès schreef op do 27-05-2021 om 14:35 [+0200]:
> +All commits that are pushed to the central repository on Savannah must
> +be signed with an OpenPGP key, and the public key should be uploaded to
> +your user account on Savannah and to public key servers, such as
> +@code{keys.openpgp.org}.  To configure Git to automatically sign
> +commits, run:
> +
> +@example
> +git config commit.gpgsign true
> +git config user.signingkey CABBA6EA1DC0FF33
> +@end example

Is that meant to represent ‘cabbage and coffee’ in l33t?
Maybe replace this with something like

+@example
> +git config commit.gpgsign true
> +# Substitute the fingerprint of your public PGP key
> +git config user.signingkey CABBA6EA1DC0FF33
> +@end example

Basic, I know, but people have to learn the basics from
somewhere, so maybe best be explicit here.

> + [... some newlines after @section{...} ]

These extra newlines could go directly into 'master' I guess.
The rest of [PATCH 1/3] seems ok to me?

Greetings,
Maxime.

Hi Julien & Maxime,

Julien Lepiller <julien@lepiller.eu> skribis:

>>+@example
>>+git config commit.gpgsign true
>>+git config user.signingkey CABBA6EA1DC0FF33
>>+@end example
>>+
>>+You can prevent yourself from accidentally pushing unsigned commits to
>>+Savannah by using the pre-push Git hook called located at
>>+@file{etc/git/pre-push}:
>
> This sentence sounds weird. Isn't "called" superfluous?

[...]

>> +@example
>> +git config commit.gpgsign true
>> +git config user.signingkey CABBA6EA1DC0FF33
>> +@end example
>
> Is that meant to represent ‘cabbage and coffee’ in l33t?
> Maybe replace this with something like
>
> +@example
>> +git config commit.gpgsign true
>> +# Substitute the fingerprint of your public PGP key
>> +git config user.signingkey CABBA6EA1DC0FF33
>> +@end example
>
> Basic, I know, but people have to learn the basics from
> somewhere, so maybe best be explicit here.

Yes, that makes sense to me.

Note that this text is not new, the patch merely shuffles it around.
But I agree, I’ll address the two issues above once we’ve agreed on the
rest.

>> + [... some newlines after @section{...} ]
>
> These extra newlines could go directly into 'master' I guess.
> The rest of [PATCH 1/3] seems ok to me?

I don’t know.  :-)

Patch #1 just moves text around and adds sectioning.

BTW, the whole patch series targets ‘master’ (there’s no point in
documenting our procedures in a branch other than ‘master’).

Thanks,
Ludo’.