[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Ludovic Courtès]

Hello Guix!

Happy new year, merry 12 nivôse, or whatever celebration is
appropriate for you!  :-)

These patches do three things:

  1. Move text from ‘HACKING’ to ‘doc/contributing.texi’.

  2. Encourage patch review for committers.

  3. Add a tentative policy for granting commit access (the last
     patch of this series).

I expect #1 and #2 to be uncontroversial, but I’d like feedback on #3!

So far, we’ve been giving commit access in a very ad-hoc fashion.
Often it was Ricardo or myself who ended up taking care of that,
even though other people have admin rights on Savannah to add/remove
members.

We briefly discussed it among maintainers after the maintainer
collective expanded, and it seems to me that perhaps now is a good time
to formalize things a bit—to clarify what contributors may expect and
to increase transparency.  Hence this proposal of a simple co-optation
policy.

As you know, Chris Baines has been working towards automated testing
of submitted patches.  One of the goals is to allow part of the
QA to be automated, such that, eventually, approved merges could be
automated.  In that spirit, we would have an incentive to not add more
committers (probably also a good thing security-wise).  That’s why I
added a note on this topic.

What do people think?

Thanks,
Ludo’.

Ludovic Courtès (4):
  doc: Add "Tracking Bugs and Patches" section.
  doc: Move "Commit Access" section from 'HACKING' to the manual.
  doc: Encourage patch review.
  DRAFT doc: Add a cooption policy for commit access.

 HACKING               |  58 +-------------
 doc/contributing.texi | 171 ++++++++++++++++++++++++++++++++++++++++--
 doc/guix.texi         |   2 +-
 3 files changed, 168 insertions(+), 63 deletions(-)

-- 
2.24.1

