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

[Ludovic Courtès]

* 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}:
+
+@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,
-- 
2.31.1