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

Emily Shaffer [off-list ref] writes:

On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:

quoted

If we refer to a specific person, then using a gendered pronoun is
appropriate. Examples within the Git codebase include:

* References to real people (e.g. Linus Torvalds, "the Git maintainer").
  Do not misgender real people. If there is any doubt to the gender of a
  person, then use singular "they".

* References to fictional people with clear genders (e.g. Alice and
  Bob).

* Sample text used in test cases (e.g t3702, t6432).

* The official text of the GPL license contains uses of "he or she", but
  modifying the license this way is not within the scope of the Git
  project.

Other cases within the Git project were cleaned up by the previous
changes.

Signed-off-by: Derrick Stolee <redacted>

Well said.
Acked-by: Emily Shaffer <redacted>

quoted

---
 Documentation/CodingGuidelines | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index e3af089ecf26..78cd399f7cf5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines

@@ -648,3 +648,8 @@ Writing Documentation:
  inline substituted text+ instead of `monospaced literal text`, and with
  the former, the part that should not get substituted must be
  quoted/escaped.
+
+ When referring to an anonymous user, use singular "they/them" pronouns
+ as opposed to choosing between "he/him" and "she/her". Do not use more
+ complicated constructs such as "he or she" or "s/he". This recommendation
+ also applies to code comments and commit messages.

I am not sure if this "here is the rule and you will follow it" is
helpful without hinting what the rule is trying to achieve.  It is
more so that the four-bullet-point list in the proposed log message
that says when not to blindly apply the singular they rule will not
be seen by intended readers---we who are reviewing this change in
the patch form may understand and embrace it, but the readers have
less than we have to go with.

Perhaps start the whole paragraph a bit differently, like this?

    Refer to an anonymous user in a gender neutral way.  Use
    singular "they/them" pronouns as opposed to ...

The added single phase will be a sufficient clue to readers that
this is about inclusion, and will tell readers that singular they is
not a hard and fast rule but one of the suggested ways to achieve
that goal.  To be even clearer, we may probably want to add "One way
to do so is to" before the second sentence.

On 6/9/2021 12:44 AM, Junio C Hamano wrote:

Emily Shaffer [off-list ref] writes:

quoted

On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:

...

quoted

quoted

+
+ When referring to an anonymous user, use singular "they/them" pronouns
+ as opposed to choosing between "he/him" and "she/her". Do not use more
+ complicated constructs such as "he or she" or "s/he". This recommendation
+ also applies to code comments and commit messages.

I am not sure if this "here is the rule and you will follow it" is
helpful without hinting what the rule is trying to achieve.  It is
more so that the four-bullet-point list in the proposed log message
that says when not to blindly apply the singular they rule will not
be seen by intended readers---we who are reviewing this change in
the patch form may understand and embrace it, but the readers have
less than we have to go with.

I went to far trying to be brief in CodingGuidelines in favor of a
long commit message (that can be blamed). But you're right. "Start
with why" is a good strategy.
 

Perhaps start the whole paragraph a bit differently, like this?

    Refer to an anonymous user in a gender neutral way.  Use
    singular "they/them" pronouns as opposed to ...

The added single phase will be a sufficient clue to readers that
this is about inclusion, and will tell readers that singular they is
not a hard and fast rule but one of the suggested ways to achieve
that goal.  To be even clearer, we may probably want to add "One way
to do so is to" before the second sentence.

That's a good idea.

The other thing I have added is to recommend changing the sentence
to use different nouns so that singular "you" or plural "they" are
appropriate.

Thanks,
-Stolee