[bug#38846] [PATCH 1/4] doc: Add "Tracking Bugs and Patches" section.

[Ludovic Courtès]

* doc/contributing.texi (Tracking Bugs and Patches): New section.
(Submitting Patches): Refer to it.
* doc/guix.texi: Update copyright line.
* HACKING (Using emacs-debbugs): Remove.
---
 HACKING               | 11 +-------
 doc/contributing.texi | 62 ++++++++++++++++++++++++++++++++++++++-----
 doc/guix.texi         |  2 +-
 3 files changed, 58 insertions(+), 17 deletions(-)

diff --git a/HACKING b/HACKING
index 2f0f93f896..eeea2f6311 100644
--- a/HACKING
+++ b/HACKING
@@ -2,7 +2,7 @@
 
 #+TITLE: Hacking GNU Guix and Its Incredible Distro
 
-Copyright © 2012, 2013, 2014, 2016, 2017, 2019 Ludovic Courtès <ludo@gnu.org>
+Copyright © 2012, 2013, 2014, 2016, 2017, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
 Copyright © 2015, 2017 Mathieu Lirzin <mthl@gnu.org>
 Copyright © 2017 Leo Famulari <leo@famulari.name>
 Copyright © 2017 Arun Isaac <arunisaac@systemreboot.net>
@@ -63,12 +63,3 @@ after two weeks, and if 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.
-
-* Using emacs-debbugs
-
-Bug reports and patches are tracked using debbugs. If you are on emacs, you
-can use emacs-debbugs.
-
-List all open bug reports on guix-patches with
-
-C-u M-x debbugs-gnu <RET> <RET> guix-patches <RET> n y
diff --git a/doc/contributing.texi b/doc/contributing.texi
index e656676c0f..fd27f037e9 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -26,6 +26,7 @@ choice.
 * Packaging Guidelines::        Growing the distribution.
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
+* Tracking Bugs and Patches::   Using Debbugs.
 @end menu
 
 @node Building from Git
@@ -827,12 +828,12 @@ Thus, access to the repository is not strictly necessary.  We welcome
 contributions in the form of patches as produced by @code{git
 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
 
-This mailing list is backed by a Debbugs instance accessible at
-@uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track
-of submissions.  Each message sent to that mailing list gets a new
-tracking number assigned; people can then follow up on the submission by
-sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
-the tracking number (@pxref{Sending a Patch Series}).
+This mailing list is backed by a Debbugs instance, which allows us to
+keep track of submissions (@pxref{Tracking Bugs and Patches}).  Each
+message sent to that mailing list gets a new tracking number assigned;
+people can then follow up on the submission by sending email to
+@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
+number (@pxref{Sending a Patch Series}).
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -1040,3 +1041,52 @@ they are kept together.  See
 for more information.  You can install @command{git send-email} with
 @command{guix install git:send-email}.
 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
+
+@node Tracking Bugs and Patches
+@section Tracking Bugs and Patches
+
+@cindex bug reports, tracking
+@cindex patch submissions, tracking
+@cindex issue tracking
+@cindex Debbugs, issue tracking system
+Bug reports and patch submissions are currently tracked using the
+Debbugs instance at @uref{https://bugs.gnu.org}.  Bug reports are filed
+against the @code{guix} ``package'' (in Debbugs parlance), by sending
+email to @email{bug-guix@@gnu.org}, while patch submissions are filed
+against the @code{guix-patches} package by sending email to
+@email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
+
+A web interface (actually @emph{two} web interfaces!) are available to
+browse issues:
+
+@itemize
+@item
+@url{https://bugs.gnu.org/guix} lists bug reports;
+@item
+@url{https://bugs.gnu.org/guix-patches} lists patch submissions.
+@end itemize
+
+You can also access both of these @i{via} the (nicer)
+@url{https://issues.guix.gnu.org} interface@footnote{The web interface
+at @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
+software written in Guile, and you can help!  See
+@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.}.  To view
+discussions related to issue number @var{n}, go to
+@indicateurl{https://issues.guix.gnu.org/issue/@var{n}} or
+@indicateurl{https://bugs.gnu.org/@var{n}}.
+
+If you use Emacs, you may find it more convenient to interact with
+issues using @file{debbugs.el}, which you can install with:
+
+@example
+guix install emacs-debbugs
+@end example
+
+For example, to list all open issues on @code{guix-patches}, hit:
+
+@example
+@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
+@end example
+
+@xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
+this nifty tool!
diff --git a/doc/guix.texi b/doc/guix.texi
index 70e3dfea6a..999b7c9421 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -21,7 +21,7 @@
 @set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
 
 @copying
-Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@*
+Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès@*
 Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
 Copyright @copyright{} 2013 Nikita Karetnikov@*
 Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
-- 
2.24.1

[bug#38846] [PATCH 2/4] doc: Move "Commit Access" section from 'HACKING' to the manual.

[Ludovic Courtès]

* HACKING (Commit Access): Remove.
(Contributing): Update URL of the manual.
* doc/contributing.texi (Commit Access): New section.
(Submitting Patches): Add cross reference.
---
 HACKING               | 47 +---------------------------------
 doc/contributing.texi | 59 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 46 deletions(-)

diff --git a/HACKING b/HACKING
index eeea2f6311..36373278f9 100644
--- a/HACKING
+++ b/HACKING
@@ -17,49 +17,4 @@ See the manual for useful hacking informations, either by running
 
   info -f doc/guix.info "Contributing"
 
-or by checking the [[http://www.gnu.org/software/guix/manual/guix.html#Contributing][web copy of the manual]].
-
-* Commit Access
-
-For frequent contributors, having write access to the repository is
-convenient.  When you deem it necessary, feel free to ask for it on the
-mailing list.  When you get commit access, please make sure to follow the
-policy below (discussions of the policy can take place on guix-devel@gnu.org.)
-
-Non-trivial patches should always be posted to guix-patches@gnu.org (trivial
-patches include fixing typos, etc.).  This mailing list fills the
-patch-tracking database at [[https://bugs.gnu.org/guix-patches]]; see
-"Contributing" in the manual for details.
-
-For patches that just add a new package, and a simple one, it’s OK to commit,
-if you’re confident (which means you successfully built it in a chroot setup,
-and have done a reasonable copyright and license auditing.)  Likewise for
-package upgrades, except upgrades that trigger a lot of rebuilds (for example,
-upgrading GnuTLS or GLib.)  We have a mailing list for commit notifications
-(guix-commits@gnu.org), so people can notice.  Before pushing your changes,
-make sure to run ‘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
-‘keys.openpgp.org’.  To configure Git to automatically sign commits,
-run:
-
-  git config commit.gpgsign true
-  git config user.signingkey CABBA6EA1DC0FF33
-
-You can prevent yourself from accidentally pushing unsigned commits to
-Savannah by using the pre-push Git hook called located at ‘etc/git/pre-push’:
-
-  cp etc/git/pre-push .git/hooks/pre-push
-
-When pushing a commit on behalf of somebody else, please add a Signed-off-by
-line at the end of the commit log message (e.g. with ‘git am --signoff’).
-This improves tracking of who did what.
-
-For anything else, please post to guix-patches@gnu.org and leave time for a
-review, without committing anything.  If you didn’t receive any reply
-after two weeks, and if 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.
+or by checking the [[https://guix.gnu.org/manual/devel/en/html_node/Contributing.html][web copy of the manual]].
diff --git a/doc/contributing.texi b/doc/contributing.texi
index fd27f037e9..e6e6ab36c2 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -27,6 +27,7 @@ choice.
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
 * Tracking Bugs and Patches::   Using Debbugs.
+* Commit Access::               Pushing to the official repository.
 @end menu
 
 @node Building from Git
@@ -827,6 +828,8 @@ Development is done using the Git distributed version control system.
 Thus, access to the repository is not strictly necessary.  We welcome
 contributions in the form of patches as produced by @code{git
 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
+Seasoned Guix developers may also want to look at the section on commit
+access (@pxref{Commit Access}).
 
 This mailing list is backed by a Debbugs instance, which allows us to
 keep track of submissions (@pxref{Tracking Bugs and Patches}).  Each
@@ -1090,3 +1093,59 @@ For example, to list all open issues on @code{guix-patches}, hit:
 
 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
 this nifty tool!
+
+@node Commit Access
+@section Commit Access
+
+@cindex commit access, for developers
+For frequent contributors, having write access to the repository is
+convenient.  When you deem it necessary, feel free to ask for it on the
+mailing list.  When 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}).
+
+Non-trivial patches should always be posted to
+@email{guix-patches@@gnu.org} (trivial patches include fixing typos,
+etc.).  This mailing list fills the patch-tracking database
+(@pxref{Tracking Bugs and Patches}).
+
+For patches that just add a new package, and a simple one, it's OK to
+commit, if you're confident (which means you successfully built it in a
+chroot setup, and have done a reasonable copyright and license
+auditing).  Likewise for package upgrades, except upgrades that trigger
+a lot of rebuilds (for example, upgrading GnuTLS or GLib).  We have a
+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
+what.
+
+For anything else, please post to @email{guix-patches@@gnu.org} and
+leave time for a review, without committing anything (@pxref{Submitting
+Patches}).  If you didn’t receive any reply after two weeks, and if
+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.
-- 
2.24.1

[bug#38846] [PATCH 2/4] doc: Move "Commit Access" section from 'HACKING' to the manual.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> * HACKING (Commit Access): Remove.
> (Contributing): Update URL of the manual.
> * doc/contributing.texi (Commit Access): New section.
> (Submitting Patches): Add cross reference.

LGTM!

-- 
Ricardo

[bug#38846] [PATCH 3/4] doc: Encourage patch review.

[Ludovic Courtès]

* doc/contributing.texi (Commit Access): Add note about patch review.
---
 doc/contributing.texi | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index e6e6ab36c2..74b4718eb3 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1149,3 +1149,9 @@ 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.
+
+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,
+you're welcome to use your expertise and commit rights to help other
+contributors, too!
-- 
2.24.1

[bug#38846] [PATCH 3/4] doc: Encourage patch review.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> * doc/contributing.texi (Commit Access): Add note about patch review.
> ---
>  doc/contributing.texi | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index e6e6ab36c2..74b4718eb3 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -1149,3 +1149,9 @@ 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.
> +
> +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,
> +you're welcome to use your expertise and commit rights to help other
> +contributors, too!

Perfect!

-- 
Ricardo

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ludovic Courtès]

DRAFT: Subject to discussion!

* doc/contributing.texi (Commit Access): Draft a cooptation policy.
---
 doc/contributing.texi | 48 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 74b4718eb3..6e2cc1a369 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1099,8 +1099,52 @@ this nifty tool!
 
 @cindex commit access, for developers
 For frequent contributors, having write access to the repository is
-convenient.  When you deem it necessary, feel free to ask for it on the
-mailing list.  When you get commit access, please make sure to follow
+convenient.  When you deem it necessary, consider applying for commit
+access by following these steps:
+
+@enumerate
+@item
+Find three committers who would vouch for you, emailing a signed
+statement to @email{guix-maintainers@@gnu.org} (a private alias for the
+collective of maintainers).  You can view the list of committers at
+@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.
+
+Committers are expected to have had some interactions with you as a
+contributor and to be able to judge whether you are sufficiently
+familiar with the project's practices.  It is @emph{not} a judgment on
+the quality of your work, so a refusal should rather be interpreted as
+``let's try again later''.
+
+@item
+Send @email{guix-maintainers@@gnu.org} a signed message stating your
+intent, listing the three committers who support your application, and
+giving the fingerprint of the OpenPGP key you will use to sign commits
+(see below).
+
+@item
+Once you've been given access, please send a message to
+@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
+you will use to sign commits.  That way, everyone can notice and ensure
+you control that OpenPGP key.
+
+@c TODO: Add note about adding the fingerprint to the list of authorized
+@c keys once that has stabilized.
+
+@item
+Make sure to read the rest of this section and... profit!
+@end enumerate
+
+@quotation Note
+Maintainers are happy to give commit access to people who have been
+contributing for some time and have a track record---don't be shy and
+don't underestimate your work!
+
+However, note that the project is working towards a more automated patch
+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
+
+When 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}).
 
-- 
2.24.1

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> DRAFT: Subject to discussion!
>
> * doc/contributing.texi (Commit Access): Draft a cooptation policy.

I like this!

> +Find three committers who would vouch for you, emailing a signed
> +statement to @email{guix-maintainers@@gnu.org} (a private alias for the
> +collective of maintainers).  You can view the list of committers at
> +@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.

I misinterpreted this to mean that the three committers would need to
sign their endorsement…

> +
> +@item
> +Send @email{guix-maintainers@@gnu.org} a signed message stating your
> +intent, listing the three committers who support your application, and
> +giving the fingerprint of the OpenPGP key you will use to sign commits
> +(see below).

I think it may be necessary to state that “signed” means the use of a
cryptographic signature here and not just “~~ Rekado” (as it would be
done on the Wikipedia for example).  Perhaps we could link to the email
self defense guide of the FSF?

    https://emailselfdefense.fsf.org/en/

Thank you for the draft!

--
Ricardo

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ludovic Courtès]

Hello!

Ricardo Wurmus <rekado@elephly.net> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> DRAFT: Subject to discussion!
>>
>> * doc/contributing.texi (Commit Access): Draft a cooptation policy.
>
> I like this!
>
>> +Find three committers who would vouch for you, emailing a signed
>> +statement to @email{guix-maintainers@@gnu.org} (a private alias for the
>> +collective of maintainers).  You can view the list of committers at
>> +@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.
>
> I misinterpreted this to mean that the three committers would need to
> sign their endorsement…

That’s actually what I meant, but perhaps this is ambiguous?

>> +
>> +@item
>> +Send @email{guix-maintainers@@gnu.org} a signed message stating your
>> +intent, listing the three committers who support your application, and
>> +giving the fingerprint of the OpenPGP key you will use to sign commits
>> +(see below).
>
> I think it may be necessary to state that “signed” means the use of a
> cryptographic signature here and not just “~~ Rekado” (as it would be
> done on the Wikipedia for example).  Perhaps we could link to the email
> self defense guide of the FSF?
>
>     https://emailselfdefense.fsf.org/en/

Good points.

Taking these comments into accounts, I get:

--8<---------------cut here---------------start------------->8---
@enumerate
@item
Find three committers who would vouch for you.  You can view the list of
committers at
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.  Each
of them should email a statement to @email{guix-maintainers@@gnu.org} (a
private alias for the collective of maintainers), signed with their
OpenPGP key.

Committers are expected to have had some interactions with you as a
contributor and to be able to judge whether you are sufficiently
familiar with the project's practices.  It is @emph{not} a judgment on
the quality of your work, so a refusal should rather be interpreted as
``let's try again later''.

@item
Send @email{guix-maintainers@@gnu.org} a message stating your intent,
listing the three committers who support your application, signed with
the OpenPGP key you will use to sign commits, and giving its fingerprint
(see below).  See @uref{https://emailselfdefense.fsf.org/en/}, for an
introduction to public-key cryptography with GnuPG.

@item
Once you've been given access, please send a message to
@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
you will use to sign commits.  That way, everyone can notice and ensure
you control that OpenPGP key.

@c TODO: Add note about adding the fingerprint to the list of authorized
@c keys once that has stabilized.

@item
Make sure to read the rest of this section and... profit!
@end enumerate
--8<---------------cut here---------------end--------------->8---

Thanks for your feedback!

Ludo’.

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Maxim Cournoyer]

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

Hi Ludo,

Thank you for taking the time to draft this new policy.

Ludovic Courtès <ludo@gnu.org> writes:


[...]

> Taking these comments into accounts, I get:
>
> @enumerate
> @item
> Find three committers who would vouch for you.  You can view the list of
> committers at
> @url{https://savannah.gnu.org/project/memberlist.php?group=guix}.  Each
> of them should email a statement to @email{guix-maintainers@@gnu.org} (a
> private alias for the collective of maintainers), signed with their
> OpenPGP key.
>
> Committers are expected to have had some interactions with you as a
> contributor and to be able to judge whether you are sufficiently
> familiar with the project's practices.  It is @emph{not} a judgment on
> the quality of your work, so a refusal should rather be interpreted as
> ``let's try again later''.
>
> @item
> Send @email{guix-maintainers@@gnu.org} a message stating your intent,
> listing the three committers who support your application, signed with
> the OpenPGP key you will use to sign commits, and giving its fingerprint
> (see below).  See @uref{https://emailselfdefense.fsf.org/en/}, for an
> introduction to public-key cryptography with GnuPG.

Note that Email Self-Defense focuses on the use of Thunderbird + the
Enigmail plugin, both of which are missing from our collection of
packages.  I don't have a better resource to suggest, though.

> @item
> Once you've been given access, please send a message to
> @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
> you will use to sign commits.  That way, everyone can notice and ensure
> you control that OpenPGP key.
>
> @c TODO: Add note about adding the fingerprint to the list of authorized
> @c keys once that has stabilized.
>
> @item
> Make sure to read the rest of this section and... profit!
> @end enumerate
>
> Thanks for your feedback!
>
> Ludo’.

I like the proposal drafted so far.  I agree with others that it is
important to say that the maintainers reserve the final say in whether
or not a contributor is granted push rights to the Guix repository, for
transparency.

LGTM :-)

Maxim

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[zimoun]

Hi,

Nice proposal!


On Wed, 1 Jan 2020 at 17:36, Ludovic Courtès <ludo@gnu.org> wrote:

> +Committers are expected to have had some interactions with you as a
> +contributor and to be able to judge whether you are sufficiently
> +familiar with the project's practices.  It is @emph{not} a judgment on
> +the quality of your work, so a refusal should rather be interpreted as
> +``let's try again later''.

Cutting the hairs: on one hand "be able to judge" on practices and on
the other hand "not a judgment on the quality".
Even if I understand the idea behind (I guess), I do not find it well
worded, if I might.
I mean, I bet that "the quality of work" is a strong part when
motivating the acceptance or the refusal, so yes it is "a judgment on
the quality of your work" (but not only).
Quality implies standards and practices; quality can be measured (more
or less). From my understanding.

Instead of 'quality', I propose 'value' which is more subjective.

Well, my English is not very good...


> +However, note that the project is working towards a more automated patch
> +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

I find inappropriate the "Stay tuned!" in the manual.


Cheers,
simon

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ludovic Courtès]

Hello!

zimoun <zimon.toutoune@gmail.com> skribis:

> On Wed, 1 Jan 2020 at 17:36, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> +Committers are expected to have had some interactions with you as a
>> +contributor and to be able to judge whether you are sufficiently
>> +familiar with the project's practices.  It is @emph{not} a judgment on
>> +the quality of your work, so a refusal should rather be interpreted as
>> +``let's try again later''.
>
> Cutting the hairs: on one hand "be able to judge" on practices and on
> the other hand "not a judgment on the quality".
> Even if I understand the idea behind (I guess), I do not find it well
> worded, if I might.
> I mean, I bet that "the quality of work" is a strong part when
> motivating the acceptance or the refusal, so yes it is "a judgment on
> the quality of your work" (but not only).
> Quality implies standards and practices; quality can be measured (more
> or less). From my understanding.
>
> Instead of 'quality', I propose 'value' which is more subjective.

I agree that “value” sounds more appropriate here.  Fixed!

>> +However, note that the project is working towards a more automated patch
>> +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
>
> I find inappropriate the "Stay tuned!" in the manual.

Because it’s too informal, or because it’s confusing?  (The former is
fine with me.)

Thanks,
Ludo’.

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[zimoun]

Hi Ludo,

On Thu, 2 Jan 2020 at 12:53, Ludovic Courtès <ludo@gnu.org> wrote:

> zimoun <zimon.toutoune@gmail.com> skribis:

> > I find inappropriate the "Stay tuned!" in the manual.
>
> Because it’s too informal, or because it’s confusing?  (The former is
> fine with me.)

Maybe a bit of both. :-)

It is an analogy, but I feel the same than if I read a manual of maths
with "stay tuned" after a theorem as the proof. I feel in the same
time not enough formal for a manual and I am confused: is it already
proved and not written down yet or is it not proven yet?

Well, it is my feedback when I read it. :-)
And I feel cutting the hair in small pieces... French bias. ;-)


Thank you for the initiative. Cool!

All the best,
simon

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ludovic Courtès]

Hi!

zimoun <zimon.toutoune@gmail.com> skribis:

> On Thu, 2 Jan 2020 at 12:53, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> zimoun <zimon.toutoune@gmail.com> skribis:
>
>> > I find inappropriate the "Stay tuned!" in the manual.
>>
>> Because it’s too informal, or because it’s confusing?  (The former is
>> fine with me.)
>
> Maybe a bit of both. :-)
>
> It is an analogy, but I feel the same than if I read a manual of maths
> with "stay tuned" after a theorem as the proof. I feel in the same
> time not enough formal for a manual and I am confused: is it already
> proved and not written down yet or is it not proven yet?

Heh.  Well I guess it doesn’t bring much anyway, we can remove it.

Thanks,
Ludo’.

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Brett Gilio]

Ludovic Courtès <ludo@gnu.org> writes:

> +Find three committers who would vouch for you, emailing a signed
> +statement to @email{guix-maintainers@@gnu.org} (a private alias for the
> +collective of maintainers).  You can view the list of committers at
> +@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.
> +
> +Committers are expected to have had some interactions with you as a
> +contributor and to be able to judge whether you are sufficiently
> +familiar with the project's practices.  It is @emph{not} a judgment on
> +the quality of your work, so a refusal should rather be interpreted as
> +``let's try again later''.

Maybe it is superfluous, because maintainers have the final say
anyways. But I think getting vouching approval by three committers and
one maintainer would be a fine idea.

Wdyt?

-- 
Brett M. Gilio
GNU Guix, Contributor | GNU Project, Webmaster
[DFC0 C7F7 9EE6 0CA7 AE55 5E19 6722 43C4 A03F 0EEE]
<brettg@gnu.org> <brettg@posteo.net>

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ricardo Wurmus]

Brett Gilio <brettg@gnu.org> writes:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> +Find three committers who would vouch for you, emailing a signed
>> +statement to @email{guix-maintainers@@gnu.org} (a private alias for the
>> +collective of maintainers).  You can view the list of committers at
>> +@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.
>> +
>> +Committers are expected to have had some interactions with you as a
>> +contributor and to be able to judge whether you are sufficiently
>> +familiar with the project's practices.  It is @emph{not} a judgment on
>> +the quality of your work, so a refusal should rather be interpreted as
>> +``let's try again later''.
>
> Maybe it is superfluous, because maintainers have the final say
> anyways. But I think getting vouching approval by three committers and
> one maintainer would be a fine idea.

One long term goal is to reduce the dictatorial powers of maintainers
and shift more towards finding consensus or seeking consent.
Maintainers can’t know every new contributor, but they probably know
the committers who vouch for the new contributor.

--
Ricardo

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ludovic Courtès]

Hi Brett,

Brett Gilio <brettg@gnu.org> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> +Find three committers who would vouch for you, emailing a signed
>> +statement to @email{guix-maintainers@@gnu.org} (a private alias for the
>> +collective of maintainers).  You can view the list of committers at
>> +@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.
>> +
>> +Committers are expected to have had some interactions with you as a
>> +contributor and to be able to judge whether you are sufficiently
>> +familiar with the project's practices.  It is @emph{not} a judgment on
>> +the quality of your work, so a refusal should rather be interpreted as
>> +``let's try again later''.
>
> Maybe it is superfluous, because maintainers have the final say
> anyways. But I think getting vouching approval by three committers and
> one maintainer would be a fine idea.

The way I see it, it’s more about notifying maintainers than it’s about
asking them for approval; they could refuse someone, but the idea is
they’d usually do what other people agreed on.

Cooptation may allow us to scale better: it’s easy for maintainers to
simply lose track of who has been working on what and who should be
given commit access.

Thanks for your feedback,
Ludo’.

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Tobias Geerinckx-Rice via Guix-patches via]

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

Ludo',

Thank you for this series.

Ludovic Courtès 写道：
> +@item
> +Send @email{guix-maintainers@@gnu.org} a signed message stating 
> your
> +intent, listing the three committers who support your 
> application, and
> +giving the fingerprint of the OpenPGP key you will use to sign 
> commits
> +(see below).
> +
> +@item
> +Once you've been given access, please send a message to
   ^^^^

Probably just me, but this glosses over maintainer approval just a 
bit too deftly, and that even with 3 signed referrals commit 
access isn't guaranteed, just extremely likely.

Unless that will actually change, I think we should briefly 
mention it as well.  People react worse to ‘let's try again later’ 
when they think they've already passed.  Understandably so.

> +@email{guix-devel@@gnu.org} to say so, again signed with the 
> OpenPGP key
> +you will use to sign commits.  That way, everyone can notice 
> and ensure
> +you control that OpenPGP key.

Best to add an explicit ‘before pushing your first commit’ here, 
if that is the intent.

> +When you get commit access, please make sure to follow
   ^^^^

‘If’?  Same point as the first @items above.

Kind regards,

T G-R

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Tobias Geerinckx-Rice via Guix-patches via]

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

Tobias Geerinckx-Rice 写道：
> Ludo',
>
> Thank you for this series.

Speaking of being explicit: LGTM!

Kind regards,

T G-R

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Brett Gilio]

