Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jun 17, 2021, 14:53 UTC
Message-ID: <87o8c4wkn7.fsf@evledraar.gmail.com>
In-Reply-To: <5755690e-ef13-e12c-4b10-9cb303ae843a@gmail.com>

On Thu, Jun 17 2021, Derrick Stolee wrote:

Show 21 quoted lines

> On 6/16/2021 8:09 PM, Junio C Hamano wrote:
>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> ...
>>> The references to "gendered prounouns" etc. are gone, perhaps there's a
>>> good reason to re-include them, but the point of "isn't that issue
>>> solved by recommending an orthagonal approach?" is one of the many
>>> things Stolee hasn't been addressing in the threads related to this
>>> series.
>>>
>>> To me that whole approach is somewhere between a solution in search of a
>>> problem and a "let's fix it and move on". Not something we need
>>> explicitly carry in our CodingGuidelines forever.
>> 
>> This I think is the crux of the differences between you two.  I'd
>> love to hear Derrick's response and eventually see a middle ground
>> reached.
>
> I disagree that removing gendered pronouns and updating the
> guidelines are orthogonal. At minimum, we shouldn't have
> guidelines that we do not follow, especially when they are
> small in number and we can fix them in a few patches.

Sorry, I read that a few times and I'm still not sure I get it.

Do you mean by "we shouldn't have guidelines that we do not follow" that we shouldn't engage in general tree-wide fixes unless we also have documented guidelines to back them up?

Or that the tree-wide changes for existing occurrences cannot be separated from having specific documented advice applicable to those occurances, or...?

If it's the first we have a bunch of tree-wide fixes that don't result in documented guidelines, e.g. we did a general replacement of http with https links recently. See 6eda9ac9e5 (doc: use https links, 2021-02-05). That's generally considered a good idea, I don't think we have a guideline, and I'd think we *probably* wouldn't need one for reasons similar to what I'm maintaining here.

> The entire point of this series was to reach a decision about
> gendered pronouns so we can stop having arguments about them
> when they come up.

Where have we been having those arguments? A reverse search of the ML for all time reverse ordered by date for the term shows the 20th result as the greater topic of this thread:

    https://lore.kernel.org/git/?q=pronouns&o=-1

You need to search a bit further to get to this thread, or the ~120th result for "gendered". Much of the earlier is false positives, and skimming it to the extent that it's code I'd say those cases would fall squarely under more "be brief, be succinct, UIDs aren't people" etc. advice:

    https://lore.kernel.org/git/?q=gendered&o=-1

In that context your "so we can stop[...]" somewhat sounds like "take my patches, or I won't stop talking about my patches" :)

> We should just be able to point to "here is
> the decision we made" and it's not enough to say "If you go
> look at the mailing list archive you can see that we removed
> all gendered pronouns so you shouldn't add them again."

And I'd probably agree with you if you were providing examples of how this is really some ongoing confusion, or pointing out how specific parts of the documentation, code, comments etc. that we're now aren't going to have that problem solved as a byproduct of more generally applicable style guide advice.

Can you point out specific hunks that you, me or Felipe have changed in our respective patches on this greater topic that wouldn't implicitly be covered under something like the advice I'm proposing upthread[1]?

> We need ways for contributors to self-discover these things.
> Anything less is doing a disservice to our fellow contributors.

We're in full agreement with that. I've often started writing some documentation patch and genuinely forgotten what the general tone of our documentation is.

Should I write "an option such as this", "this option", say "you can do", or "a user might" etc? I've then gone paging through the Documentation/ directory, and not being sure what's considered good current practice, and what's historical.

So I think we absolutely need general advice on how we write our documentation, their tone, how we talk about common things like CLI switches, program interaction etc.

But here in 1/4 we have two doc hunks being changed, one from 2007, one from 2013.

In 2/4 we've got 6 occurances in the whole tree. 2 are from Junio and the last time he sinned in that particular area was 2013. 2 are from a 2019 GSOC intern adding "she", one more from Jeff King in 2015, and one in 2014 from a person who last got a patch in git.git in in that same year.

I'm avoiding naming that 2019 GSOC intern b.t.w. because I for one wouldn't want to contribute to a project like git, do a search for my name on lore.kernel.org/git/ and see this thread. I.e. see that my addition of a pronoun referring to my gender in a comment has somehow become something that must be eliminated ... in order to get people like myself to feel like their contributions are more welcome.

That's less welcoming, not more. Just like this whole thread-at-large started by pouncing on another non-native English speaker's recent and obviously innocent use of the wrong pronoun in a commit message.

But I digress.

Going on, 3/4 are simple typos, and your original 4/4 is an implicit suggestion that (by approximate line count) 5% of everyone's time spent reading through CodingGuidelines is best spent reading about this always-obscure-and-now-gone-from-the-tree "issue" addressed in the previous 3 patches.

I'm suggesting that 5% of their time would be better spent on something that clearly has direct applicability to the maintenance of existing code and documentation, and the authoring of new works. I also think it happens to gives you 100% of the end result you want in terms of what code/docs we end up with in-tree.

1. https://lore.kernel.org/git/87bl85y15s.fsf@evledraar.gmail.com