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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Thu, Jun 17 2021, Derrick Stolee wrote:

> 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