Tobias Geerinckx-Rice via Guix-patches via <guix-patches@gnu.org>
writes:

> Probably just me, but this glosses over maintainer approval just a bit
> too deftly, and that even with 3 signed referrals commit access isn't
> guaranteed, just extremely likely.
>
> Unless that will actually change, I think we should briefly mention it
> as well.  People react worse to ‘let's try again later’ when they
> think they've already passed.  Understandably so.

Hi Tobias,

This is definitely not just you. I felt similarly, as per a previous
email on the matter where I suggested that it be 3 commiters and 1
maintainer. But that process turned out to be redundant, if not
completely superfluous by Ricardo's mention of how the process is likely
to change in the future with a different integration model.

Regardless, I hear your point. I also think that getting refused after
achieving three referrals is a hard point. I think it should be
documented clearly that the mainters have the final say.

Additionally, and this is just a point for my part, depending on what
kind of merit we are taking for credence in a committer making a
referral, should we only consider committers who have worked closely
with the person requesting commit access, or is somebody who has
reviewed and seen their patches in passing also a viable subject?

For example, I have been asked a few times by people to push patches for
them over IRC, but their patches were unrelated to software I use /
would use / know how to approach (examples being GNOME). So, I kindly
refused to push their patch citing that I do not feel comfortable in
knowledge to understand the ramifications of their
patches. Hypothetically, if such a person approached me in the future
and asked for a commit access referral, since I had not worked closely
with them what kind of weight would be referral hold?

