[bug#48696] [PATCH 2/3] doc: Add "Addressing Mistakes" section.

[Christopher Baines <mail@cbaines.net>]

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


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

> * doc/contributing.texi (Addressing Mistakes): New section.
> ---
>  doc/contributing.texi | 34 ++++++++++++++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
>
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 7dc912b4de..8308551261 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -1402,6 +1402,40 @@ 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 Addressing Mistakes
> +
> +We all make mistakes.  We expect peer review (@pxref{Submitting
> +Patches}) and tools such as @command{guix lint} (@pxref{Invoking guix
> +lint}) and the test suite (@pxref{Running the Test Suite}) to catch
> +issues before they are pushed; yet, mistakes might go through---that
> +happens to both newcomers and old-timers, and there is nothing to be
> +ashamed of when it happens.  As a community, we expect committers to
> +recognize and address mistakes as soon as possible.
> +
> +Some mistakes can directly affect all users---for instance because they
> +make @command{guix pull} fail or break core functionality, because they
> +break major packages (at build time or run time), or because they
> +introduce known security vulnerabilities.
> +
> +@cindex reverting commits
> +The person who pushed the faulty commit(s) should be at the forefront to
> +address such an issue in a timely fashion: by pushing a followup commit
> +to fix it (if possible), or by reverting it to leave time to come up
> +with a proper fix, and by communicating with other developers about the
> +problem.
> +
> +If the committer is unavailable to address the issue in time, other
> +committers are entitled to revert the offending commit(s), explaining in
> +the commit log and on the mailing list what the problem was, with the
> +goal of leaving time to the original committer and author(s) to propose
> +a way forward.
> +
> +The Guix project values friendly cooperation and a constant effort to
> +focus on the way forward when issues arise.  Committers should lead by
> +example, notably as a way to encourage contributors and contributors to
> +be.  Blame as well as defensiveness do not have their place in Guix when
> +addressing genuine mistakes.

I too would like to see less blame, but one factor is how things are
framed and the language used.

On the language here, "mistake" is a word I would generally avoid if the
aim is avoid blaming someone, since mistakes are made by a person or set
of people. I'd prefer a term like "problem", since I don't perceieve
that as directly linked to a person or set of people.

On the bit about the "person who pushed the faulty commits" (so, person
to blame...) I'd much prefer an emphisis on group responsibility to
mitigate the impact of problems quickly, and understand the factors that
led to that problems in the first place. That avoids assigning blame,
rather than the process pushing responsibility to the person to blame
("person who pushed the faulty commit(s)").

On this same thread, I'd like to see less blaming in the form of asking
people to "explain". When there's a problem, and you ask someone to
explain, I would interpret that as "I'm blaming you for this, please
give your account of how the mistake was made", to which the person can
either answer explaining the details as to why they are to blame, or can
disagree with the implicit assertion that they are to blame. To avoid
assigning blame, one can just ask someone to "describe" what happened,
which I wouldn't interpret as being loaded with the same implicit
assertion.

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