Subject: Re: [PATCH 1/4] Documentation: use singular they when appropriate

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Mon, 07 Jun 2021 20:21:35 +0200

On Mon, Jun 07 2021, Derrick Stolee wrote:

> On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
>> 
>> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
>> 
>>> From: Derrick Stolee <[email-masked]>
>>>
>>> There are several instances in our documentation where we refer to an
>>> anonymous user as "a contributor" or "an integrator" or similar. To
>>> avoid repeating this role, pronouns are used. Previous examples
>>> chose a gender for this user, using "he/him" or "she/her" arbitrarily.
>>>
>>> Replace these uses with "they/them" to ensure that these documentation
>>> examples apply to all potential users without exception.
>>>
>>> Signed-off-by: Derrick Stolee <[email-masked]>
>> 
>> I think this is mostly an improvement, however:
>> 
>>>  .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------
>> 
>> This is a quote from a mail of Junio's[1] (date and all). I don't think
>> it makes sense to copyedit that after the fact without at least editing
>> the header that indicates that it's a verbatim reproduction.
>> 
>> 1. https://lore.kernel.org/git/[email-masked]/
>
> That's a good point. It does look a little strange that there is
> an email in our Documentation/ directory. I wondered if this was
> included in the docs that get posted to git-scm.com, but I see that
> the link I manually constructed [1] redirects to the GitHub mirror.
>
> [1] https://git-scm.com/docs/howto/using-signed-tag-in-pull-request.txt

We have a few of those FWIW, try grepping for ^Subject Documentation/

It seems git-scm.com dosen't carry them, but googling around e.g. this
site does: https://gitirc.eu/howto/using-signed-tag-in-pull-request.html

> As long as this file remains formatted as an archived email message,
> the edits here are inappropriate. It's another question of whether the
> files within Documentation/howto should be updated to be docs that can
> be more easily posted in places like git-scm.com.

*Nod*, I have some unrelated patches to fix some of this state of
 affairs in Documentation/, but for now it's like that...

I do think there's a time & place for it though, and it's unfortunate
that we haven't done as much of this recently. We've had quite a few
"E-Mails of reference", and IMO we're better off with them in
Documentation/ than not at all, and if we require that they be formatted
into "normal" documentation we're probably closer to "not at all"...