I hope this makes sense. Maybe I am being overly nitpicky, I just really
like clarity. :)

-- 
Brett M. Gilio
GNU Guix, Contributor | GNU Project, Webmaster
[DFC0 C7F7 9EE6 0CA7 AE55 5E19 6722 43C4 A03F 0EEE]
<brettg@gnu.org> <brettg@posteo.net>

[bug#38846] [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[zimoun]

Hi,

My end-user opinion does not matter. But the transparency is good. :-)


On Tue, 7 Jan 2020 at 01:19, Brett Gilio <brettg@gnu.org> wrote:
>
> Tobias Geerinckx-Rice via Guix-patches via <guix-patches@gnu.org>
> writes:
>
> > Probably just me, but this glosses over maintainer approval just a bit
> > too deftly, and that even with 3 signed referrals commit access isn't
> > guaranteed, just extremely likely.
> >
> > Unless that will actually change, I think we should briefly mention it
> > as well.  People react worse to ‘let's try again later’ when they
> > think they've already passed.  Understandably so.

[...]

> This is definitely not just you. I felt similarly, as per a previous
> email on the matter where I suggested that it be 3 commiters and 1
> maintainer. But that process turned out to be redundant, if not
> completely superfluous by Ricardo's mention of how the process is likely
> to change in the future with a different integration model.

