From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-07 16:57:53
In another topic, I claimed [1] that singular "they" was better than
"he/she" for gender neutrality.
[1]
https://lore.kernel.org/git/44d937a0-e876-e185-f409-a4fd61eae580@gmail.com/
The fact that singular "they" is less awkward to write and read seemed
obvious to me, so I did not back up my statement with any references or
reasons. The ensuing discussion did include reasons, especially brian m.
carlson's thoughtful message [2].
[2] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
This patch series officially adopts singular "they" as a contributor
guideline; see Patch 4 for the change to the guidelines and the reasoning
for the change. Before modifying the guidelines, documentation and comments
are updated to not use gendered pronouns, which provides examples of how to
use it.
I would appreciate ACKs in support on patch 4.
Thanks, -Stolee
Derrick Stolee (4):
Documentation: use singular they when appropriate
*: use singular they in comments
*: fix typos
CodingGuidelines: recommend singular they
Documentation/CodingGuidelines | 5 +++
Documentation/SubmittingPatches | 2 +-
Documentation/git-push.txt | 4 +-
.../using-signed-tag-in-pull-request.txt | 38 +++++++++----------
Documentation/user-manual.txt | 2 +-
commit.c | 2 +-
config.c | 2 +-
config.h | 2 +-
contrib/hooks/multimail/git_multimail.py | 4 +-
date.c | 2 +-
pathspec.h | 2 +-
strbuf.h | 2 +-
t/t9300-fast-import.sh | 2 +-
wt-status.c | 2 +-
14 files changed, 38 insertions(+), 33 deletions(-)
base-commit: c09b6306c6ca275ed9d0348a8c8014b2ff723cfb
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-975%2Fderrickstolee%2Fthey-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-975/derrickstolee/they-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/975
--
gitgitgadget
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-07 16:57:54
From: Derrick Stolee <redacted>
Several comments in our code refer to an anonymous user with "he/him" or
"she/her" pronouns, and the choice between the two is arbitrary.
Replace these uses with "they/them" which universally includes all
potential readers.
Signed-off-by: Derrick Stolee <redacted>
---
commit.c | 2 +-
config.h | 2 +-
contrib/hooks/multimail/git_multimail.py | 4 ++--
date.c | 2 +-
pathspec.h | 2 +-
strbuf.h | 2 +-
wt-status.c | 2 +-
7 files changed, 8 insertions(+), 8 deletions(-)
@@ -3219,7 +3219,7 @@ class GitoliteEnvironmentLowPrecMixin(defget_repo_shortname(self):# The gitolite environment variable $GL_REPO is a pretty good# repo_shortname (though it's probably not as good as a value-# the user might have explicitly put in his config).+# the user might have explicitly put in their config).return(self.osenv.get('GL_REPO',None)orsuper(GitoliteEnvironmentLowPrecMixin,self).get_repo_shortname()
@@ -3361,7 +3361,7 @@ def get_pusher(self):# __submitter into an RFC 2822 string already.returnre.match(r'(.*?)\s*<',self.__submitter).group(1)else:-# Submitter has no configured email, it's just his name.+# Submitter has no configured email, it's just their name.returnself.__submitterelse:# If we arrive here, this means someone pushed "Submit" from
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-07 16:58:09
From: Derrick Stolee <redacted>
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 <redacted>
---
Documentation/SubmittingPatches | 2 +-
Documentation/git-push.txt | 4 +-
.../using-signed-tag-in-pull-request.txt | 38 +++++++++----------
Documentation/user-manual.txt | 2 +-
4 files changed, 23 insertions(+), 23 deletions(-)
@@ -373,7 +373,7 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch+ reviewer and means that they are completely satisfied that the patch is ready for application. It is usually offered only after a detailed review. . `Tested-by:` is used to indicate that the person applied the patch
@@ -244,8 +244,8 @@ Imagine that you have to rebase what you have already published. You will have to bypass the "must fast-forward" rule in order to replace the history you originally published with the rebased history. If somebody else built on top of your original history while you are-rebasing, the tip of the branch at the remote may advance with her-commit, and blindly pushing with `--force` will lose her work.+rebasing, the tip of the branch at the remote may advance with their+commit, and blindly pushing with `--force` will lose their work. + This option allows you to say that you expect the history you are updating is what you rebased and want to replace. If the remote ref
@@ -1,8 +1,8 @@ From: Junio C Hamano <gitster@pobox.com> Date: Tue, 17 Jan 2011 13:00:00 -0800 Subject: Using signed tag in pull requests-Abstract: Beginning v1.7.9, a contributor can push a signed tag to her- publishing repository and ask her integrator to pull it. This assures the+Abstract: Beginning v1.7.9, a contributor can push a signed tag to their+ publishing repository and ask their integrator to pull it. This assures the integrator that the pulled history is authentic and allows others to later validate it. Content-type: text/asciidoc
@@ -11,9 +11,9 @@ How to use a signed tag in pull requests ======================================== A typical distributed workflow using Git is for a contributor to fork a-project, build on it, publish the result to her public repository, and ask-the "upstream" person (often the owner of the project where she forked-from) to pull from her public repository. Requesting such a "pull" is made+project, build on it, publish the result to their public repository, and ask+the "upstream" person (often the owner of the project where they forked+from) to pull from their public repository. Requesting such a "pull" is made easy by the `git request-pull` command. Earlier, a typical pull request may have started like this:
@@ -32,7 +32,7 @@ followed by a shortlog of the changes and a diffstat. The request was for a branch name (e.g. `for-xyzzy`) in the public repository of the contributor, and even though it stated where the-contributor forked her work from, the message did not say anything about+contributor forked their work from, the message did not say anything about the commit to expect at the tip of the for-xyzzy branch. If the site that hosts the public repository of the contributor cannot be fully trusted, it was unnecessarily hard to make sure what was pulled by the integrator was
@@ -57,7 +57,7 @@ integrator, using Git v1.7.9 or later. A contributor or a lieutenant ------------------------------After preparing her work to be pulled, the contributor uses `git tag -s`+After preparing their work to be pulled, the contributor uses `git tag -s` to create a signed tag: ------------
@@ -73,7 +73,7 @@ to justify why it is worthwhile for the integrator to pull it, as this message will eventually become part of the final history after the integrator responds to the pull request (as we will see later).-Then she pushes the tag out to her public repository:+Then they push the tag out to their public repository: ------------ $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
@@ -94,10 +94,10 @@ The contributor then prepares a message to request a "pull": The arguments are:-. the version of the integrator's commit the contributor based her work on;-. the URL of the repository, to which the contributor has pushed what she- wants to get pulled; and-. the name of the tag the contributor wants to get pulled (earlier, she could+. the version of the integrator's commit the contributor based their work on;+. the URL of the repository, to which the contributor has pushed what they+ want to get pulled; and+. the name of the tag the contributor wants to get pulled (earlier, they could write only a branch name here). The resulting msg.txt file begins like so:
@@ -130,7 +130,7 @@ command, the reader should notice that: The latter is why the contributor would want to justify why pulling her work is worthwhile when creating the signed tag. The contributor then-opens her favorite MUA, reads msg.txt, edits and sends it to her upstream+opens their favorite MUA, reads msg.txt, edits and sends it to their upstream integrator.
@@ -163,20 +163,20 @@ In the editor, the integrator will see something like this: Notice that the message recorded in the signed tag "Completed frotz feature" appears here, and again that is why it is important for the-contributor to explain her work well when creating the signed tag.+contributor to explain their work well when creating the signed tag. As usual, the lines commented with `#` are stripped out. The resulting commit records the signed tag used for this validation in a hidden field so that it can later be used by others to audit the history. There is no-need for the integrator to keep a separate copy of the tag in his+need for the integrator to keep a separate copy of the tag in their repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the-above example), and there is no need to publish the tag to his public+above example), and there is no need to publish the tag to their public repository, either.-After the integrator responds to the pull request and her work becomes+After the integrator responds to the pull request and their work becomes part of the permanent history, the contributor can remove the tag from-her public repository, if she chooses, in order to keep the tag namespace-of her public repository clean, with:+their public repository, if they choose, in order to keep the tag namespace+of their public repository clean, with: ------------ $ git push example.com:/git/froboz.git :frotz-for-xyzzy
@@ -2792,7 +2792,7 @@ A fast-forward looks something like this: In some cases it is possible that the new head will *not* actually be a descendant of the old head. For example, the developer may have-realized she made a serious mistake, and decided to backtrack,+realized they made a serious mistake, and decided to backtrack, resulting in a situation like: ................................................
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-07 16:59:05
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
[1] https://apastyle.apa.org/blog/singular-they
[2] https://style.mla.org/using-singular-they/
[3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
While not all styleguides are updating their recommendations, we can
make a choice as a project to adopt the concept because of the
efficiencies above, as well as the benefits of increased inclusion.
To futher justify singular "they" as an acceptable grammatical concept,
I include the careful research of brian m. carlson who collected their
thoughts on this matter [2] (lightly edited):
Singular "they" has been used by native English speakers as part of
the language for over half a millennium and is widely used and
understood. This usage is specified in Merriam Webster[3]:
The use of they, their, them, and themselves as pronouns of
indefinite gender and indefinite number is well established in
speech and writing, even in literary and formal contexts.
Wiktionary notes[4] (references omitted):
Usage of they as a singular pronoun began in the 1300s and has been
common ever since, despite attempts by some grammarians, beginning
in 1795, to condemn it as a violation of traditional (Latinate)
agreement rules. Some other grammarians have countered that criticism
since at least 1896. Fowler's Modern English Usage (third edition)
notes that it "is being left unaltered by copy editors" and is "not
widely felt to lie in a prohibited zone." Some authors compare use of
singular they to widespread use of singular you instead of thou.
Linguists fit roughly into two camps: prescriptive and descriptive.
The former specify rules for people to use, and the latter document
language as it is actually used without forming a judgment.
Some prescriptivists think it is acceptable, and some do not. But
descriptivists will rightly note that it is and has been commonly
used in English across countries, cultures, and contexts for an
extended period of time and is therefore generally accepted by most
English speakers as a normal part of the language. Since we are
writing text for an English language audience who are mostly not
linguists, we should probably consider using the language that most
people will use in this context.
[2] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
[3] https://www.merriam-webster.com/dictionary/they
[4] https://en.wiktionary.org/wiki/they
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>
---
Documentation/CodingGuidelines | 5 +++++
1 file changed, 5 insertions(+)
@@ -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.
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' 'commitrefs/heads/O1# -- ignore all of this textcommitter$GIT_COMMITTER_NAME<$GIT_COMMITTER_EMAIL>$GIT_COMMITTER_DATE-# $GIT_COMMITTER_NAME has inserted here for his benefit.+# $GIT_COMMITTER_NAME has inserted here for this benefit.data<<COMMITdirtydirectorycopyCOMMIT
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
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 <redacted>
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/7vehuyosaa.fsf@alter.siamese.dyndns.org/
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
Several comments in our code refer to an anonymous user with "he/him" or
"she/her" pronouns, and the choice between the two is arbitrary.
Replace these uses with "they/them" which universally includes all
potential readers.
Signed-off-by: Derrick Stolee <redacted>
---
commit.c | 2 +-
config.h | 2 +-
contrib/hooks/multimail/git_multimail.py | 4 ++--
On 6/7/2021 1:12 PM, Ævar Arnfjörð Bjarmason wrote:
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
Several comments in our code refer to an anonymous user with "he/him" or
"she/her" pronouns, and the choice between the two is arbitrary.
Replace these uses with "they/them" which universally includes all
potential readers.
Signed-off-by: Derrick Stolee <redacted>
---
commit.c | 2 +-
config.h | 2 +-
contrib/hooks/multimail/git_multimail.py | 4 ++--
On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
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 <redacted>
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/7vehuyosaa.fsf@alter.siamese.dyndns.org/
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
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.
For now, I'll remove these edits from the patch.
Thanks,
-Stolee
From: Andrei Rybak <hidden> Date: 2021-06-07 17:43:22
On 07/06/2021 19:32, Derrick Stolee wrote:
On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
quoted
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
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 <redacted>
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/7vehuyosaa.fsf@alter.siamese.dyndns.org/
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
As long as this file remains formatted as an archived email message,
the edits here are inappropriate.
To be fair, this file has already been copyedited once in commit
2de9b71138 (Documentation: the name of the system is 'Git', not 'git',
2013-01-21)
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.
For now, I'll remove these edits from the patch.
On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
quoted
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
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 <redacted>
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/7vehuyosaa.fsf@alter.siamese.dyndns.org/
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
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"...
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
[...]
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
Somewhat humorous & somewhat serious aside: Maybe it's just me, but when
I read "incredibly efficient" I was thinking more of an energy drink
filled with with nanites that would directly update my brain with the
documentation, not the minutia of how we go about wording things :)
Continuing; Snipping around a bit in your E-Mail (a sentence copied from
"[...]" above:
If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information. [...]
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
I'd expect most people to not actively read technical documentation and
try to personally actively ascribe themselves to prose that clearly
forms an example of something they may or may not do.
If that is how people commonly read documentation and find it
off-putting I'd expect gendered language to be the least of our
problems, since even with s/\bhe|she\b/they/g so much of what's left is
still referring to hypothetical situations most users won't want to find
themselves in.
Maybe I'm overthinking this, but per the above I'd think if this is a
problem with losing the reader that we'd need more structural solutions
to it in the common case, e.g. more guarded language that you should not
read further if you don't care about XYZ aspect of the technical feature
we're about to discuss.
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
[1] https://apastyle.apa.org/blog/singular-they
[2] https://style.mla.org/using-singular-they/
[3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
While not all styleguides are updating their recommendations, we can
make a choice as a project to adopt the concept because of the
efficiencies above, as well as the benefits of increased inclusion.
To futher justify singular "they" as an acceptable grammatical concept,
I include the careful research of brian m. carlson who collected their
thoughts on this matter [2] (lightly edited):
It seems strange to attempt to summarize the previous discussion in the
cover letter and here thoroughly, and make not even a passing mention of
the counter-argument I presented to it in [1]; which resulted in most of
the replies to that thread, and which the maintainer you're trying to
get to apply this patch seemed to agree with. More on that at the end.
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".
Sure.
* References to fictional people with clear genders (e.g. Alice and
Bob).
I don't think using the Alice & Bob examples is necessarily a problem,
but while we're discussing writing inclusive technical docs I think
their use is probably a bigger problem than the pronoun issue you're
presenting here.
That's because often using those characters is an overly clever
reference to their use in crypto circles, and thus the developer often
ends up writing documentation that simply assumes that the fact that
"Eve" is the "Eavesdropper" is obvious to the reader.
Whenever I read documentation like that I end up Googling it and end up
at the "Cast of Characters" section in the relevant Wikipedia page, just
to see if I'm missing something. It doesn't make for accessible
documentation.
I think the use in Documentation/gittutorial.txt that you didn't end up
changing is a good example of something that would be better rewritten
as "you" and then referring to "bob" as some generic remote repository
instead, I haven't seen an overly clever example of Alice/Bob/Eve
etc. in git.git's docs, but maybe it's there somewhere.
* Sample text used in test cases (e.g t3702, t6432).
It seems strange to exclude arbitrary uses of passages from Beowulf and
quoting of Plato in diff/merge tests from a commit that's otherwise
arguing that arbitrary uses of "he" or "she" is going to lose the reader.
After all we do have a need to refer to the hypothetical user in some
manner in the prose of our documentation, but those tests will pass if
we rot13 the gendered-pronoun-using relevant text, or otherwise replaced
all the input with gibberish following similar whitespace rules.
@@ -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". [...]
I do think most of the changes in patches 1-3 were an obvious
improvement and that we could really do with some general extension of
preferred prose in the "Writing Documentation" section you're
modifying.
I think advice about that should really start more generically, this
seems like losing the forest for the trees. E.g. do we write things
like:
--force: You can use this to force the command to do XYZ
Or:
--force: Skip sanity checks, do XYZ
I'd like to think that we'd mostly prefer the latter, and that also
nicely sidesteps the issue you're tackling here.
I think any such advice would be better off by stating that our usual
preference is to describe things in the abstract, continuing to
preferring to assume that we're talking directly at the user:
You can use use --force to disable the safety.
As opposed to needlessly introducing more verbose and possibly gendered
prose:
Should the user wish to disable the safety features, they can use
the --force option.
This patch hunk also seems like it would be better worked into the first
3-4 paragraphs of "Writing Documentation" somehow, rather than tacking
it at the end. That's where we've started to discuss US v.s. UK English,
following existing conventions etc.
[...] Do not use more complicated constructs such as "he or she" or
"s/he".[...]
I note that one thing you didn't tackle at all in [1] & downthread is
the problem we have that's really not present in the style manuals
you're referring to.
That is, once we've done with avoiding verbosity per the above &
preferring "you" over anything else we're usually left referring to a
generic concept of an OS user.
Such a thing does not have any gender, and need not be tied to any
particular life form. It's usually something authors of manuals of style
don't need to consider outside of sci-fi novels.
I think we'd do well to prefer imitating how e.g. C library docs usually
deal with that over any MOS, which is to just say something like "a user
with permission xyz can...." or whatever. It's just weird to think of
say a git command run by my sshd or www-data user as a "they", just as I
wouldn't use "he" or "she".
[...] This recommendation also applies to code comments and commit
messages.
Since you were seeking ACKs in the CL this is overall a NACK from
me. For reasons noted in the thread starting at [1] so I won't repeat
most of that here; but briefly: I do think extending this to commit
messages in particular is over-reaching.
Our installed documentation is one thing, but commit messages are much
closer to the prose people are personally comfortable with, every hurdle
we put to accepting patches, particularly ones that seem arbitrary and
without good technical reasons are also something that harms inclusion &
project velocity.
This whole thing also started in reply to one patch submitted by Lénaïc
Huard (a non-native speaker of English), which he promptly re-rolled
after this whole pronoun thread started. Grepping around with:
git log --grep='\b(he|she)\b' -i origin/master
And mentally grepping out changes referring to specific people (just
generic examples), I see one change in 2021, then you've got to go back
to 2017 to find the next one (I just skimmed this, maybe I missed some),
you very quickly get to 2014.
I think I'd feel even stronger that we didn't need this in transitory
commit message examples even if it were more common, per the argument in
[1].
But given how rare it is anyway seeking to enforce a policy on commit
messages just seems like an over-reaction to a specific recent
contribution.
In summary: My "NACK" is mostly on the "and commit messages". Just
because *generally* we should be less nitpicky about personal preferred
prose there, I'd feel the same way about insisting on US English only or
whatever. We should be forgiving in what we accept there.
Installed docs are another matter entirely, I'm very much in favor of
having some extensions to the existing style guide there. I do think as
argued above we should start more generically, and it's not just
bikeshedding. As argued above I think we should mostly be recommending
different prose entirely, as apposed to now actively recommending "they"
(which if you discuss e.g. "a user" mostly won't be needed).
1. https://lore.kernel.org/git/87wnrooa17.fsf@evledraar.gmail.com/
From: Felipe Contreras <hidden> Date: 2021-06-07 20:00:32
Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
We can solve that easily by using 50% he, and 50% she (I presume you are
in the equality of outcome camp in the culture war).
By using an invented pronoun we introduce more friction, especially with
the people that just learned English, and just familiarized themselves
with the standard English pronouns.
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
I do not consider the singular pronoun "they" to apply to me. I presume
others are on the same boat.
Do I not count? If so, why?
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
But it's not part of standard English language.
Of all the turf wars that have complicated the landscape of grammar
over the past few hundred years, the most complicated and frustrating
may be that of the singular they.
It may be the most controversial word use in the English
language—because it highlights a hole where a better-fitting word
should go.
It creates a conflict between writers and editors who want things to
follow the natural symmetry of Latin, and people who find they the
only logical option for referring to a single person without a gender
attached.
And there has been a lot written about it—it’s something of a hot
topic this year, thanks to a vote by the American Dialect Society to
name they its word of the year for 2015.
Alas, this problem isn’t as easy to solve as a vote from a dialect
society. The problem is something of an emotional one—and it’s sparked
debate for centuries.
Really, if this problem is ever to go away, it’s going to be up to
professional copy editors to speak up. And at least some of them
appear to have made peace with the change.
https://www.atlasobscura.com/articles/the-linguistic-turf-wars-over-the-singular-they
This is a problem for linguists, copy editors, and society in general.
Not a software project.
By introducing rules that presume an outcome fiercly debated *at this
very moment* you are introducing more friction.
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
This is a problem of the English language, not Git's documentation.
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
This would be a killer argument if language was prescriptive, but it's
not. At least half of linguists (probably way more) are on the
descriptivist side.
Most writers ignore style guides and write in the way they see others
write. Not how anyone prescribes.
While not all styleguides are updating their recommendations, we can
make a choice as a project to adopt the concept because of the
efficiencies above, as well as the benefits of increased inclusion.
To futher justify singular "they" as an acceptable grammatical concept,
I include the careful research of brian m. carlson who collected their
thoughts on this matter [2] (lightly edited):
Singular "they" has been used by native English speakers as part of
the language for over half a millennium and is widely used and
understood. This usage is specified in Merriam Webster[3]:
Again, I already responded to this argument:
A similar thing happens with the word "nucular" [2]; it is used by
native English speakers as part of the language for many decades and is
widely used and understood.
Does that mean it's a valid word? Maybe.
But does that make "nuclear" invalid? No.
You can use "nucular" if you want (many people do). I will use
"nuclear".
Both can be valid, and we shouldn't demand the use of one over the
other.
Linguists fit roughly into two camps: prescriptive and descriptive.
The former specify rules for people to use, and the latter document
language as it is actually used without forming a judgment.
Some prescriptivists think it is acceptable, and some do not. But
descriptivists will rightly note that it is and has been commonly
used in English across countries, cultures, and contexts for an
extended period of time and is therefore generally accepted by most
English speakers as a normal part of the language. Since we are
writing text for an English language audience who are mostly not
linguists, we should probably consider using the language that most
people will use in this context.
This is an argument against your proposal:
1. It dismantles the need to heed style guides
2. If it was true, we would already see wideslread use of the singular
"they" in the documentation (and we don't)
3. If we follow the descriptivist approach, the we should let the
writers of the documentation follow what they think is best, not
*prescrive* what prononoun they shall use
And even if this was an argument in favor of "they", you still need to
provide an argument against "she", or "he.
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.
The fact that singular "they" is less awkward to write and read seemed
obvious to me, so I did not back up my statement with any references or
reasons. The ensuing discussion did include reasons, especially brian m.
carlson's thoughtful message [2].
[2] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
This patch series officially adopts singular "they" as a contributor
guideline; see Patch 4 for the change to the guidelines and the reasoning
for the change. Before modifying the guidelines, documentation and comments
are updated to not use gendered pronouns, which provides examples of how to
use it.
You use a descriptivist argument (language evolves naturally), to claim
that singular "they" is already used, but then use that to *prescriptive*
rules, which is the opposite. You are contradicting yourself.
Either we follow descriptivists and let the writers decide what's
appropriate, or we follow prescriptivists and establish rules
prescriptivist linguists agree on. Prescriptivists are on the side that
singular "they" should not be used (because of Latin adherence).
You can't have both.
From: Robert Karszniewicz <hidden> Date: 2021-06-07 20:20:16
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
That is funny, because I experience cognitive dissonance exactly when
people use singular plural-pronouns. ("What? Did I read right? Is it a
group? Or a company?" [seek back to verify, or explicitly ignore the
hiccup])
On the other hand I strongly doubt that such a cognitive dissonance
happens when people come across a wrong gender. When documentation
speaks of "the user" -- *any* user -- then it does not in any way
conflict that that "any user" might be female.
And I'm not just theorizing, as I /did/ have the following experience
(anecdote):
One time I was presented a document which I was supposed to read and
sign. I read through the whole document all fine and only at the very
end I noticed that the whole document is consistently written in the
female form (and that was in German, there is no distinct neutral
"the"). I made a joke about it asking where the document version for
males is, to which he responded: "Now you know how it feels being
female". Which -- and I want to stress this -- I found deeply insulting.
"He or she" is problematic in its own way, but you already propose
against it.
As one of the users whose happiness is being discussed here, I can only
ask not to change from singular to plural pronouns. If you must, pick
"she", I don't mind. Or "it", or "person", whatever, as long as it
matches the cardinality of "the user".
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
The 'singular "they"' does not apply to every reader and might not even
apply to most readers. It might be natural for native speakers to know
that "they" is "1 or more people", but that is not what foreigners are
taught what "they" means. In my entire curriculum at school I have not
once been taught that "they" can mean "one person". Therefore, whenever
I see it used that way, I cannot help but stumble. Every time.
Not to mention that the documentation does not talk about "the reader"
but "the user". Yes, had the documentation talked about me specifically,
the reader, and I suddenly had to assume another gender, I might ask
myself what's going on. But it never crossed my mind to assume the
identity of an unspecified, indeterminate "the user".
Thank you,
Robert Karszniewicz
@@ -373,7 +373,7 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch+ reviewer and means that they are completely satisfied that the patch
This sounds completely alien to me.
Granted, I'm not a native English speaker, but aren't you supposed to be
trying to be inclusive?
It took me a considerable amount of time to train my mind to think in
English, and now I don't have to think in Spanish, but "he" is "él",
"she" is "ella", and "they" is "ellos", or "ellas". And that has been
more than enough to read 99.9% of documents I encounter without
problems.
And now you come out of the blue with a pronoun that doesn't match any
of my mental models.
There's many Spanish speakers out there, but this probably extends to
Italians, French, and all the other Latin-based languages.
But to be honest I read a lot of English, and I virtually never
encounter this usage. And at least 58% of the Usage Panel of The
American Heritage Dictionary [1] agrees with me.
I have read Steven Pinker's (a renowned linguist) style manual: The
Sense of Style. He specifically mentions singular "they", and he
explains the cases where it makes sense, and where it doesn't.
It is not so straight-forward, and to show why, here's an example:
A contemporary example with an unambiguous female referent comes from
a spoken interview with Sean Ono Lennon in which he specified the kind
of person he was seeking as a romantic partner: “Any girl who is
interested must simply be born female and between the ages of 18 and
45. They must have an IQ above 130 and they must be honest.”
In this case "they" is grammatically singular, yes, but it is
*psychologically* plural, since the person is picked from a pool.
I don't know how a native speaker parses this "they", but as a Spanish
speaker I cannot leave it unspecified. "They must" translates to
"deben", which is plural, if it was singular it would be "debe", which
in English would be "she must".
I have read many instances where English speakers argue it's a singular
"they" but to me it's not. According to Steven Pinker it's because it's
psychologically plural.
Pinker uses singular "they" very occasionally, and only with
semantically plural antecedents, the rest of the times he alternates
between he and she freely. And I try to do so as well.
This is his conclusion in his style manual:
Because of these complexities, writers always have to consider the
full inventory of devices that the English language makes available to
convey generic information, each imperfect for a different reason: he,
she, he or she, they, a plural antecedent, replacing the pronoun, and
who knows, perhaps someday even using thon.
For some purists, these complexities provide an excuse to dismiss all
concerns with gender inclusiveness and stick with the flawed option of
he. Gelernter complains, “Why should I worry about feminist ideology
while I write? . . . Writing is a tricky business that requires one’s
whole concentration.” But the reaction is disingenuous. Every sentence
requires a writer to grapple with tradeoffs between clarity,
concision, tone, cadence, accuracy, and other values. Why should the
value of not excluding women be the only one whose weight is set to
zero?
He does however, provide tips to avoid some hurdles, one is to express
quantified descriptions as plural, so we would have:
`Reviewed-by:`, unlike the other tags, can only be offered by the
reviewers and means that they are completely satisfied that the patch
is ready for application. It is usually offered only after a
detailed review.
That reads perfectly fine to me.
@@ -244,8 +244,8 @@ Imagine that you have to rebase what you have already published. You will have to bypass the "must fast-forward" rule in order to replace the history you originally published with the rebased history. If somebody else built on top of your original history while you are-rebasing, the tip of the branch at the remote may advance with her-commit, and blindly pushing with `--force` will lose her work.+rebasing, the tip of the branch at the remote may advance with their+commit, and blindly pushing with `--force` will lose their work.
This one does read correctly to me, and is in fact better than "she".
And it is because "somebody" is semantically plural: he or she comes
from a pool of people.
As stated above, writing is a tricky business, you can't just
s/s?he/they/.
Not even renowned linguists dare to prescribe point-blank rules like you
are trying to do.
This is part of Usage Note on "singular they" from The American
Heritage Dictionary:
Resistance remains strongest when the sentence refers to a specific
individual whose gender is unknown, rather than to a generic
individual representative of anyone: in our 2015 survey, 58 percent of
the Panel found We thank the anonymous reviewer for their helpful
comments unacceptable. A sentence with a generic antecedent, A person
at that level should not have to keep track of the hours they put in,
was rejected by 48 percent (a substantial change from our 1996 survey,
in which 80 percent rejected this same sentence). As for the use of
they with antecedents such as anyone and everyone, pronouns that are
grammatically singular but carry a plural meaning, by 2008, a majority
of the Panel accepted such sentences as If anyone calls, tell them I
can’t come to the phone (56 percent) and Everyone returned to their
seats (59 percent).
I do not think the Git project should jump into these muddy waters.
Cheers.
[1] https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-07 22:19:11
Robert Karszniewicz wrote:
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
That is funny, because I experience cognitive dissonance exactly when
people use singular plural-pronouns. ("What? Did I read right? Is it a
group? Or a company?" [seek back to verify, or explicitly ignore the
hiccup])
Same here.
On the other hand I strongly doubt that such a cognitive dissonance
happens when people come across a wrong gender. When documentation
speaks of "the user" -- *any* user -- then it does not in any way
conflict that that "any user" might be female.
Same here. If it is stated that a female reviewer shall do X, I don't see
for the life of me why it wouldn't apply to me too.
quoted
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
The 'singular "they"' does not apply to every reader and might not even
apply to most readers. It might be natural for native speakers to know
that "they" is "1 or more people", but that is not what foreigners are
taught what "they" means.
That's not even true for native speakers either.
There's a difference between singular "they" with semantically plural
antecedents, and semantically singular antecedents.
For example:
Everyone returned to their seats
I don't see any problem with that sentence, and it's singular "they"
(with semantically plural antecedents).
When linguists say singular "they" has been used four centuries, they
refer to the usage above.
But with semantically singular antecedents it's different:
We thank the reviewer for their comments
Many native speaker linguist experts see a problem with that sentence
(and so do I).
Cheers.
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-08 01:48:41
Ævar Arnfjörð Bjarmason wrote:
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
quoted
If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information. [...]
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
I'd expect most people to not actively read technical documentation and
try to personally actively ascribe themselves to prose that clearly
forms an example of something they may or may not do.
If that is how people commonly read documentation and find it
off-putting I'd expect gendered language to be the least of our
problems, since even with s/\bhe|she\b/they/g so much of what's left is
still referring to hypothetical situations most users won't want to find
themselves in.
Maybe I'm overthinking this, but per the above I'd think if this is a
problem with losing the reader that we'd need more structural solutions
to it in the common case, e.g. more guarded language that you should not
read further if you don't care about XYZ aspect of the technical feature
we're about to discuss.
Personally I have no trouble at all reading instructions mentioning a
female user and see how they apply to me just the same.
Using a singular "they" for semantically singular antecedents does sound
totally broken to me, and that does distract me from what the
documentation is supposedly trying to transmit.
I have trouble parsing the documentation as it is--which does feel to be
in a very detached and unpersonal style. Changes like s/s?he/they/ only
make the situation worse. I would rather have the documentation speak to
me more like a person, and less like a previous-generation AI.
Cheers.
--
Felipe Contreras
From: Jeff King <hidden> Date: 2021-06-08 07:10:38
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
In general, I do like the efficiency and readability of singular "they".
As a native speaker, I have no problem reading it, and I have little
sense that most of my native-speaker acquaintances would, either.
I _do_ worry that it would be jarring or difficult to read for
non-native speakers (or perhaps native speakers who aren't in my circle
of acquaintances). There have been a few comments to that effect on the
list, but it's hard to consider that data and not anecdotes.
One thing that gives me some comfort is your research here:
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
[1] https://apastyle.apa.org/blog/singular-they
[2] https://style.mla.org/using-singular-they/
[3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
I don't know to what degree those style guidelines take into account
non-native speakers. But they at least provide a sense that this style
is in wide-ish use. And probably growing use, as well, considering that
they have changed recently. So even if it may be surprising to some
readers at first, I hope it may become less so as time goes on and
projects (like ours) make it more commonplace.
(You could perhaps argue the same "it may become less surprising over
time" for something like "xe", but that one does not seem to be in
particularly wide or growing use, from my experience).
So I think this is a reasonable style suggestion to put in our
guidelines.
-Peff
From: Felipe Contreras <hidden> Date: 2021-06-08 08:11:37
Jeff King wrote:
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
In general, I do like the efficiency and readability of singular "they".
As a native speaker, I have no problem reading it, and I have little
sense that most of my native-speaker acquaintances would, either.
Does this sound correct to you?
We thank the reviewer for their helpful comments
One thing that gives me some comfort is your research here:
On Mon, Jun 07, 2021 at 04:57:45PM +0000, Derrick Stolee via GitGitGadget wrote:
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.
(I am not disagreeing with the series.)
There is value in intentionally defaulting to "she/her", especially in
settings where women are underrepresented. It can be a nice way to
shake the foundations of unconscious bias in the reader's head. See
https://www.askamanager.org/2011/07/why-i-refer-to-everyone-as-she.html
as an example.
Replace these uses with "they/them" to ensure that these documentation
examples apply to all potential users without exception.
However, in this case, I think "they/them" is appropriate as a default.
As you say, this documentation is intended as a guide to potential users
and contributors, and should apply to them. Thanks for writing the
change.
Reviewed-by: Emily Shaffer <redacted>
On Mon, Jun 07, 2021 at 04:57:46PM +0000, Derrick Stolee via GitGitGadget wrote:
Several comments in our code refer to an anonymous user with "he/him" or
"she/her" pronouns, and the choice between the two is arbitrary.
Replace these uses with "they/them" which universally includes all
potential readers.
Thanks. I'm especially glad to see the codebase start to unify instead
of awkwardly choosing between "he", "she", "he or she", or even "(s)he".
This seems a lot neater.
Reviewed-by: Emily Shaffer <redacted>
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
[1] https://apastyle.apa.org/blog/singular-they
[2] https://style.mla.org/using-singular-they/
[3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
While not all styleguides are updating their recommendations, we can
make a choice as a project to adopt the concept because of the
efficiencies above, as well as the benefits of increased inclusion.
To futher justify singular "they" as an acceptable grammatical concept,
I include the careful research of brian m. carlson who collected their
thoughts on this matter [2] (lightly edited):
Singular "they" has been used by native English speakers as part of
the language for over half a millennium and is widely used and
understood. This usage is specified in Merriam Webster[3]:
The use of they, their, them, and themselves as pronouns of
indefinite gender and indefinite number is well established in
speech and writing, even in literary and formal contexts.
Wiktionary notes[4] (references omitted):
Usage of they as a singular pronoun began in the 1300s and has been
common ever since, despite attempts by some grammarians, beginning
in 1795, to condemn it as a violation of traditional (Latinate)
agreement rules. Some other grammarians have countered that criticism
since at least 1896. Fowler's Modern English Usage (third edition)
notes that it "is being left unaltered by copy editors" and is "not
widely felt to lie in a prohibited zone." Some authors compare use of
singular they to widespread use of singular you instead of thou.
Linguists fit roughly into two camps: prescriptive and descriptive.
The former specify rules for people to use, and the latter document
language as it is actually used without forming a judgment.
Some prescriptivists think it is acceptable, and some do not. But
descriptivists will rightly note that it is and has been commonly
used in English across countries, cultures, and contexts for an
extended period of time and is therefore generally accepted by most
English speakers as a normal part of the language. Since we are
writing text for an English language audience who are mostly not
linguists, we should probably consider using the language that most
people will use in this context.
[2] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
[3] https://www.merriam-webster.com/dictionary/they
[4] https://en.wiktionary.org/wiki/they
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>
@@ -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.
From: Felipe Contreras <hidden> Date: 2021-06-08 18:03:51
Emily Shaffer wrote:
On Mon, Jun 07, 2021 at 04:57:45PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
Replace these uses with "they/them" to ensure that these documentation
examples apply to all potential users without exception.
However, in this case, I think "they/them" is appropriate as a default.
As you say, this documentation is intended as a guide to potential users
and contributors, and should apply to them. Thanks for writing the
change.
What do you prefer?
A. We thank the reviewer for their helpful comments
B. We thank the reviewer for her helpful comments
--
Felipe Contreras
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
In general, I do like the efficiency and readability of singular "they".
As a native speaker, I have no problem reading it, and I have little
sense that most of my native-speaker acquaintances would, either.
Does this sound correct to you?
We thank the reviewer for their helpful comments
In the case of an anonymous reviewer (such as a single-blind review of
an academic paper), then this is exactly how one should acknowledge a
single reviewer.
If we know the identity of the reviewer, then we should use their
preferred pronouns to the best of our ability.
Thanks,
-Stolee
From: Kerry, Richard <hidden> Date: 2021-06-09 13:44:18
What do you prefer?
A. We thank the reviewer for their helpful comments
B. We thank the reviewer for her helpful comments
[RK] If this is, as it appears to be, a reference to a specific reviewer, then use their preferred pronoun, or possibly a conventional singular one if you know their name and they haven't specified a preference.
[RK] Only if they aren't known, and especially if they are one from a pool, then "their".
[RK] Or make them plural - We thank the reviewers for their helpful comments.
[RK] Or rephrase to sidestep the issue (though it isn't clear to me here what that option would be)
Regards,
Richard.
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-09 13:54:45
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time. Singular
"they" applies to every reader.
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
[1] https://apastyle.apa.org/blog/singular-they
[2] https://style.mla.org/using-singular-they/
[3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
While not all styleguides are updating their recommendations, we can
make a choice as a project to adopt the concept because of the
efficiencies above, as well as the benefits of increased inclusion.
To futher justify singular "they" as an acceptable grammatical concept,
I include the careful research of brian m. carlson who collected their
thoughts on this matter [4] (lightly edited):
Singular "they" has been used by native English speakers as part of
the language for over half a millennium and is widely used and
understood. This usage is specified in Merriam Webster[5]:
The use of they, their, them, and themselves as pronouns of
indefinite gender and indefinite number is well established in
speech and writing, even in literary and formal contexts.
Wiktionary notes[6] (references omitted):
Usage of they as a singular pronoun began in the 1300s and has been
common ever since, despite attempts by some grammarians, beginning
in 1795, to condemn it as a violation of traditional (Latinate)
agreement rules. Some other grammarians have countered that criticism
since at least 1896. Fowler's Modern English Usage (third edition)
notes that it "is being left unaltered by copy editors" and is "not
widely felt to lie in a prohibited zone." Some authors compare use of
singular they to widespread use of singular you instead of thou.
Linguists fit roughly into two camps: prescriptive and descriptive.
The former specify rules for people to use, and the latter document
language as it is actually used without forming a judgment.
Some prescriptivists think it is acceptable, and some do not. But
descriptivists will rightly note that it is and has been commonly
used in English across countries, cultures, and contexts for an
extended period of time and is therefore generally accepted by most
English speakers as a normal part of the language. Since we are
writing text for an English language audience who are mostly not
linguists, we should probably consider using the language that most
people will use in this context.
[4] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
[5] https://www.merriam-webster.com/dictionary/they
[6] https://en.wiktionary.org/wiki/they
Since singular "they" might be unfamiliar to some, we also list an
option to rephrase writing to use singular "you" or plural "they". We
can use singular "you" to refer to the reader instead of an abstract
user. Plural "they" works if we refer to multiple abstract users instead
of one. The English language does not have gendered versions of these
terms.
If we refer to a specific person, then using a gendered pronoun is
appropriate. There can also be other cases where it is inappropriate for
us to update the existing examples within the Git codebase, such as:
* 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.
* Literal email messages in Documentation/howto/ should not be edited
for grammatical concerns such as this, unless we update the entire
document to fit the standard documentation format. If such an effort is
taken on, then the authorship would change and no longer refer to the
exact mail message.
* External projects consumed in contrib/ should not deviate solely for
style reasons. Recommended edits should be contributed to those
projects directly.
Other cases within the Git project were cleaned up by the previous
changes.
Helped-by: Junio C Hamano [off-list ref]
Signed-off-by: Derrick Stolee <redacted>
---
Documentation/CodingGuidelines | 7 +++++++
1 file changed, 7 insertions(+)
@@ -648,3 +648,10 @@ 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.++ Refer to an anonymous user in a gender neutral way. Singular "they/them"+ pronouns are preferred over "he/him" and "she/her". Do not use more+ complicated constructs such as "he or she" or "s/he". When in doubt about+ how to use this pronoun, then change your sentence to use singular "you"+ (e.g. "When you want to do X, do Y") or plural "they" (e.g. "When users+ want to do X, they can do Y.").
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' 'commitrefs/heads/O1# -- ignore all of this textcommitter$GIT_COMMITTER_NAME<$GIT_COMMITTER_EMAIL>$GIT_COMMITTER_DATE-# $GIT_COMMITTER_NAME has inserted here for his benefit.+# $GIT_COMMITTER_NAME has inserted here for this benefit.data<<COMMITdirtydirectorycopyCOMMIT
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-09 13:55:00
From: Derrick Stolee <redacted>
Several comments in our code refer to an anonymous user with "he/him" or
"she/her" pronouns, and the choice between the two is arbitrary.
Replace these uses with "they/them" which universally includes all
potential readers.
Helped-by: Felipe Contreras [off-list ref]
Signed-off-by: Derrick Stolee <redacted>
---
commit.c | 2 +-
config.h | 2 +-
date.c | 2 +-
pathspec.h | 2 +-
strbuf.h | 2 +-
wt-status.c | 2 +-
6 files changed, 6 insertions(+), 6 deletions(-)
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-09 13:55:44
In another topic, I claimed [1] that singular "they" was better than
"he/she" for gender neutrality.
[1]
https://lore.kernel.org/git/44d937a0-e876-e185-f409-a4fd61eae580@gmail.com/
The fact that singular "they" is less awkward to write and read seemed
obvious to me, so I did not back up my statement with any references or
reasons. The ensuing discussion did include reasons, especially brian m.
carlson's thoughtful message [2].
[2] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
This patch series officially adopts singular "they" as a contributor
guideline; see Patch 4 for the change to the guidelines and the reasoning
for the change. Before modifying the guidelines, documentation and comments
are updated to not use gendered pronouns, which provides examples of how to
use it.
I would appreciate ACKs in support on patch 4.
Updates in v2
=============
* Some edits were removed because they were in contrib/ or
Documentation/howto/ and these are now listed as exclusions in the
message of Patch 4.
* Several recommendations to improve the edits in the documentation and
code comments were incorporated. Those who recommended these edits are
credited with "Helped-by" tags.
* The URLs in Patch 4 had overlapping citation numbers. This is fixed.
Thanks, -Stolee
Derrick Stolee (4):
Documentation: use singular they when appropriate
*: use singular they in comments
*: fix typos
CodingGuidelines: recommend singular they
Documentation/CodingGuidelines | 7 +++++++
Documentation/SubmittingPatches | 8 ++++----
Documentation/git-push.txt | 4 ++--
Documentation/user-manual.txt | 2 +-
commit.c | 2 +-
config.c | 2 +-
config.h | 2 +-
date.c | 2 +-
pathspec.h | 2 +-
strbuf.h | 2 +-
t/t9300-fast-import.sh | 2 +-
wt-status.c | 2 +-
12 files changed, 22 insertions(+), 15 deletions(-)
base-commit: c09b6306c6ca275ed9d0348a8c8014b2ff723cfb
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-975%2Fderrickstolee%2Fthey-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-975/derrickstolee/they-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/975
Range-diff vs v1:
1: afc51c5e6ede ! 1: fb7a7573782a Documentation: use singular they when appropriate
@@ Commit message
Replace these uses with "they/them" to ensure that these documentation
examples apply to all potential users without exception.
+ Helped-by: Richard Kerry [off-list ref]
+ Helped-by: Junio C Hamano [off-list ref]
Signed-off-by: Derrick Stolee [off-list ref]
## Documentation/SubmittingPatches ##
@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:
+ the patch attempts to fix.
. `Acked-by:` says that the person who is more familiar with the area
the patch attempts to modify liked the patch.
- . `Reviewed-by:`, unlike the other tags, can only be offered by the
+-. `Reviewed-by:`, unlike the other tags, can only be offered by the
- reviewer and means that she is completely satisfied that the patch
-+ reviewer and means that they are completely satisfied that the patch
- is ready for application. It is usually offered only after a
- detailed review.
+- is ready for application. It is usually offered only after a
+- detailed review.
++. `Reviewed-by:`, unlike the other tags, can only be offered by a
++ reviewer when they are completely satisfied with the patch. It is
++ offered only after reviews by reviewers who are known to be experts
++ in the affected area by the community members.
. `Tested-by:` is used to indicate that the person applied the patch
+ and found it to have the desired effect.
+
## Documentation/git-push.txt ##
@@ Documentation/git-push.txt: Imagine that you have to rebase what you have already published.
@@ Documentation/git-push.txt: Imagine that you have to rebase what you have alread
This option allows you to say that you expect the history you are
updating is what you rebased and want to replace. If the remote ref
- ## Documentation/howto/using-signed-tag-in-pull-request.txt ##
-@@
- From: Junio C Hamano [off-list ref]
- Date: Tue, 17 Jan 2011 13:00:00 -0800
- Subject: Using signed tag in pull requests
--Abstract: Beginning v1.7.9, a contributor can push a signed tag to her
-- publishing repository and ask her integrator to pull it. This assures the
-+Abstract: Beginning v1.7.9, a contributor can push a signed tag to their
-+ publishing repository and ask their integrator to pull it. This assures the
- integrator that the pulled history is authentic and allows others to
- later validate it.
- Content-type: text/asciidoc
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: How to use a signed tag in pull requests
- ========================================
-
- A typical distributed workflow using Git is for a contributor to fork a
--project, build on it, publish the result to her public repository, and ask
--the "upstream" person (often the owner of the project where she forked
--from) to pull from her public repository. Requesting such a "pull" is made
-+project, build on it, publish the result to their public repository, and ask
-+the "upstream" person (often the owner of the project where they forked
-+from) to pull from their public repository. Requesting such a "pull" is made
- easy by the `git request-pull` command.
-
- Earlier, a typical pull request may have started like this:
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: followed by a shortlog of the changes and a diffstat.
-
- The request was for a branch name (e.g. `for-xyzzy`) in the public
- repository of the contributor, and even though it stated where the
--contributor forked her work from, the message did not say anything about
-+contributor forked their work from, the message did not say anything about
- the commit to expect at the tip of the for-xyzzy branch. If the site that
- hosts the public repository of the contributor cannot be fully trusted, it
- was unnecessarily hard to make sure what was pulled by the integrator was
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: integrator, using Git v1.7.9 or later.
- A contributor or a lieutenant
- -----------------------------
-
--After preparing her work to be pulled, the contributor uses `git tag -s`
-+After preparing their work to be pulled, the contributor uses `git tag -s`
- to create a signed tag:
-
- ------------
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: to justify why it is worthwhile for the integrator to pull it, as this
- message will eventually become part of the final history after the
- integrator responds to the pull request (as we will see later).
-
--Then she pushes the tag out to her public repository:
-+Then they push the tag out to their public repository:
-
- ------------
- $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: The contributor then prepares a message to request a "pull":
-
- The arguments are:
-
--. the version of the integrator's commit the contributor based her work on;
--. the URL of the repository, to which the contributor has pushed what she
-- wants to get pulled; and
--. the name of the tag the contributor wants to get pulled (earlier, she could
-+. the version of the integrator's commit the contributor based their work on;
-+. the URL of the repository, to which the contributor has pushed what they
-+ want to get pulled; and
-+. the name of the tag the contributor wants to get pulled (earlier, they could
- write only a branch name here).
-
- The resulting msg.txt file begins like so:
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: command, the reader should notice that:
-
- The latter is why the contributor would want to justify why pulling her
- work is worthwhile when creating the signed tag. The contributor then
--opens her favorite MUA, reads msg.txt, edits and sends it to her upstream
-+opens their favorite MUA, reads msg.txt, edits and sends it to their upstream
- integrator.
-
-
-@@ Documentation/howto/using-signed-tag-in-pull-request.txt: In the editor, the integrator will see something like this:
-
- Notice that the message recorded in the signed tag "Completed frotz
- feature" appears here, and again that is why it is important for the
--contributor to explain her work well when creating the signed tag.
-+contributor to explain their work well when creating the signed tag.
-
- As usual, the lines commented with `#` are stripped out. The resulting
- commit records the signed tag used for this validation in a hidden field
- so that it can later be used by others to audit the history. There is no
--need for the integrator to keep a separate copy of the tag in his
-+need for the integrator to keep a separate copy of the tag in their
- repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the
--above example), and there is no need to publish the tag to his public
-+above example), and there is no need to publish the tag to their public
- repository, either.
-
--After the integrator responds to the pull request and her work becomes
-+After the integrator responds to the pull request and their work becomes
- part of the permanent history, the contributor can remove the tag from
--her public repository, if she chooses, in order to keep the tag namespace
--of her public repository clean, with:
-+their public repository, if they choose, in order to keep the tag namespace
-+of their public repository clean, with:
-
- ------------
- $ git push example.com:/git/froboz.git :frotz-for-xyzzy
-
## Documentation/user-manual.txt ##
@@ Documentation/user-manual.txt: A fast-forward looks something like this:
2: b36e3f99716b ! 2: f611603718ab *: use singular they in comments
@@ Commit message
Replace these uses with "they/them" which universally includes all
potential readers.
+ Helped-by: Felipe Contreras [off-list ref]
Signed-off-by: Derrick Stolee [off-list ref]
## commit.c ##
@@ commit.c: static void handle_signed_tag(struct commit *parent, struct commit_ext
* We could verify this signature and either omit the tag when
* it does not validate, but the integrator may not have the
- * public key of the signer of the tag he is merging, while a
-+ * public key of the signer of the tag they are merging, while a
++ * public key of the signer of the tag being merged, while a
* later auditor may have it while auditing, so let's not run
* verify-signed-buffer here for now...
*
@@ config.h: void git_configset_init(struct config_set *cs);
*/
int git_configset_add_file(struct config_set *cs, const char *filename);
- ## contrib/hooks/multimail/git_multimail.py ##
-@@ contrib/hooks/multimail/git_multimail.py: class GitoliteEnvironmentLowPrecMixin(
- def get_repo_shortname(self):
- # The gitolite environment variable $GL_REPO is a pretty good
- # repo_shortname (though it's probably not as good as a value
-- # the user might have explicitly put in his config).
-+ # the user might have explicitly put in their config).
- return (
- self.osenv.get('GL_REPO', None) or
- super(GitoliteEnvironmentLowPrecMixin, self).get_repo_shortname()
-@@ contrib/hooks/multimail/git_multimail.py: def get_pusher(self):
- # __submitter into an RFC 2822 string already.
- return re.match(r'(.*?)\s*<', self.__submitter).group(1)
- else:
-- # Submitter has no configured email, it's just his name.
-+ # Submitter has no configured email, it's just their name.
- return self.__submitter
- else:
- # If we arrive here, this means someone pushed "Submit" from
-
## date.c ##
@@ date.c: int parse_expiry_date(const char *date, timestamp_t *timestamp)
/*
3: c40ad4a058a7 = 3: feecbd7a0c6e *: fix typos
4: d2c079264955 ! 4: 065e2fdeb151 CodingGuidelines: recommend singular they
@@ Commit message
To futher justify singular "they" as an acceptable grammatical concept,
I include the careful research of brian m. carlson who collected their
- thoughts on this matter [2] (lightly edited):
+ thoughts on this matter [4] (lightly edited):
Singular "they" has been used by native English speakers as part of
the language for over half a millennium and is widely used and
- understood. This usage is specified in Merriam Webster[3]:
+ understood. This usage is specified in Merriam Webster[5]:
The use of they, their, them, and themselves as pronouns of
indefinite gender and indefinite number is well established in
speech and writing, even in literary and formal contexts.
- Wiktionary notes[4] (references omitted):
+ Wiktionary notes[6] (references omitted):
Usage of they as a singular pronoun began in the 1300s and has been
common ever since, despite attempts by some grammarians, beginning
@@ Commit message
linguists, we should probably consider using the language that most
people will use in this context.
- [2] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
- [3] https://www.merriam-webster.com/dictionary/they
- [4] https://en.wiktionary.org/wiki/they
+ [4] https://lore.kernel.org/git/YKrk4dEjEm6+48ji@camp.crustytoothpaste.net/
+ [5] https://www.merriam-webster.com/dictionary/they
+ [6] https://en.wiktionary.org/wiki/they
+
+ Since singular "they" might be unfamiliar to some, we also list an
+ option to rephrase writing to use singular "you" or plural "they". We
+ can use singular "you" to refer to the reader instead of an abstract
+ user. Plural "they" works if we refer to multiple abstract users instead
+ of one. The English language does not have gendered versions of these
+ terms.
If we refer to a specific person, then using a gendered pronoun is
- appropriate. Examples within the Git codebase include:
+ appropriate. There can also be other cases where it is inappropriate for
+ us to update the existing examples within the Git codebase, such as:
* 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
@@ Commit message
modifying the license this way is not within the scope of the Git
project.
+ * Literal email messages in Documentation/howto/ should not be edited
+ for grammatical concerns such as this, unless we update the entire
+ document to fit the standard documentation format. If such an effort is
+ taken on, then the authorship would change and no longer refer to the
+ exact mail message.
+
+ * External projects consumed in contrib/ should not deviate solely for
+ style reasons. Recommended edits should be contributed to those
+ projects directly.
+
Other cases within the Git project were cleaned up by the previous
changes.
+ Helped-by: Junio C Hamano [off-list ref]
Signed-off-by: Derrick Stolee [off-list ref]
## Documentation/CodingGuidelines ##
@@ Documentation/CodingGuidelines: Writing Documentation:
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.
++ Refer to an anonymous user in a gender neutral way. Singular "they/them"
++ pronouns are preferred over "he/him" and "she/her". Do not use more
++ complicated constructs such as "he or she" or "s/he". When in doubt about
++ how to use this pronoun, then change your sentence to use singular "you"
++ (e.g. "When you want to do X, do Y") or plural "they" (e.g. "When users
++ want to do X, they can do Y.").
--
gitgitgadget
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-09 13:55:45
From: Derrick Stolee <redacted>
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.
Helped-by: Richard Kerry [off-list ref]
Helped-by: Junio C Hamano [off-list ref]
Signed-off-by: Derrick Stolee <redacted>
---
Documentation/SubmittingPatches | 8 ++++----
Documentation/git-push.txt | 4 ++--
Documentation/user-manual.txt | 2 +-
3 files changed, 7 insertions(+), 7 deletions(-)
@@ -372,10 +372,10 @@ If you like, you can put extra tags at the end: the patch attempts to fix. . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch.-. `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch- is ready for application. It is usually offered only after a- detailed review.+. `Reviewed-by:`, unlike the other tags, can only be offered by a+ reviewer when they are completely satisfied with the patch. It is+ offered only after reviews by reviewers who are known to be experts+ in the affected area by the community members. . `Tested-by:` is used to indicate that the person applied the patch and found it to have the desired effect.
@@ -244,8 +244,8 @@ Imagine that you have to rebase what you have already published. You will have to bypass the "must fast-forward" rule in order to replace the history you originally published with the rebased history. If somebody else built on top of your original history while you are-rebasing, the tip of the branch at the remote may advance with her-commit, and blindly pushing with `--force` will lose her work.+rebasing, the tip of the branch at the remote may advance with their+commit, and blindly pushing with `--force` will lose their work. + This option allows you to say that you expect the history you are updating is what you rebased and want to replace. If the remote ref
@@ -2792,7 +2792,7 @@ A fast-forward looks something like this: In some cases it is possible that the new head will *not* actually be a descendant of the old head. For example, the developer may have-realized she made a serious mistake, and decided to backtrack,+realized they made a serious mistake, and decided to backtrack, resulting in a situation like: ................................................
From: Felipe Contreras <hidden> Date: 2021-06-09 15:21:27
Derrick Stolee wrote:
On 6/8/2021 4:11 AM, Felipe Contreras wrote:
quoted
Jeff King wrote:
quoted
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
In general, I do like the efficiency and readability of singular "they".
As a native speaker, I have no problem reading it, and I have little
sense that most of my native-speaker acquaintances would, either.
Does this sound correct to you?
We thank the reviewer for their helpful comments
In the case of an anonymous reviewer (such as a single-blind review of
an academic paper), then this is exactly how one should acknowledge a
single reviewer.
From: Felipe Contreras <hidden> Date: 2021-06-09 15:34:43
Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
Replace these uses with "they/them" to ensure that these documentation
examples apply to all potential users without exception.
This is not the main purpose of documentation.
The main purpose is to convey useful information as accurately and
readably as possible.
@@ -372,10 +372,10 @@ If you like, you can put extra tags at the end: the patch attempts to fix. . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch.-. `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch- is ready for application. It is usually offered only after a- detailed review.+. `Reviewed-by:`, unlike the other tags, can only be offered by a+ reviewer when they are completely satisfied with the patch. It is+ offered only after reviews by reviewers who are known to be experts+ in the affected area by the community members.
This is convoluted, but at least doesn't sound wrong.
@@ -2792,7 +2792,7 @@ A fast-forward looks something like this: In some cases it is possible that the new head will *not* actually be a descendant of the old head. For example, the developer may have-realized she made a serious mistake, and decided to backtrack,+realized they made a serious mistake, and decided to backtrack,
This suffers from the same problem "the reviewer" above did: it's
semantically singular. It doesn't sound grammatically right to many.
Another solution is to use an indefinite or generic noun: "they" -> "a".
the developer may have realized a serious mistake was made
Of course it isn't a good style to use the passive voice, and we will be
counting on the reader assuming who made mistake. But at least it's
more grammatically correct than your version.
So far a step in the wrong direction.
--
Felipe Contreras
Another semantically singular antecedent.
But this one has an easy fix:
can be used by programmers of the callback as they see fit.
It's more weird, but at least grammatically correct.
@@ -648,3 +648,10 @@ 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.++ Refer to an anonymous user in a gender neutral way. Singular "they/them"+ pronouns are preferred over "he/him" and "she/her". Do not use more+ complicated constructs such as "he or she" or "s/he". When in doubt about+ how to use this pronoun, then change your sentence to use singular "you"+ (e.g. "When you want to do X, do Y") or plural "they" (e.g. "When users+ want to do X, they can do Y.").
You are prescribing what language to use, this is prescriptivism.
Earlier you said:
Linguists fit roughly into two camps: prescriptive and descriptive.
The former specify rules for people to use, and the latter document
language as it is actually used without forming a judgment.
Some prescriptivists think it is acceptable, and some do not. But
descriptivists will rightly note that it is and has been commonly
used in English across countries, cultures, and contexts for an
extended period of time and is therefore generally accepted by most
English speakers as a normal part of the language.
Descriptivist linguists indeed have noted that the singular "they" has
been used in the past, but not in the way you are proposing.
Singular "they" has been used on semantically plural antecedents, not
singular antecedents [1]. This detail easily escapes non-linguists.
Moreover, descriptivists would also note that "she" and "he" have been
commonly used as well, and there's nothing wrong with using them.
A descriptivist linguist would not dare to prescribe how language
should be used in a community, like you are doing.
[1] https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they
--
Felipe Contreras
On Wed, Jun 09 2021, Derrick Stolee via GitGitGadget wrote:
Updates in v2
=============
* Some edits were removed because they were in contrib/ or
Documentation/howto/ and these are now listed as exclusions in the
message of Patch 4.
Thanks.
* Several recommendations to improve the edits in the documentation and
code comments were incorporated. Those who recommended these edits are
credited with "Helped-by" tags.
I think a v2 is a bit premature with all the active discussion on the v1
thread, a lot of which isn't addressed by the v2 or this CL, e.g. many
point I[1] and others raised.
My main objection of extending this to commit messages and thus making
e.g. non-native speakers be on their toes when contributing to the
project is gone, so that's good.
I'm still not in favor of this change because I think an active
recommendation like "Refer to an anonymous user in a gender neutral way"
probably isn't needed if we simply document that our preferred prose is
to avoid the issue entirely, which is the case in most of our
documentation.
The below for-show patch[2] shows an alternate approach that I think is
a better direction than this series.
It shows how some of the s/he|she/they/g search-replacements you did
could IMO be better if we simply reduced the amount of prose, e.g. in
strbuf.h changing:
passes a context pointer, which can be used by the programmer of the
callback as she sees fit.
To:
passes a `void *context` to the callback `fn`
Is a better change than a mere s/she/they/g. Nobody needs all this
verbosity to understand the common pattern of passing a user-controlled
'void *` to a callback. It's implicitly understood by the technical
level of the reader this documentation is targeted at.
So much of this just seems premature, e.g. your change to git-push.txt
of s/her/they/.
If we look more carefully at that we can see that the "her" was added in
28f5d17611 (remote.c: add command line option parser for
"--force-with-lease", 2013-07-08), and then since fddfaf8a22
(git-push.txt: clean up force-with-lease wording, 2015-03-26) the
paragraph right after that discusses "other people", instead of
continuing with the example already provided.
Having it be s/her/they/ -> other people isn't much of an overall
improvement, and just seems like blind search-replacement.
Perhaps my WIP rewrite isn't much better, but it at least tries to make
forward progress on not having two paragraphs that read like different
semi-related pages in a book.
There's a reason your patch series isn't bigger than it is, this sort of
prose is the rare exception in our documentation, and for reasons that
trump any perceived sensitivity to specific pronouns from some people:
It's overly verbose.
1. https://lore.kernel.org/git/875yyp4fun.fsf@evledraar.gmail.com/
2.
@@ -551,6 +551,31 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file).+ Prefer succinctness and matter-of-factly describing functionality in+ the abstract. E.g.:++ --short:: Emit output in the short-format.++ Not something like these overly verbose alternatives:++ --short:: Use this to emit output in the short-format.+ --short:: You can use this to get output in the short-format.+ --short:: A user who prefers shorter output could....+ --short:: Should a person and/or program want shorter output, he+ she/they/it can...++ When it becomes awkward to stick to this style prefer "you" when+ addressing the the hypothetical user, and possibly "we" when+ discussing how the program might react to the user.++ You can use this option instead of --xyz, but we might remove+ support for it in future versions.++ While keeping in mind that you can probably be less verbose, e.g.:++ Use this instead of --xyz. This option might be removed in future+ versions.+ Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions.
@@ -240,17 +240,17 @@ already exists on the remote side. This option overrides this restriction if the current value of the remote ref is the expected value. "git push" fails otherwise. ++When collaborating with others this is safer than using the `--force` option. Imagine that you have to rebase what you have already published.-You will have to bypass the "must fast-forward" rule in order to-replace the history you originally published with the rebased history.-If somebody else built on top of your original history while you are-rebasing, the tip of the branch at the remote may advance with her-commit, and blindly pushing with `--force` will lose her work.-+-This option allows you to say that you expect the history you are-updating is what you rebased and want to replace. If the remote ref-still points at the commit you specified, you can be sure that no-other people did anything to the ref. It is like taking a "lease" on+By using `--force` you might inadvertently clobber commits that+someone else pushed on top of branch.++++Unlike `--force`, `--force-with-lease` will transmit the expected+object ID to the remote server (similar to linkgit:git-update-ref[1]'s+`<oldvalue>`, and thus provides a safeguard against inadvertently+clobbering remote refs which have changed since you retrieved them+with `git fetch`. Using this option has the effect of taking a "lease" on the ref without explicitly locking it, and the remote ref is updated only if the "lease" is still valid. +
From: Felipe Contreras <hidden> Date: 2021-06-09 17:22:23
Ævar Arnfjörð Bjarmason wrote:
The below for-show patch[2] shows an alternate approach that I think is
a better direction than this series.
It shows how some of the s/he|she/they/g search-replacements you did
could IMO be better if we simply reduced the amount of prose, e.g. in
strbuf.h changing:
passes a context pointer, which can be used by the programmer of the
callback as she sees fit.
To:
passes a `void *context` to the callback `fn`
Is a better change than a mere s/she/they/g. Nobody needs all this
verbosity to understand the common pattern of passing a user-controlled
'void *` to a callback. It's implicitly understood by the technical
level of the reader this documentation is targeted at.
@@ -551,6 +551,31 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file).+ Prefer succinctness and matter-of-factly describing functionality in+ the abstract. E.g.:++ --short:: Emit output in the short-format.++ Not something like these overly verbose alternatives:++ --short:: Use this to emit output in the short-format.+ --short:: You can use this to get output in the short-format.+ --short:: A user who prefers shorter output could....+ --short:: Should a person and/or program want shorter output, he+ she/they/it can...
@@ -240,17 +240,17 @@ already exists on the remote side. This option overrides this restriction if the current value of the remote ref is the expected value. "git push" fails otherwise. ++When collaborating with others this is safer than using the `--force` option. Imagine that you have to rebase what you have already published.-You will have to bypass the "must fast-forward" rule in order to-replace the history you originally published with the rebased history.-If somebody else built on top of your original history while you are-rebasing, the tip of the branch at the remote may advance with her-commit, and blindly pushing with `--force` will lose her work.-+-This option allows you to say that you expect the history you are-updating is what you rebased and want to replace. If the remote ref-still points at the commit you specified, you can be sure that no-other people did anything to the ref. It is like taking a "lease" on+By using `--force` you might inadvertently clobber commits that+someone else pushed on top of branch.
* the branch?
++
+
+Unlike `--force`, `--force-with-lease` will transmit the expected
+object ID to the remote server (similar to linkgit:git-update-ref[1]'s
+`<oldvalue>`, and thus provides a safeguard against inadvertently
+clobbering remote refs which have changed since you retrieved them
+with `git fetch`. Using this option has the effect of taking a "lease" on
Clearer and more useful. I didn't even notice where the gender of the
reader was replaced, or where it supposedly came from.
Instead we focus on what's important: instructing the user.
quoted hunk
the ref without explicitly locking it, and the remote ref is updated
only if the "lease" is still valid.
+
From: Felipe Contreras <hidden> Date: 2021-06-09 17:45:43
Kerry, Richard wrote:
What do you prefer?
A. We thank the reviewer for their helpful comments
B. We thank the reviewer for her helpful comments
[RK] If this is, as it appears to be, a reference to a specific reviewer, then use their preferred pronoun, or possibly a conventional singular one if you know their name and they haven't specified a preference.
[RK] Only if they aren't known, and especially if they are one from a pool, then "their".
[RK] Or make them plural - We thank the reviewers for their helpful comments.
[RK] Or rephrase to sidestep the issue (though it isn't clear to me here what that option would be)
The question is not what sort of rules you would like us to enforce (I
for one don't believe in policing speech).
The question is what you as a native English speaker, or non-native
speaker, think of the sentences as they are. Do they sound grammatically
correct to you?
Would it be possible for you to use quoted line prefix [1] as is common
on this mailing list? We only have the beginnings of a mailing list
etiquette [2], but this is something that reads very different from
everyone else.
Cheers.
[1] https://en.wikipedia.org/wiki/Posting_style#Quoted_line_prefix
[2] https://lore.kernel.org/git/20210512233412.10737-1-dwh@linuxprogrammer.org/
--
Felipe Contreras
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
Why should the pronoun apply to the reader? If the documentation wants
to refer to the reader, it should use "you". If it's using "he" then
it's referring to someone else previously mentioned in the
documentation, not to me. Just because I am male does not mean I suffer
from confusion when I read documentation like: "Alice wants to
communicate with others securely. She can do that by using gpg."
But it's not part of standard English language.
<snip>
You can use "nucular" if you want (many people do). I will use
"nuclear".
You can use "nucular", but you will look stupid.
Both can be valid, and we shouldn't demand the use of one over the
other.
Sure we can; one is not valid. You also may not "axe" me a question, or
drink an "expresso".
Also you argued against using they because it is not standard English,
but then argued that it is fine to use non standard English.
@@ -373,7 +373,7 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch+ reviewer and means that they are completely satisfied that the patch
Say wait a minute. If that is a "singular they", then why was the "is"
changed to "are"? I think that belies the fact that there is no such
thing as a "singular they".
From: Felipe Contreras <hidden> Date: 2021-06-09 20:18:40
Phillip Susi wrote:
Felipe Contreras [off-list ref] writes:
quoted
Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
Why should the pronoun apply to the reader? If the documentation wants
to refer to the reader, it should use "you". If it's using "he" then
it's referring to someone else previously mentioned in the
documentation, not to me.
Indeed, and the patches don't apply exclusively to the reader. Here [1]
the relevant person is somebody else who rebased a branch. It is unclear
what kind of "cognitive dissonance" would a reader experience when she
reads that that somebody happens to be a she.
quoted
You can use "nucular" if you want (many people do). I will use
"nuclear".
You can use "nucular", but you will look stupid.
I do think so, but that doesn't stop people from using it.
Such is the nature of language.
quoted
Both can be valid, and we shouldn't demand the use of one over the
other.
Sure we can; one is not valid. You also may not "axe" me a question, or
drink an "expresso".
According to some dictionaries "nucular" is valid [2].
Plus, I don't think "valid" is the right word. Some people have a
descpritive view of language, and in that view all words are valid, or
rather: no word is invalid.
What makes words land in a dictionary is simply how much people use
them. The word "cute" used to mean "clever" [3], and it was "invalid" to
use it as we use it today. But people didn't care, and the meaning of
the word was forced to change. Dictioaries simply recorded the will of
the people.
Also you argued against using they because it is not standard English,
but then argued that it is fine to use non standard English.
@@ -373,7 +373,7 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch+ reviewer and means that they are completely satisfied that the patch
Say wait a minute. If that is a "singular they", then why was the "is"
changed to "are"?
Great point. I doubt any linguist would be happy with:
can only be offered by the reviewer and means that they is completely
satisfied...
Unless we are in the context of African-American Vernacular English.
I think that belies the fact that there is no such thing as a
"singular they".
There is such a thing as singular they, but it's not what the proponents
of this patch think [1]:
This is a good use of singular they:
Everyone returned to their seats
This isn't:
We thank the anonymous reviewer for their helpful comments
Cheers.
[1] https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they
--
Felipe Contreras
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/7vehuyosaa.fsf@alter.siamese.dyndns.org/
We edit those documents all the time, e.g. when `pu` was renamed to
`seen`.
And I think it is appropriate to edit them: as soon as those emails were
copied into a version-controlled repository, we implicitly indicated our
intention to iterate on them. Why else would we need to version-control
them, after all.
And it is desirable to edit them, too. If we truly want to be welcoming
and inviting (especially to potential contributors who currently feel
underrepresented), we need to model the language in our documentation
accordingly.
And I want to believe that we truly want to be welcoming like that.
Ciao,
Dscho
From: Johannes Schindelin <hidden> Date: 2021-06-10 08:18:29
Hi Emily,
On Tue, 8 Jun 2021, Emily Shaffer wrote:
There is value in intentionally defaulting to "she/her", especially in
settings where women are underrepresented. It can be a nice way to shake
the foundations of unconscious bias in the reader's head. See
https://www.askamanager.org/2011/07/why-i-refer-to-everyone-as-she.html
as an example.
I am glad you brought this up.
It is all too easy for male readers such as myself to not even notice how
effortless it is to read text that includes you, whether by the pronoun
"he" or by avoiding any gendered pronoun altogether.
All the more surprising that the same male readers (again, I will include
myself as it still happens to me, despite all the work I embarked on to
become more conscious of my own biases) will stumble over sentences where
a female pronoun "excludes" them.
And the first reaction, funnily enough, is rarely "Oh, _that_ is how I
make half of the population feel all the time!". Instead it is more like
"How dare they exclude me"?
Funny side note: this is precisely what happened recently in Germany,
where a law was proposed, and in contrast to common practices (which
dictates to use the "generic male form", i.e. "he/him", as the German
language does not have a singular "they"), it used the "generic female"
instead. I bet you can imagine the indignant backlash from male
politicians...
Let me be the first to admit that working on this kind of bias isn't easy,
and I imagine that other male readers' struggles will be similar (or even
more pronounced, if they are less interested in biases and fairness than I
am).
Seeing how threatening these efforts to adjust our language are sometimes
perceived, I often find it pretty difficult to tread carefully. For
example, I recently suggested that stumbling over a "singular they" might
give male readers an opportunity to develop empathy with the
underrepresented, to experience a glimpse of what it means to feel
excluded (even if they weren't excluded at all), and consequently to pay
more attention. This suggestion did not quite have the intended effect, I
must say: it seems that this invitation was misunderstood as an attack
instead.
In light of this experience, even if I generally agree with your point about
using "she/he" by default, I believe that Stolee's direction is more
diplomatic.
On Mon, Jun 07, 2021 at 04:57:45PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
Replace these uses with "they/them" to ensure that these documentation
examples apply to all potential users without exception.
However, in this case, I think "they/them" is appropriate as a default.
As you say, this documentation is intended as a guide to potential users
and contributors, and should apply to them. Thanks for writing the
change.
For what it's worth, I agree. Thank you, Stolee!
Ciao,
Dscho
From: Johannes Schindelin <hidden> Date: 2021-06-10 08:20:41
Hi,
On Mon, 7 Jun 2021, Ævar Arnfjörð Bjarmason wrote:
On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
quoted
From: Derrick Stolee <redacted>
Several comments in our code refer to an anonymous user with "he/him" or
"she/her" pronouns, and the choice between the two is arbitrary.
Replace these uses with "they/them" which universally includes all
potential readers.
Signed-off-by: Derrick Stolee <redacted>
---
commit.c | 2 +-
config.h | 2 +-
contrib/hooks/multimail/git_multimail.py | 4 ++--
It is probably a good idea to make that upstream project not only the
authoritative source, but the only source. In other words, I think we
should replace the files in `contrib/hooks/multimail/` by a `README` that
points to the indicated URL.
Ciao,
Dscho
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' 'commitrefs/heads/O1# -- ignore all of this textcommitter$GIT_COMMITTER_NAME<$GIT_COMMITTER_EMAIL>$GIT_COMMITTER_DATE-# $GIT_COMMITTER_NAME has inserted here for his benefit.+# $GIT_COMMITTER_NAME has inserted here for this benefit.
What is this even supposed to mean? I fail to parse that sentence in both
original and modified forms.
Looking at 401d53fa350 (Teach fast-import to ignore lines starting with
'#', 2007-08-01), where the comment was added, I deduce from the commit
message that the personal pronoun _was_ actually intended.
So maybe a better way to express the original intent would be this:
# comment added by $GIT_COMMITTER_NAME; fast-import should ignore it
Ciao,
Dscho
From: Felipe Contreras <hidden> Date: 2021-06-10 14:37:01
Johannes Schindelin wrote:
And it is desirable to edit them, too. If we truly want to be welcoming
and inviting (especially to potential contributors who currently feel
underrepresented), we need to model the language in our documentation
accordingly.
Whether or not this particular approach is how we want to model the
language in our documentation is a matter for debate.
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-10 14:43:44
Johannes Schindelin wrote:
It is all too easy for male readers such as myself to not even notice how
effortless it is to read text that includes you, whether by the pronoun
"he" or by avoiding any gendered pronoun altogether.
I am a male reader, and I have no problem reading "she", as many other
(presumably male) readers have stated as well.
In light of this experience, even if I generally agree with your point about
using "she/he" by default, I believe that Stolee's direction is more
diplomatic.
Except in diplomacy you are supposed to work with your counterpart, not
completely ignore it.
*Nobody* has a problem with using "she/her" in the documentation, and
yet you push for the option guaranteed to increase conflict.
That the opposite of diplomacy.
--
Felipe Contreras
@@ -373,7 +373,7 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch+ reviewer and means that they are completely satisfied that the patch
Say wait a minute. If that is a "singular they", then why was the "is"
changed to "are"? I think that belies the fact that there is no such
thing as a "singular they".
Singular "they" works the same as singular "you". For example:
...means that _you are_ completely satisfied...
Singular "you" had a similar backlash in the 1660s as singular "they"
is having in this thread, but singular "you" has lasted (and we use
"thou" only to signify someone using old-timey language).
There is more of this in [1] and [2]
[1] https://public.oed.com/blog/a-brief-history-of-singular-they/
[2] https://en.wikipedia.org/wiki/T%E2%80%93V_distinction#English
Thanks,
-Stolee
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' 'commitrefs/heads/O1# -- ignore all of this textcommitter$GIT_COMMITTER_NAME<$GIT_COMMITTER_EMAIL>$GIT_COMMITTER_DATE-# $GIT_COMMITTER_NAME has inserted here for his benefit.+# $GIT_COMMITTER_NAME has inserted here for this benefit.
What is this even supposed to mean? I fail to parse that sentence in both
original and modified forms.
I missed that there appears to be a second typo, s/has/was/, giving
# $GIT_COMMITTER_NAME was inserted here for this benefit
implying that the environment variable exists to allow changing the
committer info during this process.
Looking at 401d53fa350 (Teach fast-import to ignore lines starting with
'#', 2007-08-01), where the comment was added, I deduce from the commit
message that the personal pronoun _was_ actually intended.
So maybe a better way to express the original intent would be this:
# comment added by $GIT_COMMITTER_NAME; fast-import should ignore it
I think the first comment "# -- ignore all of this text" satisfies
that need, so maybe we just delete this typo line?
Thanks,
-Stolee
From: brian m. carlson <hidden> Date: 2021-06-10 22:06:48
On 2021-06-08 at 07:10:36, Jeff King wrote:
On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
quoted
If we use singular "they/them" pronouns instead of "he/him" or "she/her"
pronouns, then we can avoid this congitive load on the reader.
Using singular "they" is also incredibly efficient. Choosing a gendered
pronoun is usually arbitrary between "he" or "she". Using constructs
such as "he or she", "s/he", or "(s)he" are more complicated than
singular "they".
In general, I do like the efficiency and readability of singular "they".
As a native speaker, I have no problem reading it, and I have little
sense that most of my native-speaker acquaintances would, either.
I agree. I'm very much in favor of singular "they".
I _do_ worry that it would be jarring or difficult to read for
non-native speakers (or perhaps native speakers who aren't in my circle
of acquaintances). There have been a few comments to that effect on the
list, but it's hard to consider that data and not anecdotes.
I have heard these arguments, and as a someone who speaks two other
languages, I'm sympathetic to the argument that this is a little tricky.
For me, personally, I liken it to the French "on" (one), which can be
used in many, but not all, places that "nous" (we) is used, to reflect
the first-person plural, but with some slightly different shades of
meaning. This is a tricky part of the language and it's a hard one to
get right, but it's also extremely commonly used, so it's nearly
obligatory to be comfortable with it in order to be reasonably
conversant in French.
Similarly, singular "they" is extremely common in informal written
English (e.g., texts and tweets) and nearly ubiquitous in spoken
English, where people use it routinely without thinking[0]. So while I am
in favor of making things easier for non-native speakers, this is so
common in actual usage that it's practically unavoidable and it's a
feature of the language that almost every speaker will be exposed to and
they will need to be comfortable with it to function effectively.
Given this context, I'm comfortable with adopting this change.
One thing that gives me some comfort is your research here:
quoted
Perhaps due to similar reasons, official style guides have changed their
stance on singuler "they" in recent years. For example, the APA style
guide changed their official recommendation in 2019 [1]. The MLA
handbook also references helpful ways to use singular "they" [2]. While
not fully endorsing it, the Chicago Manual of Style has removed its
blanket ban on singular "they" [3] (the previous recommendation was to
only use "it" as a singular non-gendered pronoun).
[1] https://apastyle.apa.org/blog/singular-they
[2] https://style.mla.org/using-singular-they/
[3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
I don't know to what degree those style guidelines take into account
non-native speakers. But they at least provide a sense that this style
is in wide-ish use. And probably growing use, as well, considering that
they have changed recently. So even if it may be surprising to some
readers at first, I hope it may become less so as time goes on and
projects (like ours) make it more commonplace.
I agree that this is becoming more common, not less, and that it is
gaining acceptance by many authorities.
So I think this is a reasonable style suggestion to put in our
guidelines.
I agree with this as well.
[0] I have noticed this to be true of non-native but fluent colleagues,
for example.
--
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA
From: brian m. carlson <hidden> Date: 2021-06-10 22:32:39
On 2021-06-09 at 15:44:59, Ævar Arnfjörð Bjarmason wrote:
On Wed, Jun 09 2021, Derrick Stolee via GitGitGadget wrote:
quoted
Updates in v2
=============
* Some edits were removed because they were in contrib/ or
Documentation/howto/ and these are now listed as exclusions in the
message of Patch 4.
Thanks.
quoted
* Several recommendations to improve the edits in the documentation and
code comments were incorporated. Those who recommended these edits are
credited with "Helped-by" tags.
I think a v2 is a bit premature with all the active discussion on the v1
thread, a lot of which isn't addressed by the v2 or this CL, e.g. many
point I[1] and others raised.
My main objection of extending this to commit messages and thus making
e.g. non-native speakers be on their toes when contributing to the
project is gone, so that's good.
I'm still not in favor of this change because I think an active
recommendation like "Refer to an anonymous user in a gender neutral way"
probably isn't needed if we simply document that our preferred prose is
to avoid the issue entirely, which is the case in most of our
documentation.
I agree that in many cases in technical writing that the passive voice
(or another technique) may be preferable. For example, this selection
about O_TRUNC from open(2):
If the file already exists and is a regular file and the access mode
allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to
length 0. If the file is a FIFO or terminal device file, the O_TRUNC
flag is ignored. Otherwise, the effect of O_TRUNC is unspecified.
Who is truncating it? Who is ignoring it? Who is not specifying it?
In all three cases, the specific actor is unimportant or irrelevant, and
we're better off using the passive voice here than trying to enumerate
the actor.
The below for-show patch[2] shows an alternate approach that I think is
a better direction than this series.
It shows how some of the s/he|she/they/g search-replacements you did
could IMO be better if we simply reduced the amount of prose, e.g. in
strbuf.h changing:
passes a context pointer, which can be used by the programmer of the
callback as she sees fit.
To:
passes a `void *context` to the callback `fn`
In many cases, saying less is better, I agree. If we don't need to
refer to a human being, then we don't need to consider any pronouns for
that human being. If we communicate things more simply with fewer
words, then that's clearly better overall for everyone involved.
Nobody's reading documentation for pleasure, after all.
I do think that the recommendation that we refer to an anonymous user in
a gender-neutral way still stands, though. Sometimes we will need to
refer to the user or another human actor and that will be the most
natural way to express the idea, so we should use gender-neutral
language to do so.
So roughly here, I'm in favor of both approaches.
--
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA
[[PGP Signed Part:Undecided]]
On 2021-06-09 at 15:44:59, Ævar Arnfjörð Bjarmason wrote:
quoted
On Wed, Jun 09 2021, Derrick Stolee via GitGitGadget wrote:
quoted
Updates in v2
=============
* Some edits were removed because they were in contrib/ or
Documentation/howto/ and these are now listed as exclusions in the
message of Patch 4.
Thanks.
quoted
* Several recommendations to improve the edits in the documentation and
code comments were incorporated. Those who recommended these edits are
credited with "Helped-by" tags.
I think a v2 is a bit premature with all the active discussion on the v1
thread, a lot of which isn't addressed by the v2 or this CL, e.g. many
point I[1] and others raised.
My main objection of extending this to commit messages and thus making
e.g. non-native speakers be on their toes when contributing to the
project is gone, so that's good.
I'm still not in favor of this change because I think an active
recommendation like "Refer to an anonymous user in a gender neutral way"
probably isn't needed if we simply document that our preferred prose is
to avoid the issue entirely, which is the case in most of our
documentation.
I agree that in many cases in technical writing that the passive voice
(or another technique) may be preferable. For example, this selection
about O_TRUNC from open(2):
If the file already exists and is a regular file and the access mode
allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to
length 0. If the file is a FIFO or terminal device file, the O_TRUNC
flag is ignored. Otherwise, the effect of O_TRUNC is unspecified.
Who is truncating it? Who is ignoring it? Who is not specifying it?
In all three cases, the specific actor is unimportant or irrelevant, and
we're better off using the passive voice here than trying to enumerate
the actor.
Exactly. The preferred prose in Git's documentation in this regard
should be the same matter of fact prose found in C library, binutils
etc. documentation.
quoted
The below for-show patch[2] shows an alternate approach that I think is
a better direction than this series.
It shows how some of the s/he|she/they/g search-replacements you did
could IMO be better if we simply reduced the amount of prose, e.g. in
strbuf.h changing:
passes a context pointer, which can be used by the programmer of the
callback as she sees fit.
To:
passes a `void *context` to the callback `fn`
In many cases, saying less is better, I agree. If we don't need to
refer to a human being, then we don't need to consider any pronouns for
that human being. If we communicate things more simply with fewer
words, then that's clearly better overall for everyone involved.
Nobody's reading documentation for pleasure, after all.
I do think that the recommendation that we refer to an anonymous user in
a gender-neutral way still stands, though. Sometimes we will need to
refer to the user or another human actor and that will be the most
natural way to express the idea, so we should use gender-neutral
language to do so.
So roughly here, I'm in favor of both approaches.
When do we need or even prefer to refer to a user like that?
I haven't seen an example in our documentation that's actually better
off because we're talking about things as if two "people" we need to
invent pronouns for are interacting.
Can anyone name one that'll stand up under scrutiny, i.e. once we can
look at it and see if we couldn't phrase it better by avoiding the issue
this series tries to address with a regex search-replacement?
The diffstat of this series is only:
12 files changed, 22 insertions(+), 15 deletions(-)
I've looked at all of them and I can't see one that wouldn't be better
if the relevant text was changed similarly to what I've suggested
upthread.
That's why I don't think this proposal is useful. If we accept this
series we're going to be left with an active recommendation for a
pattern that's already almost nonexistent in our documentation.
Perhaps that's because we're doing it 98% right already and aren't using
"he" or "she" but "they" or "their". The multiple ways you can use
"they" or "their" in the English language makes that hard to grep for. A
lot of our "they"'s are referring e.g. to a command-line option, or
"their" referring to "their arguments", as in the argv vector of a
program.
The skepticism about this being needed at all isn't an opinion I hold
about software documentation in general, but about software in Git's
problem space specifically.
Git isn't something like software to track medical records or tax
filings where we can make a hard assumption that the software is dealing
with data from people, and thus the software's documentation might
regularly expect to need to discuss such an invented cast of characters.
We just have:
* You: The "user" of the software. Maybe a human being, but that's
usually no more assumed than the "user" of chmod(2) being a human
being.
* Other users, not people, but users in the UID/GID sense of the
word. Describing system-local interactions that are really two
operating system users interacting in terms of assuming that they map
onto two people just adds confusion.
Note how e.g. chmod(2) and other such documentation rightly avoids
bringing people into the matter. At most it refers to "owner" or
"another user" etc.
* "Other users" on the network, e.g. you make a change, it conflicts
with upstream. I think in all these cases saying something like:
You can add data and commit it, then push it. Once you push it
you might find another person has made changes on the same
branch, he/she/it/they changed the same file as you, now you've
got a conflict...
Is worse than:
When push your branch you might get a conflict with the remote's
upstream branch, if merging it results in a conflict then...
In such scenarios we're talking about e.g. our local state
interacting with remote network state, those are ultimately commits
or other data we have to deal with in some way.
It's almost never important whether that data was made by a human or
some automated system. Inventing a cast of characters just makes
things more confusing.
I think the nearest we come to rightly discussing actual people in the
context of git's documentation is things like commit envelope data
(names, E-Mail addresses). Even those don't cleanly map to human beings,
so our documentation probably shouldn't be implying that in its prose.
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' 'commitrefs/heads/O1# -- ignore all of this textcommitter$GIT_COMMITTER_NAME<$GIT_COMMITTER_EMAIL>$GIT_COMMITTER_DATE-# $GIT_COMMITTER_NAME has inserted here for his benefit.+# $GIT_COMMITTER_NAME has inserted here for this benefit.
What is this even supposed to mean? I fail to parse that sentence in both
original and modified forms.
I missed that there appears to be a second typo, s/has/was/, giving
# $GIT_COMMITTER_NAME was inserted here for this benefit
implying that the environment variable exists to allow changing the
committer info during this process.
quoted
Looking at 401d53fa350 (Teach fast-import to ignore lines starting with
'#', 2007-08-01), where the comment was added, I deduce from the commit
message that the personal pronoun _was_ actually intended.
So maybe a better way to express the original intent would be this:
# comment added by $GIT_COMMITTER_NAME; fast-import should ignore it
I think the first comment "# -- ignore all of this text" satisfies
that need, so maybe we just delete this typo line?
D'oh! That's the best solution. Just delete that line.
Thanks,
Dscho
From: Felipe Contreras <hidden> Date: 2021-06-11 16:02:58
Derrick Stolee wrote:
Singular "you" had a similar backlash in the 1660s as singular "they"
is having in this thread, but singular "you" has lasted (and we use
"thou" only to signify someone using old-timey language).
There is more of this in [1] and [2]
[1] https://public.oed.com/blog/a-brief-history-of-singular-they/
Let's see...
In modern English, that’s: ‘Each man hurried . . . till they drew near
. . . where William and his darling were lying together.’
Yeah, that grammatical singular "they" indeed, but with a semantic
plural antecedent, so no, that's not what you are proposing above.
I'd say leave linguistics to linguists.
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-11 16:12:05
brian m. carlson wrote:
Similarly, singular "they" is extremely common in informal written
English (e.g., texts and tweets) and nearly ubiquitous in spoken
English, where people use it routinely without thinking[0].
Singular "they" with semantic plural antecedents, yes, singular "they"
with semantic singular antecedents, no.
That's like saying we should all eat mushrooms because they have many
beneficial properties, which is true...
but not *all* mushrooms.
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-11 16:34:14
Ævar Arnfjörð Bjarmason wrote:
That's why I don't think this proposal is useful. If we accept this
series we're going to be left with an active recommendation for a
pattern that's already almost nonexistent in our documentation.
Perhaps that's because we're doing it 98% right already and aren't using
"he" or "she" but "they" or "their". The multiple ways you can use
"they" or "their" in the English language makes that hard to grep for. A
lot of our "they"'s are referring e.g. to a command-line option, or
"their" referring to "their arguments", as in the argv vector of a
program.
The skepticism about this being needed at all isn't an opinion I hold
about software documentation in general, but about software in Git's
problem space specifically.
Plus I find it odd that as soon as a progressive issue comes forward
everyone suddenly flips the rules not only of proposed changes, but
logic in general.
The burden of proof should be on the side that is proposing the change
to explain why it's better that the current situation, not to the
opposing side to explain why it isn't.
"I like X" is not an argument in favor of a proposed change, you need to
explain why the current status quo is not OK.
Every patch is subjected to this standard, why should this series be
exempted?
The side for the motion has not yet explained what's wrong with the
current practice of avoiding pronouns altogether, or using "she" and
"he" interchangeably. Even worse, they are assuming they already won the
debate and are not even engaging with the opposing arguments.
Ignoring arguments against your beliefs is not conducive to growth.
Cheers.
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-11 17:03:40
Phillip Susi wrote:
Felipe Contreras [off-list ref] writes:
quoted
This is a good use of singular they:
Everyone returned to their seats
Shouldn't seat be singular there so that it agrees in number with the
singular their?
Good point.
I do not know, and I didn't pick the example; the American Heritage
Dictionary did.
Translated into Spansih both uses would be correct "seat" or "seats"
(except "seat" wouldn't have "their", but the equivalent of "his/her").
Anyway, even though I don't mind talking about this, I don't think this
mailing list is the place for that. The git documentation has many
problems, but heavily using gendered pronouns isn't one of them.
Cheers.
--
Felipe Contreras
On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:
On Thu, Jun 10 2021, brian m. carlson wrote:
...
quoted
In many cases, saying less is better, I agree. If we don't need to
refer to a human being, then we don't need to consider any pronouns for
that human being. If we communicate things more simply with fewer
words, then that's clearly better overall for everyone involved.
Nobody's reading documentation for pleasure, after all.
I do think that the recommendation that we refer to an anonymous user in
a gender-neutral way still stands, though. Sometimes we will need to
refer to the user or another human actor and that will be the most
natural way to express the idea, so we should use gender-neutral
language to do so.
So roughly here, I'm in favor of both approaches.
When do we need or even prefer to refer to a user like that?
I haven't seen an example in our documentation that's actually better
off because we're talking about things as if two "people" we need to
invent pronouns for are interacting.
Can anyone name one that'll stand up under scrutiny, i.e. once we can
look at it and see if we couldn't phrase it better by avoiding the issue
this series tries to address with a regex search-replacement?
The diffstat of this series is only:
12 files changed, 22 insertions(+), 15 deletions(-)
I've looked at all of them and I can't see one that wouldn't be better
if the relevant text was changed similarly to what I've suggested
upthread.
That's why I don't think this proposal is useful. If we accept this
series we're going to be left with an active recommendation for a
pattern that's already almost nonexistent in our documentation.
Perhaps that's because we're doing it 98% right already and aren't using
"he" or "she" but "they" or "their". The multiple ways you can use
"they" or "their" in the English language makes that hard to grep for. A
lot of our "they"'s are referring e.g. to a command-line option, or
"their" referring to "their arguments", as in the argv vector of a
program.
Since the examples are already few in number, it is not an
overwhelming amount of work to remove third-person singular pronouns
from the necessary locations. Perhaps if there were more examples
then such a conversion would be too difficult and we would want to
use a more mechanical replacement with singular "they".
My general approach (as specified in this v2) is:
1. Use singular "they" over "he" or "she" and other variants.
2. If you don't want to write "they", then avoid third-person
singular pronouns.
Your approach focuses only on item 2, giving this recommendation:
* Avoid third-person singular pronouns.
I think your change to CodingGuidelines is a bit verbose to get to
that point, and makes it difficult to understand one goal is to
avoid gendered pronouns, which I think reduces the chance that a
new contributor would discover and understand that recommendation.
A semantically similar addition would be:
Avoid gendered pronouns such as "he/him" and "she/her". If
necessary, alter your sentence structure to use singular "you"
to refer to the reader or plural "they" to refer to multiple
actors.
The skepticism about this being needed at all isn't an opinion I hold
about software documentation in general, but about software in Git's
problem space specifically.
A change that says "don't use 'he' and/or 'she' unnecessarily" is
important to encode as a project guideline so we can stop having
discussions about their use whenever they are introduced in a patch.
There is value in having this decision encoded, and the important
thing from my standpoint is that we explicitly avoid gendered pronouns
and can simply point contributors to that decision if we ever notice
one being introduced. That reduces friction the same way that we
decide where curly braces should be placed after an "if" statement.
My preference continues to be singular "they" because it is an easy
way to adapt natural sentence structures into an inclusive language.
But if we decide that this grammar is too difficult for some readers
to understand (due to English as a secondary language or other
reasons to be more strict to older language patterns), then avoiding
gendered pronouns entirely would satisfy my goals in this series.
Thanks,
-Stolee
From: Felipe Contreras <hidden> Date: 2021-06-11 20:39:00
Derrick Stolee wrote:
On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:
quoted
The skepticism about this being needed at all isn't an opinion I hold
about software documentation in general, but about software in Git's
problem space specifically.
A change that says "don't use 'he' and/or 'she' unnecessarily" is
important to encode as a project guideline so we can stop having
discussions about their use whenever they are introduced in a patch.
That has historically never been a problem.
And there's no need to make it a problem.
There is value in having this decision encoded,
But such decision has not been made.
And more importantly: there's absolutely no need to tie your correction
patches to a change in the guideline.
--
Felipe Contreras
Hi,
On 07/06/21 23.57, Derrick Stolee via GitGitGadget wrote:
This patch series officially adopts singular "they" as a contributor
guideline; see Patch 4 for the change to the guidelines and the reasoning
for the change. Before modifying the guidelines, documentation and comments
are updated to not use gendered pronouns, which provides examples of how to
use it.
Sorry for late into this debate, because I'm still on recovering from
fever a week ago (I still have headache and prefer eating less).
Honestly I'm against this patchset. There are concerns from ESL learners
(myself included) which have been taught that `they` MUST be used as
plural pronoun.
As an alternative while still keeping singular constructs, why don't we
use gender neutral pronoun "it"?
--
An old man doll... just what I always wanted! - Clara
Singular "they" works the same as singular "you". For example:
...means that _you are_ completely satisfied...
Singular "you" had a similar backlash in the 1660s as singular "they"
is having in this thread, but singular "you" has lasted (and we use
"thou" only to signify someone using old-timey language).
Oh weird... the big debate with you always was that we have no plural
version of it to use when referring to a group of people, and it was
plural all along, but is still used when referring to only one person.
On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:
quoted
On Thu, Jun 10 2021, brian m. carlson wrote:
...
quoted
quoted
In many cases, saying less is better, I agree. If we don't need to
refer to a human being, then we don't need to consider any pronouns for
that human being. If we communicate things more simply with fewer
words, then that's clearly better overall for everyone involved.
Nobody's reading documentation for pleasure, after all.
I do think that the recommendation that we refer to an anonymous user in
a gender-neutral way still stands, though. Sometimes we will need to
refer to the user or another human actor and that will be the most
natural way to express the idea, so we should use gender-neutral
language to do so.
So roughly here, I'm in favor of both approaches.
When do we need or even prefer to refer to a user like that?
I haven't seen an example in our documentation that's actually better
off because we're talking about things as if two "people" we need to
invent pronouns for are interacting.
Can anyone name one that'll stand up under scrutiny, i.e. once we can
look at it and see if we couldn't phrase it better by avoiding the issue
this series tries to address with a regex search-replacement?
The diffstat of this series is only:
12 files changed, 22 insertions(+), 15 deletions(-)
I've looked at all of them and I can't see one that wouldn't be better
if the relevant text was changed similarly to what I've suggested
upthread.
That's why I don't think this proposal is useful. If we accept this
series we're going to be left with an active recommendation for a
pattern that's already almost nonexistent in our documentation.
Perhaps that's because we're doing it 98% right already and aren't using
"he" or "she" but "they" or "their". The multiple ways you can use
"they" or "their" in the English language makes that hard to grep for. A
lot of our "they"'s are referring e.g. to a command-line option, or
"their" referring to "their arguments", as in the argv vector of a
program.
Since the examples are already few in number, it is not an
overwhelming amount of work to remove third-person singular pronouns
from the necessary locations. Perhaps if there were more examples
then such a conversion would be too difficult and we would want to
use a more mechanical replacement with singular "they".
My general approach (as specified in this v2) is:
1. Use singular "they" over "he" or "she" and other variants.
2. If you don't want to write "they", then avoid third-person
singular pronouns.
Your approach focuses only on item 2, giving this recommendation:
* Avoid third-person singular pronouns.
I think your change to CodingGuidelines is a bit verbose to get to
that point, [...]
It is, because I'm not trying to get to that point at all, and I haven't
been convinced by your proposed series that we need to. I think it's
implicitly covered more generally applicable advice.
and makes it difficult to understand one goal is to
avoid gendered pronouns, which I think reduces the chance that a
new contributor would discover and understand that recommendation.
I think a new contributor is going to be confused by your proposed
modification to the CodingGuidelines because it doesn't activtely tell
you how to do things in the common case, but just that you should avoid
this one obscure edge case.
I'm not saying my hastily written alternative is perfect, but it is a
start at providing some much more general advice that would also have
the effect of bypassing the issue you're concerned about, would it not?
A semantically similar addition would be:
Avoid gendered pronouns such as "he/him" and "she/her". If
necessary, alter your sentence structure to use singular "you"
to refer to the reader or plural "they" to refer to multiple
actors.
Or, if we just fix these existing occurrences as a one-off there'll be
no existing examples of it in-tree, and as people tend to imitate
existing documentation they're unlikely to introduce new
occurrences.
Even before any discussion of an explicit recommendation the number of
occurrences is tiny compared to the volume of documentation we have.
If and when Felipe's [off-list ref]
is applied how small is the diff you'll still have rebased on top of
that?
There's a cost/benefit trade-off between noting something in
CodingGuidelines, meaning that all contributors going forward will have
to read it and understand it, and just fixing a rare issue as a one-off.
I've provided examples of e.g. binutils, C library etc. documentation
that covers similar problem spaces, I'm fairly sure most/all of that
documentation was written in a way that satisfies your criteria without
the need for any specific advice on this point.
quoted
The skepticism about this being needed at all isn't an opinion I hold
about software documentation in general, but about software in Git's
problem space specifically.
A change that says "don't use 'he' and/or 'she' unnecessarily" is
important to encode as a project guideline so we can stop having
discussions about their use whenever they are introduced in a patch.
There is value in having this decision encoded, and the important
thing from my standpoint is that we explicitly avoid gendered pronouns
and can simply point contributors to that decision if we ever notice
one being introduced. That reduces friction the same way that we
decide where curly braces should be placed after an "if" statement.
I'd probably agree with you if this was anything as common in our
documentation as missing {} if/else braces are in our code.
Due to the relative rarity of the documentation issue you're fixing I
can't think of a comparison other than: There's probably also plenty of
generic issues in our code that if fixed, would result in a diffstat
similar to your "12 files changed, 22 insertions(+), 15
deletions(-)".
Assuming your series and Felipe's overlaps (I haven't tried rebasing it
myself) a "9 files changed, 13 insertions(+), 14 deletions(-)" would be
deducted from that.
It doesn't follow that an issue of that rarity belongs in the
CodingGuidelines. Maybe there are still convincing reasons to include
them, I just don't think you've provided any.
It seems to me that any future proposed addition of an elaborate example
where we're gendering the command-line utility or the UID of some OS
user can be changed in a way that satisfies your criteria because it's
overly verbose and imprecise.
My preference continues to be singular "they" because it is an easy
way to adapt natural sentence structures into an inclusive language.
But if we decide that this grammar is too difficult for some readers
to understand (due to English as a secondary language or other
reasons to be more strict to older language patterns), then avoiding
gendered pronouns entirely would satisfy my goals in this series.
Wouldn't it also satisfy your goals to re-roll on top of
[off-list ref] and more generally
look at the leftover hunks as noted in my
[off-list ref]?
From: Robert Karszniewicz <hidden> Date: 2021-06-14 22:10:40
On Thu, Jun 10, 2021 at 10:18:11AM +0200, Johannes Schindelin wrote:
Hi Emily,
On Tue, 8 Jun 2021, Emily Shaffer wrote:
quoted
There is value in intentionally defaulting to "she/her", especially in
settings where women are underrepresented. It can be a nice way to shake
the foundations of unconscious bias in the reader's head. See
https://www.askamanager.org/2011/07/why-i-refer-to-everyone-as-she.html
as an example.
I am glad you brought this up.
It is all too easy for male readers such as myself to not even notice how
effortless it is to read text that includes you, whether by the pronoun
"he" or by avoiding any gendered pronoun altogether.
All the more surprising that the same male readers (again, I will include
myself as it still happens to me, despite all the work I embarked on to
become more conscious of my own biases) will stumble over sentences where
a female pronoun "excludes" them.
And the first reaction, funnily enough, is rarely "Oh, _that_ is how I
make half of the population feel all the time!". Instead it is more like
"How dare they exclude me"?
Funnily enough, I was also in such a situation, and as I explained in
another email in this thread, I /didn't even notice until the very end/,
at which I didn't mind at all, but made a joke about it and the answer
implied that I'm some kind of sexist, which was deeply insulting to me.
Funny side note: this is precisely what happened recently in Germany,
where a law was proposed, and in contrast to common practices (which
dictates to use the "generic male form", i.e. "he/him", as the German
language does not have a singular "they"), it used the "generic female"
instead. I bet you can imagine the indignant backlash from male
politicians...
Right, that's because there is no "generic femininum", it is a feminist
invention that didn't quite catch on, and not without reason. It is a
solution looking to create problems.
(I live in Germany) I've listened to how real people talk "on the
streets" and my experience is that they use the generic masculinum,
whether the speaker is male or female. Pretty much the only place I see
people gender their speech is on TV and in academia. And, "funnily
enough", they do so heavily inconsistently, as that is impossible to do
consistently, if the point is to actually convey information and not
neuro-linguistic programming.
The reason why the generic masculinum is the default is that in our
minds it is a no-op, and that's not because there is some kind of
conspiracy against non-males, but because nobody actually cares about
sex, because it is a completely irrelevant detail. The only way I can
see why someone would even notice the sex, is that he actually cares
about the sex.
However, if you use the female form, the brain will stumble. Not because
the listener is angry because females should not be spoken to or about,
but because it trips the brain's pattern recognition. Isn't it "funny"
how we listen up when a female is mentioned, but nobody cares when the
male is mentioned?
So if the male politicians backlashed on using a "generic femininum",
they were very right to do so; males have to share their gender with
everyone, females have their own exclusive gender. One might even dare
to assert that males do not actually have their own gender at all in the
first place.
Cheers,
Robert Karszniewicz
From: Felipe Contreras via GitGitGadget <hidden> Date: 2021-06-15 14:11:36
From: Felipe Contreras <redacted>
We generally avoid specifying the gender of our users in order to be
more inclusive, but sometimes a few slip by due to habit.
Since by doing a little bit of rewording we can avoid this irrelevant
detail, let's do so.
Inspired-by: Derrick Stolee [off-list ref]
Helped-by: Ævar Arnfjörð Bjarmason [off-list ref]
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: Derrick Stolee <redacted>
---
commit.c | 2 +-
config.h | 4 ++--
date.c | 2 +-
pathspec.h | 2 +-
strbuf.h | 4 ++--
wt-status.c | 2 +-
6 files changed, 8 insertions(+), 8 deletions(-)
From: Felipe Contreras via GitGitGadget <hidden> Date: 2021-06-15 14:11:37
From: Felipe Contreras <redacted>
Using gendered pronouns for an anonymous person applies a gender where
none is known and further excludes readers who do not use gendered
pronouns. Avoid such examples in the documentation by using "they" or
passive voice to avoid the need for a pronoun.
Inspired-by: Derrick Stolee [off-list ref]
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: Derrick Stolee <redacted>
---
Documentation/SubmittingPatches | 5 ++---
Documentation/git-push.txt | 4 ++--
Documentation/user-manual.txt | 2 +-
3 files changed, 5 insertions(+), 6 deletions(-)
@@ -373,9 +373,8 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the- reviewer and means that she is completely satisfied that the patch- is ready for application. It is usually offered only after a- detailed review.+ reviewers themselves when they are completely satisfied with the+ patch after a detailed analysis. . `Tested-by:` is used to indicate that the person applied the patch and found it to have the desired effect.
@@ -244,8 +244,8 @@ Imagine that you have to rebase what you have already published. You will have to bypass the "must fast-forward" rule in order to replace the history you originally published with the rebased history. If somebody else built on top of your original history while you are-rebasing, the tip of the branch at the remote may advance with her-commit, and blindly pushing with `--force` will lose her work.+rebasing, the tip of the branch at the remote may advance with their+commit, and blindly pushing with `--force` will lose their work. + This option allows you to say that you expect the history you are updating is what you rebased and want to replace. If the remote ref
@@ -2792,7 +2792,7 @@ A fast-forward looks something like this: In some cases it is possible that the new head will *not* actually be a descendant of the old head. For example, the developer may have-realized she made a serious mistake, and decided to backtrack,+realized a serious mistake was made and decided to backtrack, resulting in a situation like: ................................................
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-15 14:11:39
From: Derrick Stolee <redacted>
These typos were found while searching the codebase for gendered
pronouns. In the case of t9300-fast-import.sh, remove a confusing
comment that is unnecessary to the understanding of the test.
Signed-off-by: Derrick Stolee <redacted>
---
config.c | 2 +-
t/t9300-fast-import.sh | 1 -
2 files changed, 1 insertion(+), 2 deletions(-)
@@ -1538,7 +1538,6 @@ test_expect_success 'O: comments are all skipped' 'commitrefs/heads/O1# -- ignore all of this textcommitter$GIT_COMMITTER_NAME<$GIT_COMMITTER_EMAIL>$GIT_COMMITTER_DATE-# $GIT_COMMITTER_NAME has inserted here for his benefit.data<<COMMITdirtydirectorycopyCOMMIT
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-15 14:11:39
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time.
To make our documentation more inclusive, add recommendations to the
CodingGuidelines document. We can refer to this section when a
contributor submits a patch with a gendered pronoun and these
recommendations apply. The examples can assist in producing a new patch
with adjusted language.
As noted in the guidelines, removing an example person can make the
writing clearer and more concise. Other techniques such as singular
"you" and plural "they" are widely accepted ways to adjust the noun and
avoid gendered pronouns. Finally, an author can resort to singluar
"they" if absolutely necessary, but this can be difficult for readers
who learned English in a way that dictated "they" as always plural.
If we refer to a specific person, then using a gendered pronoun is
appropriate. There can also be other cases where it is inappropriate for
us to update the existing examples within the Git codebase, such as:
* 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 avoid using pronouns.
* 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.
* Literal email messages in Documentation/howto/ should not be edited
for grammatical concerns such as this, unless we update the entire
document to fit the standard documentation format. If such an effort is
taken on, then the authorship would change and no longer refer to the
exact mail message.
* External projects consumed in contrib/ should not deviate solely for
style reasons. Recommended edits should be contributed to those
projects directly.
Other cases within the Git project were cleaned up by the previous
changes.
Co-authored-by: Junio C Hamano [off-list ref]
Signed-off-by: Derrick Stolee <redacted>
---
Documentation/CodingGuidelines | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
@@ -551,6 +551,34 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file).+ In order to ensure the documentation is inclusive, avoid assuming+ that an unspecified example person is male or female, and think+ twice before using "he", "him", "she", or "her". Here are some+ tips to avoid use of gendered pronouns:++ - Removing the example person might make the sentence more+ clear and efficient. Instead of saying "The programmer+ chooses between X and Y as she sees fit", it is clearer to+ say "Valid choices are X and Y".++ - If you need to talk about an example person, then try using+ second-person to allow the reader to be that example. For+ example, "If you want X to happen, you'd pass option Y",+ instead of "If the user wants X to happen, she'd ...").+ Alternatively, replace the single example with more than one+ person and use plural "they", such as "Interested readers+ can read 'git log -p README' to learn the history in their+ ample spare time" instead of "an interested reader" learning+ in "his" spare time).++ - If you absolutely need to refer to an example person that is+ third-person singluar, you may resort to "singular they" (e.g.+ "A contributor asks their upstream to pull from them"). Note+ that this sounds ungrammatical and unnatural to those who+ learned English as a second language in some parts of the+ world, so should be avoided unless the earlier techniques+ fail to improve the sentence.+ Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions.
From: Derrick Stolee via GitGitGadget <hidden> Date: 2021-06-15 14:11:41
In another topic, I claimed [1] that singular "they" was better than
"he/she" for gender neutrality.
[1]
https://lore.kernel.org/git/44d937a0-e876-e185-f409-a4fd61eae580@gmail.com/
Based on the discussion in earlier versions of this series (and Felipe's
submission [2]), this version makes the official recommendation to avoid
gendered pronouns. Several examples are now listed in CodingGuidelines to
assist contributors to improve their sentences in the process of removing
gendered pronouns.
[2]
https://lore.kernel.org/git/20210611202819.47077-1-felipe.contreras@gmail.com/
Here, I took Felipe's two patches, with edits, as well as a fixed patch 3
(removed an unnecessary comment that had a typo) and a replaced patch 4.
Patch 4 is listed as co-authored-by Junio, but does not have his sign-off.
Junio: please add your sign-off if this is an appropriate edit of your
recommended examples. Otherwise, I can attempt a rewrite.
Thanks, -Stolee
Derrick Stolee (2):
*: fix typos
CodingGuidelines: recommend singular they
Felipe Contreras (2):
doc: avoid using the gender of other people
comments: avoid using the gender of our users
Documentation/CodingGuidelines | 28 ++++++++++++++++++++++++++++
Documentation/SubmittingPatches | 5 ++---
Documentation/git-push.txt | 4 ++--
Documentation/user-manual.txt | 2 +-
commit.c | 2 +-
config.c | 2 +-
config.h | 4 ++--
date.c | 2 +-
pathspec.h | 2 +-
strbuf.h | 4 ++--
t/t9300-fast-import.sh | 1 -
wt-status.c | 2 +-
12 files changed, 42 insertions(+), 16 deletions(-)
base-commit: c09b6306c6ca275ed9d0348a8c8014b2ff723cfb
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-975%2Fderrickstolee%2Fthey-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-975/derrickstolee/they-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/975
Range-diff vs v2:
1: fb7a7573782a ! 1: 5b942776bb0a Documentation: use singular they when appropriate
@@
## Metadata ##
-Author: Derrick Stolee [off-list ref]
+Author: Felipe Contreras [off-list ref]
## Commit message ##
- Documentation: use singular they when appropriate
+ doc: avoid using the gender of other people
- 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.
+ Using gendered pronouns for an anonymous person applies a gender where
+ none is known and further excludes readers who do not use gendered
+ pronouns. Avoid such examples in the documentation by using "they" or
+ passive voice to avoid the need for a pronoun.
- Replace these uses with "they/them" to ensure that these documentation
- examples apply to all potential users without exception.
-
- Helped-by: Richard Kerry [off-list ref]
- Helped-by: Junio C Hamano [off-list ref]
+ Inspired-by: Derrick Stolee [off-list ref]
+ Signed-off-by: Felipe Contreras [off-list ref]
Signed-off-by: Derrick Stolee [off-list ref]
## Documentation/SubmittingPatches ##
@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:
- the patch attempts to fix.
. `Acked-by:` says that the person who is more familiar with the area
the patch attempts to modify liked the patch.
--. `Reviewed-by:`, unlike the other tags, can only be offered by the
+ . `Reviewed-by:`, unlike the other tags, can only be offered by the
- reviewer and means that she is completely satisfied that the patch
- is ready for application. It is usually offered only after a
- detailed review.
-+. `Reviewed-by:`, unlike the other tags, can only be offered by a
-+ reviewer when they are completely satisfied with the patch. It is
-+ offered only after reviews by reviewers who are known to be experts
-+ in the affected area by the community members.
++ reviewers themselves when they are completely satisfied with the
++ patch after a detailed analysis.
. `Tested-by:` is used to indicate that the person applied the patch
and found it to have the desired effect.
@@ Documentation/user-manual.txt: A fast-forward looks something like this:
In some cases it is possible that the new head will *not* actually be
a descendant of the old head. For example, the developer may have
-realized she made a serious mistake, and decided to backtrack,
-+realized they made a serious mistake, and decided to backtrack,
++realized a serious mistake was made and decided to backtrack,
resulting in a situation like:
................................................
2: f611603718ab ! 2: 57d8486ab7c8 *: use singular they in comments
@@
## Metadata ##
-Author: Derrick Stolee [off-list ref]
+Author: Felipe Contreras [off-list ref]
## Commit message ##
- *: use singular they in comments
+ comments: avoid using the gender of our users
- Several comments in our code refer to an anonymous user with "he/him" or
- "she/her" pronouns, and the choice between the two is arbitrary.
+ We generally avoid specifying the gender of our users in order to be
+ more inclusive, but sometimes a few slip by due to habit.
- Replace these uses with "they/them" which universally includes all
- potential readers.
+ Since by doing a little bit of rewording we can avoid this irrelevant
+ detail, let's do so.
- Helped-by: Felipe Contreras [off-list ref]
+ Inspired-by: Derrick Stolee [off-list ref]
+ Helped-by: Ævar Arnfjörð Bjarmason [off-list ref]
+ Signed-off-by: Felipe Contreras [off-list ref]
Signed-off-by: Derrick Stolee [off-list ref]
## commit.c ##
@@ commit.c: static void handle_signed_tag(struct commit *parent, struct commit_ext
## config.h ##
@@ config.h: void git_configset_init(struct config_set *cs);
+ /**
* Parses the file and adds the variable-value pairs to the `config_set`,
* dies if there is an error in parsing the file. Returns 0 on success, or
- * -1 if the file does not exist or is inaccessible. The user has to decide
+- * -1 if the file does not exist or is inaccessible. The user has to decide
- * if he wants to free the incomplete configset or continue using it when
-+ * if they want to free the incomplete configset or continue using it when
++ * -1 if the file does not exist or is inaccessible. The caller decides
++ * whether to free the incomplete configset or continue using it when
* the function returns -1.
*/
int git_configset_add_file(struct config_set *cs, const char *filename);
@@ date.c: int parse_expiry_date(const char *date, timestamp_t *timestamp)
* We take over "now" here, which usually translates
* to the current timestamp. This is because the user
- * really means to expire everything she has done in
-+ * really means to expire everything they have done in
++ * really means to expire everything that was done in
* the past, and by definition reflogs are the record
* of the past, and there is nothing from the future
* to be kept.
@@ pathspec.h: struct pathspec {
* A similar process is applied when a new pathspec magic is added. The designer
* lifts the GUARD_PATHSPEC restriction in the functions that support the new
- * magic. At the same time (s)he has to make sure this new feature will be
-+ * magic. At the same time they have to make sure this new feature will be
++ * magic while at the same time making sure this new feature will be
* caught at parse_pathspec() in commands that cannot handle the new magic in
* some cases. grepping parse_pathspec() should help.
*/
## strbuf.h ##
@@ strbuf.h: const char *strbuf_join_argv(struct strbuf *buf, int argc,
+ * placeholder is unknown, then the percent sign is copied, too.
*
* In order to facilitate caching and to make it possible to give
- * parameters to the callback, `strbuf_expand()` passes a context pointer,
+- * parameters to the callback, `strbuf_expand()` passes a context pointer,
- * which can be used by the programmer of the callback as she sees fit.
-+ * which can be used by the programmer of the callback as they see fit.
++ * parameters to the callback, `strbuf_expand()` passes a context
++ * pointer with any kind of data.
*/
typedef size_t (*expand_fn_t) (struct strbuf *sb,
const char *placeholder,
@@ wt-status.c: static void wt_status_collect_changes_index(struct wt_status *s)
* changed submodule SHA-1s when comparing index and HEAD, no
* matter what is configured. Otherwise the user won't be
- * shown any submodules she manually added (and which are
-+ * shown any submodules they manually added (and which are
++ * shown any submodules manually added (and which are
* staged to be committed), which would be really confusing.
*/
handle_ignore_submodules_arg(&rev.diffopt, "dirty");
3: feecbd7a0c6e ! 3: 6f6fa1b9466e *: fix typos
@@ Commit message
*: fix typos
These typos were found while searching the codebase for gendered
- pronouns.
+ pronouns. In the case of t9300-fast-import.sh, remove a confusing
+ comment that is unnecessary to the understanding of the test.
Signed-off-by: Derrick Stolee [off-list ref]
@@ t/t9300-fast-import.sh: test_expect_success 'O: comments are all skipped' '
# -- ignore all of this text
committer $GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL> $GIT_COMMITTER_DATE
- # $GIT_COMMITTER_NAME has inserted here for his benefit.
-+ # $GIT_COMMITTER_NAME has inserted here for this benefit.
data <<COMMIT
dirty directory copy
COMMIT
4: 065e2fdeb151 < -: ------------ CodingGuidelines: recommend singular they
-: ------------ > 4: f06092a9053e CodingGuidelines: recommend singular they
--
gitgitgadget
On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote:
[...]
* References to fictional people with clear genders (e.g. Alice and
Bob).
I mentioned in the feedback on an earlier round[1] that aside from your
goals, these would be better rewritten. I've just submitted a series[2]
to do that; perhaps you can look at that and see if you think there's
still a reason to explicitly exclude these.
* Sample text used in test cases (e.g t3702, t6432).
FWIW that's another unaddressed-by-you question I had in an earlier
round[1].
@@ -551,6 +551,34 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file).+ In order to ensure the documentation is inclusive, avoid assuming+ that an unspecified example person is male or female, and think+ twice before using "he", "him", "she", or "her". Here are some+ tips to avoid use of gendered pronouns:++ - Removing the example person might make the sentence more+ clear and efficient. Instead of saying "The programmer+ chooses between X and Y as she sees fit", it is clearer to+ say "Valid choices are X and Y".++ - If you need to talk about an example person, then try using+ second-person to allow the reader to be that example. For+ example, "If you want X to happen, you'd pass option Y",+ instead of "If the user wants X to happen, she'd ...").+ Alternatively, replace the single example with more than one+ person and use plural "they", such as "Interested readers+ can read 'git log -p README' to learn the history in their+ ample spare time" instead of "an interested reader" learning+ in "his" spare time).++ - If you absolutely need to refer to an example person that is+ third-person singluar, you may resort to "singular they" (e.g.+ "A contributor asks their upstream to pull from them"). Note+ that this sounds ungrammatical and unnatural to those who+ learned English as a second language in some parts of the+ world, so should be avoided unless the earlier techniques+ fail to improve the sentence.+ Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions.
In the same E-Mail that you copied the original version of this new text
from[3], Junio suggested, mostly in reference to my [4]:
I tend to agree that Ævar's approach to guidelines is to cover more
general readability tips, not necessarily focusing on avoidance of
gendered pronouns, let alone encouraging of "singular they". I
think that is overall a good approach to advance the "let's make
sure the document is easier to read by everybody" goal than
mechanical "he and she are bad, let's use they" does.
To be fair he does go on to say something that suggests to also go for a
version of your approach here, i.e. that we still have some reference to
"they" over "he" and "she". I've got no problem with that, but he also
said (comments in [] are mine):
If we were to go that route [(of copying Junio's version from [3])],
I think the first two points [(i.e. the first two bullet-points you
incorporated above)] (which I didn't give enough thought to be even
called a "draft") should be replaced with something like what Ævar
wrote in his write-up.
So your version here does none of that, and we're mostly left with advice
about what not to do in the demonstrably obscure edge case of gendered
language in our docs (as evidenced by the diffstat).
But we aren't helping contributors much with with positive examples of
what to do unrelated to that, i.e. for documentation they could actually
be expected to write or maintain. I.e. general prose guidelines for
common the cases of discussing command-line options, program behavior,
user interaction etc.
Anyway, I don't think I'll be participating in this topic any
further. It seems you're not interested in pursuing alternate approaches
that accomplish your goals, or in responding to specific point-by-point
feedback on your series from myself and others.
I do think it would be a much better and respectful use of everyone's
time on this ML if you clearly stated your unwillingness to deviate from
the narrow approach in the initial version of a series you're
submitting.
Maybe I'm wrong and you are willing to incorporate something like more
general prose that accomplishes most or all of your narrow goals as a
side-effect, but right now it seems you're not.
If we're going to make some use of the collective time spent by a lot of
people on-list reading the documentation you're suggesting to change,
that'll have to be done in a series that would textually conflict with
yours (and which Junio would need to clean up), or in something that
would build on top of your more narrowly focused work.
1. https://lore.kernel.org/git/875yyp4fun.fsf@evledraar.gmail.com/
2. https://lore.kernel.org/git/cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com/
3. https://lore.kernel.org/git/xmqqr1h51dce.fsf@gitster.g/
4. https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/
From: Felipe Contreras <hidden> Date: 2021-06-15 17:09:01
Derrick Stolee via GitGitGadget wrote:
From: Derrick Stolee <redacted>
Technical writing seeks to convey information with minimal friction. One
way that a reader can experience friction is if they encounter a
description of "a user" that is later simplified using a gendered
pronoun. If the reader does not consider that pronoun to apply to them,
then they can experience cognitive dissonance that removes focus from
the information.
The gender of the reader is never specified.
The documentation doesn't mention users in that way, only third-person
developers, reviewers, etc.
The code mentions third-person users.
Never the reader.
So it's not true the reader can experience cognitive dissonance when the
gender ofthe reader is specified, because we never do that.
Do you have an actual example?
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-06-15 17:26:39
Ævar Arnfjörð Bjarmason wrote:
On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote:
Anyway, I don't think I'll be participating in this topic any
further. It seems you're not interested in pursuing alternate approaches
that accomplish your goals, or in responding to specific point-by-point
feedback on your series from myself and others.
I do think it would be a much better and respectful use of everyone's
time on this ML if you clearly stated your unwillingness to deviate from
the narrow approach in the initial version of a series you're
submitting.
For what it's worth I also feel that's the case. 95% of my suggestions
for improvement were completely ignored, and it's only when the
maintainer threatened to merge my competing series, that I started
receiving responses.
I don't believe critical feedback has been welcomed, I don't believe my
time as a reviewer was respected, and mostly it felt like talking
to a wall.
I find it ironic that a patch series that boasts of promoting inclusion
and diversity completely ignores the most important diversity the
project should care about:
Diversity of thought.
While claiming to be trying to avoid hypothetical people from feeling
excluded, it actively excluded the opinions of actual people.
--
Felipe Contreras