I am not native  English speaker so maybe I misread. From my
understanding, the proposal clarifies how the access is granted.
Currently, only the maintainers grant; from what I have observed, it
is more because of historical reasons than an explicit model. The new
integration model proposes to enforce the trust and goes to
reduce/distribute the "power" of maintainers -- which is good IMHO.
Therefore, the maintainers trust the current committers, and if 3
committers approve, why should 1 maintainer reject the applicant? It
is a chain of trust.


> Regardless, I hear your point. I also think that getting refused after
> achieving three referrals is a hard point. I think it should be
> documented clearly that the mainters have the final say.

I do not see why. If 3 referrals vouch an applicant and 1 maintainer
refuses, then there is an issue elsewhere. The chain of trust is
broken and it means that the project is not healthy.


> Additionally, and this is just a point for my part, depending on what
> kind of merit we are taking for credence in a committer making a
> referral, should we only consider committers who have worked closely
> with the person requesting commit access, or is somebody who has
> reviewed and seen their patches in passing also a viable subject?

As an end-user, I do not want to pull "bad" code; which means not GNU
compliant. And a rule of thumb usually is: when you (committer) are
annoyed to review patches because you know that you would not do
better yourself; concretely, significant contributions with no final
tweaks.


> For example, I have been asked a few times by people to push patches for
> them over IRC, but their patches were unrelated to software I use /
> would use / know how to approach (examples being GNOME). So, I kindly
> refused to push their patch citing that I do not feel comfortable in
> knowledge to understand the ramifications of their
> patches. Hypothetically, if such a person approached me in the future
> and asked for a commit access referral, since I had not worked closely
> with them what kind of weight would be referral hold?

The bottleneck is the review. Well, I have tried to point out this here [1].

Sometime ago, "maintainer" of submodule had been discussed. For
example, one could imagine that the commit access comes with the
"responsibility" to take care of a submodule; with great power comes
great responsibility. ;-)


[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=38846#71


> I hope this makes sense. Maybe I am being overly nitpicky, I just really
> like clarity. :)

Me too, :-)


All the best,
simon

bug#38846: [PATCH 4/4] DRAFT doc: Add a cooption policy for commit access.

[Ludovic Courtès]

Hello,

Tobias Geerinckx-Rice <me@tobias.gr> skribis:

> Ludovic Courtès 写道：
>> +@item
>> +Send @email{guix-maintainers@@gnu.org} a signed message stating
>> your
>> +intent, listing the three committers who support your application,
>> and
>> +giving the fingerprint of the OpenPGP key you will use to sign
>> commits
>> +(see below).
>> +
>> +@item
>> +Once you've been given access, please send a message to
>   ^^^^
>
> Probably just me, but this glosses over maintainer approval just a bit
> too deftly, and that even with 3 signed referrals commit access isn't
> guaranteed, just extremely likely.
>
> Unless that will actually change, I think we should briefly mention it
> as well.  People react worse to ‘let's try again later’ when they
> think they've already passed.  Understandably so.

Good points (from Maxim, too).

>> +@email{guix-devel@@gnu.org} to say so, again signed with the
>> OpenPGP key
>> +you will use to sign commits.  That way, everyone can notice and
>> ensure
>> +you control that OpenPGP key.
>
> Best to add an explicit ‘before pushing your first commit’ here, if
> that is the intent.

Indeed.

>> +When you get commit access, please make sure to follow
>   ^^^^
>
> ‘If’?  Same point as the first @items above.

Yes.

I’ve now pushed the whole series:

  ef09cb866c doc: Add a cooptation policy for commit access.
  98ebcf1c1b doc: Encourage patch review.
  2d315cd428 doc: Move "Commit Access" section from 'HACKING' to the manual.
  a7bde77d24 doc: Add "Tracking Bugs and Patches" section.

I believe I’ve taken into account all the changes that were proposed.
If you think anything still needs to be adjusted, let’s do that.

Thanks everyone!

Ludo’.

[bug#38846] [PATCH 1/4] doc: Add "Tracking Bugs and Patches" section.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> * doc/contributing.texi (Tracking Bugs and Patches): New section.
> (Submitting Patches): Refer to it.
> * doc/guix.texi: Update copyright line.
> * HACKING (Using emacs-debbugs): Remove.

Looks good to me, thank you!

-- 
Ricardo

[bug#38846] [PATCH 1/4] doc: Add "Tracking Bugs and Patches" section.

[zimoun]

Hi Ludo,

On Wed, 1 Jan 2020 at 17:36, Ludovic Courtès <ludo@gnu.org> wrote:
>
> * doc/contributing.texi (Tracking Bugs and Patches): New section.
> (Submitting Patches): Refer to it.
> * doc/guix.texi: Update copyright line.
> * HACKING (Using emacs-debbugs): Remove.
> ---
>  HACKING               | 11 +-------
>  doc/contributing.texi | 62 ++++++++++++++++++++++++++++++++++++++-----
>  doc/guix.texi         |  2 +-
>  3 files changed, 58 insertions(+), 17 deletions(-)
>
> diff --git a/HACKING b/HACKING
> index 2f0f93f896..eeea2f6311 100644
> --- a/HACKING
> +++ b/HACKING
> @@ -2,7 +2,7 @@
>
>  #+TITLE: Hacking GNU Guix and Its Incredible Distro
>
> -Copyright © 2012, 2013, 2014, 2016, 2017, 2019 Ludovic Courtès <ludo@gnu.org>
> +Copyright © 2012, 2013, 2014, 2016, 2017, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
>  Copyright © 2015, 2017 Mathieu Lirzin <mthl@gnu.org>
>  Copyright © 2017 Leo Famulari <leo@famulari.name>
>  Copyright © 2017 Arun Isaac <arunisaac@systemreboot.net>
> @@ -63,12 +63,3 @@ after two weeks, and if 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.
> -
> -* Using emacs-debbugs
> -
> -Bug reports and patches are tracked using debbugs. If you are on emacs, you
> -can use emacs-debbugs.
> -
> -List all open bug reports on guix-patches with
> -
> -C-u M-x debbugs-gnu <RET> <RET> guix-patches <RET> n y

I thought the policy about copyright was when adding/changing lines,
not when removing them.

https://lists.gnu.org/archive/html/guix-devel/2019-10/msg00473.html

Maybe I miss something.
Just to notice.

Otherwise, nice!

Cheers,
simon

[bug#38846] [PATCH 1/4] doc: Add "Tracking Bugs and Patches" section.

[Ludovic Courtès]

Hi Simon,

zimoun <zimon.toutoune@gmail.com> skribis:

> On Wed, 1 Jan 2020 at 17:36, Ludovic Courtès <ludo@gnu.org> wrote:
>>
>> * doc/contributing.texi (Tracking Bugs and Patches): New section.
>> (Submitting Patches): Refer to it.
>> * doc/guix.texi: Update copyright line.
>> * HACKING (Using emacs-debbugs): Remove.
>> ---
>>  HACKING               | 11 +-------
>>  doc/contributing.texi | 62 ++++++++++++++++++++++++++++++++++++++-----
>>  doc/guix.texi         |  2 +-
>>  3 files changed, 58 insertions(+), 17 deletions(-)
>>
>> diff --git a/HACKING b/HACKING
>> index 2f0f93f896..eeea2f6311 100644
>> --- a/HACKING
>> +++ b/HACKING
>> @@ -2,7 +2,7 @@
>>
>>  #+TITLE: Hacking GNU Guix and Its Incredible Distro
>>
>> -Copyright © 2012, 2013, 2014, 2016, 2017, 2019 Ludovic Courtès <ludo@gnu.org>
>> +Copyright © 2012, 2013, 2014, 2016, 2017, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
>>  Copyright © 2015, 2017 Mathieu Lirzin <mthl@gnu.org>
>>  Copyright © 2017 Leo Famulari <leo@famulari.name>
>>  Copyright © 2017 Arun Isaac <arunisaac@systemreboot.net>
>> @@ -63,12 +63,3 @@ after two weeks, and if 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.
>> -
>> -* Using emacs-debbugs
>> -
>> -Bug reports and patches are tracked using debbugs. If you are on emacs, you
>> -can use emacs-debbugs.
>> -
>> -List all open bug reports on guix-patches with
>> -
>> -C-u M-x debbugs-gnu <RET> <RET> guix-patches <RET> n y
>
> I thought the policy about copyright was when adding/changing lines,
> not when removing them.
>
> https://lists.gnu.org/archive/html/guix-devel/2019-10/msg00473.html
>
> Maybe I miss something.
> Just to notice.

Ah well, I have (add-hook 'write-file-functions 'copyright-update),
which took care of it.  :-)

Some projects (such as Gnulib) automatically update copyright years each
1st of January, so there are different practices.  But anyway, you’re
right that it’s a bit odd to add a new year here, I’ll remove it.

Thanks,
Ludo’.

[bug#38846] [PATCH 1/4] doc: Add "Tracking Bugs and Patches" section.

[zimoun]

Hi Ludo,

On Thu, 2 Jan 2020 at 12:51, Ludovic Courtès <ludo@gnu.org> wrote:

> Ah well, I have (add-hook 'write-file-functions 'copyright-update),
> which took care of it.  :-)

Ah cool!
I did not know this neat function. :-)


Cheers,
simon

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> As you know, Chris Baines has been working towards automated testing
> of submitted patches.  One of the goals is to allow part of the
> QA to be automated, such that, eventually, approved merges could be
> automated.  In that spirit, we would have an incentive to not add more
> committers (probably also a good thing security-wise).  That’s why I
> added a note on this topic.

I’m looking forward to this.  Ultimately, it is a good thing to limit
the number of people who can write to the repository.

-- 
Ricardo

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Ludovic Courtès]

Hello!

Just a heads-up for fellow maintainers (Tobias, Marius, Maxim): could
you send a “+1” or whatever you deem appropriate :-) to this discussion?
I’d like to make sure we’re on the same page.

  https://issues.guix.gnu.org/issue/38846

Ludo’.

Ludovic Courtès <ludo@gnu.org> skribis:

> Hello Guix!
>
> Happy new year, merry 12 nivôse, or whatever celebration is
> appropriate for you!  :-)
>
> These patches do three things:
>
>   1. Move text from ‘HACKING’ to ‘doc/contributing.texi’.
>
>   2. Encourage patch review for committers.
>
>   3. Add a tentative policy for granting commit access (the last
>      patch of this series).
>
> I expect #1 and #2 to be uncontroversial, but I’d like feedback on #3!
>
> So far, we’ve been giving commit access in a very ad-hoc fashion.
> Often it was Ricardo or myself who ended up taking care of that,
> even though other people have admin rights on Savannah to add/remove
> members.
>
> We briefly discussed it among maintainers after the maintainer
> collective expanded, and it seems to me that perhaps now is a good time
> to formalize things a bit—to clarify what contributors may expect and
> to increase transparency.  Hence this proposal of a simple co-optation
> policy.
>
> As you know, Chris Baines has been working towards automated testing
> of submitted patches.  One of the goals is to allow part of the
> QA to be automated, such that, eventually, approved merges could be
> automated.  In that spirit, we would have an incentive to not add more
> committers (probably also a good thing security-wise).  That’s why I
> added a note on this topic.
>
> What do people think?
>
> Thanks,
> Ludo’.
>
> Ludovic Courtès (4):
>   doc: Add "Tracking Bugs and Patches" section.
>   doc: Move "Commit Access" section from 'HACKING' to the manual.
>   doc: Encourage patch review.
>   DRAFT doc: Add a cooption policy for commit access.
>
>  HACKING               |  58 +-------------
>  doc/contributing.texi | 171 ++++++++++++++++++++++++++++++++++++++++--
>  doc/guix.texi         |   2 +-
>  3 files changed, 168 insertions(+), 63 deletions(-)

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Marius Bakke]

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

Ludovic Courtès <ludo@gnu.org> writes:

> Hello!
>
> Just a heads-up for fellow maintainers (Tobias, Marius, Maxim): could
> you send a “+1” or whatever you deem appropriate :-) to this discussion?
> I’d like to make sure we’re on the same page.
>
>   https://issues.guix.gnu.org/issue/38846

I've read through the changes and all LGTM.

Thanks!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[zimoun]

Hi,


On Wed, 1 Jan 2020 at 17:31, Ludovic Courtès <ludo@gnu.org> wrote:

>   1. Move text from ‘HACKING’ to ‘doc/contributing.texi’.
>
>   2. Encourage patch review for committers.
>
>   3. Add a tentative policy for granting commit access (the last
>      patch of this series).
>
> I expect #1 and #2 to be uncontroversial, but I’d like feedback on #3!
>
> So far, we’ve been giving commit access in a very ad-hoc fashion.
> Often it was Ricardo or myself who ended up taking care of that,
> even though other people have admin rights on Savannah to add/remove
> members.
>
> We briefly discussed it among maintainers after the maintainer
> collective expanded, and it seems to me that perhaps now is a good time
> to formalize things a bit—to clarify what contributors may expect and
> to increase transparency.  Hence this proposal of a simple co-optation
> policy.
>
> As you know, Chris Baines has been working towards automated testing
> of submitted patches.  One of the goals is to allow part of the
> QA to be automated, such that, eventually, approved merges could be
> automated.  In that spirit, we would have an incentive to not add more
> committers (probably also a good thing security-wise).  That’s why I
> added a note on this topic.
>
> What do people think?


Personally, I find this proposal nice. As I already said when
commenting on each patch. :-)

However, let point 2 minor weak points for further discussions:

 a- if the number of committers with access is more or less fixed,
then access could be transferred (less active, less time, less
motivation, etc.);
 and b- the bottleneck is the patch review (even if it should be
improved in the future with the Guix Data Service).
Well, a- is more about human relationship, hard to fix. However, we
should work on b- but how? What does it mean "encourage patch review"?
Candy or beer at Guix Days? ;-)

For example, this patch [1] has fallen in the crack. Or this one [2]
or this other one [3].

[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31973
[2] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=33041
[3] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=33318


From the v1.0.1 to now, the repartition of committers which are not the authors:

   361
     78
     65
     61
     59
     54
     52
     47
     44
     43
     37
     21  (x2)
     11
      9
      8
      7  (x2)
      6
      5  (x3)
      4  (x2)
      3
      2  (x3)
      1  (x3)

which should be compared to the number of commits per author also
committer (first 10):

   1463
   1162
    886
    670
    618
    335
    204
    166
    161
    150

--8<---------------cut here---------------start------------->8---
# committer and not the author
git log v1.0.1..origin/HEAD --pretty=format:"%an~%cn"     \
    | awk -F '~' '{if ($1 != $2) {++cnt; print "#"$2};}' \
    | sort                                               \
    | uniq -c                                            \
    | sort -nr                                           \
    | cut -f1 -d'#'
--8<---------------cut here---------------end--------------->8---

--8<---------------cut here---------------start------------->8---
# committer and the author
git log v1.0.1..origin/HEAD --pretty=format:"%an~%cn"     \
    | awk -F '~' '{if ($1 == $2) {++cnt; print "#"$2};}' \
    | sort                                               \
    | uniq -c                                            \
    | sort -nr                                           \
    | cut -f1 -d'#' | head -n10
--8<---------------cut here---------------end--------------->8---


It is easy to produce more stats, for the example the author time
versus the committer time, or the number of newcomers (first commit),
or the hour when committing.

Do not take me wrong, it is not about blaming but it is about health
and how it could be improved. All these numbers show how Guix is
healthy. :-)


Well, all this comment is about "2. Encourage patch review for
committers.". Patch review is about trust, so what could be done to
reduce the workload of "committers"?  and smooth everything? Team
and/or delegate? Formalize "maintainer per field" (R, Lisp, Python,
OCaml, maths, etc.)? Obviously without adding too formal stuff. :-)


All the best,
simon

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Ludovic Courtès]

Hi!

zimoun <zimon.toutoune@gmail.com> skribis:

> However, let point 2 minor weak points for further discussions:
>
>  a- if the number of committers with access is more or less fixed,
> then access could be transferred (less active, less time, less
> motivation, etc.);

Sure, we should (and do) remove people who “disappeared” or retired, and
of course welcome new people willing to participate.

>  and b- the bottleneck is the patch review (even if it should be
> improved in the future with the Guix Data Service).
> Well, a- is more about human relationship, hard to fix. However, we
> should work on b- but how? What does it mean "encourage patch review"?
> Candy or beer at Guix Days? ;-)

Heh.  :-)  This is the hard part for all free software projects.  As you
noticed, there’s no shortage of patches that have fallen through the
cracks, unfortunately.

The “encourage patch review” bit in this series, in my view, is to tell
newcomers that the deal is not just that they can push their own stuff
more quickly, but also that they can help others get their stuff in in
return.  It may sound obvious to some, but it’s probably better if
explicitly stated.  Also, perhaps we’ve had the problem where committers
did not feel “entitled” to review and push other people’s patches; this
paragraph is also a way to tell them that yes, they _are_ entitled to
that.

It won’t solve the problem overnight; offering a beverage at the Guix
Days won’t solve it either but it’s a good idea anyway.  :-)

Ludo’.

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Ludovic Courtès]

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

Hello!

zimoun <zimon.toutoune@gmail.com> skribis:

>>From the v1.0.1 to now, the repartition of committers which are not the authors:
>
>    361
>      78
>      65
>      61
>      59
>      54
>      52
>      47
>      44
>      43
>      37
>      21  (x2)
>      11
>       9
>       8
>       7  (x2)
>       6
>       5  (x3)
>       4  (x2)
>       3
>       2  (x3)
>       1  (x3)
>
> which should be compared to the number of commits per author also
> committer (first 10):
>
>    1463
>    1162
>     886
>     670
>     618
>     335
>     204
>     166
>     161
>     150

I had overlooked that; interesting, though I’m not sure what conclusion(s)
to draw.  Perhaps we should look at how these numbers evolve over time?

Related to that, attached is a script I wrote a while back to view the
number of reviews per committer (ah ha!), like so:

--8<---------------cut here---------------start------------->8---
scheme@(guile-user)> (define r (reviewers repo))
scheme@(guile-user)> ,pp (sort (map car r) <)
$3 = (0
 ;; long tail omitted…
 1
 1
 1
 1
 2
 2
 2
 2
 2
 4
 5
 5
 6
 9
 9
 9
 10
 11
 13
 13
 17
 18
 19
 30
 37
 37
 38
 40
 40
 45
 48
 51
 59
 63
 72
 84
 85
 88
 99
 181
 186
 264
 287
 506
 526
 1620)
--8<---------------cut here---------------end--------------->8---

This is for all-time commits, so not all that representative, but could
be used as a starting point for the statistician in you.  :-)

Ludo’.


[-- Attachment #2: the code --]
[-- Type: text/plain, Size: 2321 bytes --]

(use-modules (git)
             (git repository)
             (git reference)
             (git oid)
             (git tag)
             (git commit)
             (git structs)                        ;signature-email, etc.
             (srfi srfi-1)
             (srfi srfi-26)
             (ice-9 match)
             (ice-9 vlist))

(define commit-author*
  (compose signature-name commit-author))
(define commit-committer*
  (compose signature-name commit-committer))

(define-syntax-rule (false-if-git-error exp)
  (catch 'git-error
    (lambda () exp)
    (const #f)))

(define* (fold-commits proc seed repo
                       #:key
                       (start (reference-target
                               (repository-head repo)))
                       end)
  "Call PROC on each commit of REPO, starting at START (an OID), and until
END if specified."
  (let loop ((commit (commit-lookup repo start))
             (result seed))
    (let ((parent (false-if-git-error (commit-parent commit))))
      (if parent
          (if (and end (oid=? (commit-id parent) end))
              (proc parent result)
              (loop parent (proc parent result)))
          result))))

(define (reviewers repo)
  "Return a list of review count/committer pairs."
  (define vhash
    (fold-commits (lambda (commit result)
                    (if (string=? (commit-author* commit)
                                  (commit-committer* commit))
                        result
                        (vhash-cons (commit-committer* commit) #t
                                    result)))
                  vlist-null
                  repo))

  (define committers
    (delete-duplicates
     (fold-commits (lambda (commit result)
                     (cons (commit-committer* commit)
                           result))
                   '()
                   repo)))

  (map (lambda (committer)
         (cons (vhash-fold* (lambda (_ count)
                              (+ 1 count))
                            0
                            committer
                            vhash)
               committer))
       committers))

(define (reviewer< r1 r2)
  (match r1
    ((count1 . name1)
     (match r2
       ((count2 . name2)
        (< count1 count2))))))

(libgit2-init!)

(define repo
  (repository-open "."))

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[zimoun]

Hi Ludo,

On Thu, 9 Jan 2020 at 23:05, Ludovic Courtès <ludo@gnu.org> wrote:

> >>From the v1.0.1 to now, the repartition of committers which are not the authors:
> >
> >    361
> >      78
> >      65
> >      61
> >      59
> >      54
> >      52
> >      47
> >      44
> >      43
> >      37
> >      21  (x2)
> >      11
> >       9
> >       8
> >       7  (x2)
> >       6
> >       5  (x3)
> >       4  (x2)
> >       3
> >       2  (x3)
> >       1  (x3)
> >
> > which should be compared to the number of commits per author also
> > committer (first 10):
> >
> >    1463
> >    1162
> >     886
> >     670
> >     618
> >     335
> >     204
> >     166
> >     161
> >     150
>
> I had overlooked that; interesting, though I’m not sure what conclusion(s)
> to draw.  Perhaps we should look at how these numbers evolve over time?

If one re-associates the number of commits as committers to the number
of commits as authors, and computes the ratio (in percent and sorted),
the result is:

248.00
128.26
105.00
100.00
100.00
67.16
53.61
45.49
42.86
41.60
40.00
28.28
28.13
23.12
23.08
19.40
14.45
10.23
8.57
7.00
6.60
6.25
5.88
5.75
5.75
5.19
3.21
2.63
1.84
1.47
1.31
.73

To be clear, the person with the score of 53.61% "reviews" half as
many commits they authors.

And the mean is almost 37%. Cool, no?


Well, it is not possible to draw an strong conclusion, just a weak
one: Guix is healthy. ;-)

(For example, the number of commits should be weighted with the number
of lines changed.)


And yes, it should be interesting to see how evolves the commits rate
(as authors, as committers) over the time.


> Related to that, attached is a script I wrote a while back to view the
> number of reviews per committer (ah ha!), like so:

Cool!

Maybe this kind of metrics could be reported to the Guix Data Service.
Well, let start by play with your script. ;-)


> This is for all-time commits, so not all that representative, but could
> be used as a starting point for the statistician in you.  :-)

Héhé! You got me. ;-)


Cheers,
simon

[bug#38846] [PATCH 0/4] Move 'HACKING' to the manual, and a proposal for commit access

[Ludovic Courtès]

Hello,

zimoun <zimon.toutoune@gmail.com> skribis:

> To be clear, the person with the score of 53.61% "reviews" half as
> many commits they authors.
>
> And the mean is almost 37%. Cool, no?
>
>
> Well, it is not possible to draw an strong conclusion, just a weak
> one: Guix is healthy. ;-)

Oh yes, that’s an interesting (and nice!) conclusion.

Thanks,
Ludo’.