All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH 0/4] Use singular "they" when appropriate
@ 2021-06-07 16:57 Derrick Stolee via GitGitGadget
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
                   ` (6 more replies)
  0 siblings, 7 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-07 16:57 UTC (permalink / raw)
  To: git; +Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
@ 2021-06-07 16:57 ` Derrick Stolee via GitGitGadget
  2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
                     ` (3 more replies)
  2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
                   ` (5 subsequent siblings)
  6 siblings, 4 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-07 16:57 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <dstolee@microsoft.com>
---
 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(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 55287d72e0ef..b518d3157f70 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a953c7c38790..2f25aa3a291b 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -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
diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt
index bbf040eda8af..e9ad0b4ff8e0 100644
--- a/Documentation/howto/using-signed-tag-in-pull-request.txt
+++ b/Documentation/howto/using-signed-tag-in-pull-request.txt
@@ -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
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index f9e54b867417..4fe9be117c4a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -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:
 
 ................................................
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH 2/4] *: use singular they in comments
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
@ 2021-06-07 16:57 ` Derrick Stolee via GitGitGadget
  2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
                     ` (2 more replies)
  2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
                   ` (4 subsequent siblings)
  6 siblings, 3 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-07 16:57 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <dstolee@microsoft.com>
---
 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(-)

diff --git a/commit.c b/commit.c
index 8ea55a447fa9..35e93abce6ae 100644
--- a/commit.c
+++ b/commit.c
@@ -1178,7 +1178,7 @@ static void handle_signed_tag(struct commit *parent, struct commit_extra_header
 	/*
 	 * 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
 	 * later auditor may have it while auditing, so let's not run
 	 * verify-signed-buffer here for now...
 	 *
diff --git a/config.h b/config.h
index 9038538ffdcb..7107b41a8933 100644
--- a/config.h
+++ b/config.h
@@ -451,7 +451,7 @@ 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
- * 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
  * the function returns -1.
  */
 int git_configset_add_file(struct config_set *cs, const char *filename);
diff --git a/contrib/hooks/multimail/git_multimail.py b/contrib/hooks/multimail/git_multimail.py
index f563be82fc7e..5932a3354f26 100755
--- a/contrib/hooks/multimail/git_multimail.py
+++ b/contrib/hooks/multimail/git_multimail.py
@@ -3219,7 +3219,7 @@ 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()
@@ -3361,7 +3361,7 @@ 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
diff --git a/date.c b/date.c
index f9ea807b3a9f..2da0f80b9bfa 100644
--- a/date.c
+++ b/date.c
@@ -908,7 +908,7 @@ 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
 		 * the past, and by definition reflogs are the record
 		 * of the past, and there is nothing from the future
 		 * to be kept.
diff --git a/pathspec.h b/pathspec.h
index fceebb876f7a..6e84099bea22 100644
--- a/pathspec.h
+++ b/pathspec.h
@@ -108,7 +108,7 @@ 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
  * caught at parse_pathspec() in commands that cannot handle the new magic in
  * some cases. grepping parse_pathspec() should help.
  */
diff --git a/strbuf.h b/strbuf.h
index 223ee2094af8..b543e354f0ed 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -338,7 +338,7 @@ const char *strbuf_join_argv(struct strbuf *buf, int argc,
  *
  * In order to facilitate caching and to make it possible to give
  * 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.
  */
 typedef size_t (*expand_fn_t) (struct strbuf *sb,
 			       const char *placeholder,
diff --git a/wt-status.c b/wt-status.c
index 42b673571696..bd7ef3e4fd02 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -639,7 +639,7 @@ static void wt_status_collect_changes_index(struct wt_status *s)
 		 * mode by passing a command line option we do not ignore any
 		 * 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
 		 * staged to be committed), which would be really confusing.
 		 */
 		handle_ignore_submodules_arg(&rev.diffopt, "dirty");
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH 3/4] *: fix typos
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
  2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
@ 2021-06-07 16:57 ` Derrick Stolee via GitGitGadget
  2021-06-08 17:37   ` Emily Shaffer
  2021-06-10  8:36   ` Johannes Schindelin
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
                   ` (3 subsequent siblings)
  6 siblings, 2 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-07 16:57 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

These typos were found while searching the codebase for gendered
pronouns.

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 config.c               | 2 +-
 t/t9300-fast-import.sh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/config.c b/config.c
index f9c400ad3062..7bb96f8f7124 100644
--- a/config.c
+++ b/config.c
@@ -2837,7 +2837,7 @@ static void maybe_remove_section(struct config_store_data *store,
 	begin = store->parsed[i].begin;
 
 	/*
-	 * Next, make sure that we are removing he last key(s) in the section,
+	 * Next, make sure that we are removing the last key(s) in the section,
 	 * and that there are no comments that are possibly about the current
 	 * section.
 	 */
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index 5c47ac4465cb..7039b5c6028d 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' '
 	commit refs/heads/O1
 	# -- 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
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
                   ` (2 preceding siblings ...)
  2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
@ 2021-06-07 16:57 ` Derrick Stolee via GitGitGadget
  2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
                     ` (5 more replies)
  2021-06-07 20:10 ` [PATCH 0/4] Use singular "they" when appropriate Felipe Contreras
                   ` (2 subsequent siblings)
  6 siblings, 6 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-07 16:57 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <dstolee@microsoft.com>
---
 Documentation/CodingGuidelines | 5 +++++
 1 file changed, 5 insertions(+)

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

^ permalink raw reply related	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
@ 2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
  2021-06-07 17:32     ` Derrick Stolee
  2021-06-10  7:44     ` Johannes Schindelin
  2021-06-07 21:36   ` Felipe Contreras
                     ` (2 subsequent siblings)
  3 siblings, 2 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-07 17:09 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee


On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:

> From: Derrick Stolee <dstolee@microsoft.com>
>
> 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 <dstolee@microsoft.com>

I think this is mostly an improvement, however:

>  .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------

This is a quote from a mail of Junio's[1] (date and all). I don't think
it makes sense to copyedit that after the fact without at least editing
the header that indicates that it's a verbatim reproduction.

1. https://lore.kernel.org/git/7vehuyosaa.fsf@alter.siamese.dyndns.org/

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 2/4] *: use singular they in comments
  2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
@ 2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
  2021-06-07 17:20     ` Derrick Stolee
  2021-06-10  8:20     ` Johannes Schindelin
  2021-06-07 19:02   ` Junio C Hamano
  2021-06-08 17:36   ` Emily Shaffer
  2 siblings, 2 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-07 17:12 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee


On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:

> From: Derrick Stolee <dstolee@microsoft.com>
>
> 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 <dstolee@microsoft.com>
> ---
>  commit.c                                 | 2 +-
>  config.h                                 | 2 +-
>  contrib/hooks/multimail/git_multimail.py | 4 ++--

We should not change upstream projects we pull in like that, see
README.Git in that directory +
https://github.com/git-multimail/git-multimail.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 2/4] *: use singular they in comments
  2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
@ 2021-06-07 17:20     ` Derrick Stolee
  2021-06-10  8:20     ` Johannes Schindelin
  1 sibling, 0 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-07 17:20 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

On 6/7/2021 1:12 PM, Ævar Arnfjörð Bjarmason wrote:
> 
> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
> 
>> From: Derrick Stolee <dstolee@microsoft.com>
>>
>> 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 <dstolee@microsoft.com>
>> ---
>>  commit.c                                 | 2 +-
>>  config.h                                 | 2 +-
>>  contrib/hooks/multimail/git_multimail.py | 4 ++--
> 
> We should not change upstream projects we pull in like that, see
> README.Git in that directory +
> https://github.com/git-multimail/git-multimail.

Whoops. Thanks. I wasn't looking carefully enough
at the path.

-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
@ 2021-06-07 17:32     ` Derrick Stolee
  2021-06-07 17:42       ` Andrei Rybak
  2021-06-07 18:21       ` Ævar Arnfjörð Bjarmason
  2021-06-10  7:44     ` Johannes Schindelin
  1 sibling, 2 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-07 17:32 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
> 
> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
> 
>> From: Derrick Stolee <dstolee@microsoft.com>
>>
>> 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 <dstolee@microsoft.com>
> 
> I think this is mostly an improvement, however:
> 
>>  .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------
> 
> This is a quote from a mail of Junio's[1] (date and all). I don't think
> it makes sense to copyedit that after the fact without at least editing
> the header that indicates that it's a verbatim reproduction.
> 
> 1. https://lore.kernel.org/git/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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 17:32     ` Derrick Stolee
@ 2021-06-07 17:42       ` Andrei Rybak
  2021-06-07 18:21       ` Ævar Arnfjörð Bjarmason
  1 sibling, 0 replies; 124+ messages in thread
From: Andrei Rybak @ 2021-06-07 17:42 UTC (permalink / raw)
  To: Derrick Stolee, Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

On 07/06/2021 19:32, Derrick Stolee wrote:
> On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
>>
>> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
>>
>>> From: Derrick Stolee <dstolee@microsoft.com>
>>>
>>> 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 <dstolee@microsoft.com>
>>
>> I think this is mostly an improvement, however:
>>
>>>   .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------
>>
>> This is a quote from a mail of Junio's[1] (date and all). I don't think
>> it makes sense to copyedit that after the fact without at least editing
>> the header that indicates that it's a verbatim reproduction.
>>
>> 1. https://lore.kernel.org/git/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.



^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 17:32     ` Derrick Stolee
  2021-06-07 17:42       ` Andrei Rybak
@ 2021-06-07 18:21       ` Ævar Arnfjörð Bjarmason
  1 sibling, 0 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-07 18:21 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee


On Mon, Jun 07 2021, Derrick Stolee wrote:

> On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:
>> 
>> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
>> 
>>> From: Derrick Stolee <dstolee@microsoft.com>
>>>
>>> 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 <dstolee@microsoft.com>
>> 
>> I think this is mostly an improvement, however:
>> 
>>>  .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------
>> 
>> This is a quote from a mail of Junio's[1] (date and all). I don't think
>> it makes sense to copyedit that after the fact without at least editing
>> the header that indicates that it's a verbatim reproduction.
>> 
>> 1. https://lore.kernel.org/git/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

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

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

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

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

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
@ 2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
  2021-06-08  1:47     ` Felipe Contreras
  2021-06-07 18:56   ` Junio C Hamano
                     ` (4 subsequent siblings)
  5 siblings, 1 reply; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-07 18:31 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee


On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:

> From: Derrick Stolee <dstolee@microsoft.com>
> [...]
> 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.

> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index e3af089ecf26..78cd399f7cf5 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -648,3 +648,8 @@ Writing Documentation:
>   inline substituted text+ instead of `monospaced literal text`, and with
>   the former, the part that should not get substituted must be
>   quoted/escaped.
> +
> + When referring to an anonymous user, use singular "they/them" pronouns
> + as opposed to choosing between "he/him" and "she/her". [...]

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/

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
  2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
@ 2021-06-07 18:56   ` Junio C Hamano
  2021-06-07 19:05     ` Derrick Stolee
  2021-06-10  8:39     ` Johannes Schindelin
  2021-06-07 20:00   ` Felipe Contreras
                     ` (3 subsequent siblings)
  5 siblings, 2 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-07 18:56 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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):

The use of "their" here I found going overboard, given that (1) it
is outside the topic of this change, where you are not referring to
a non-specific person, and (2) as Brian's siglines indicate, the
preferred pronouns for the particular person you are referring to is
"he/him or they/them".

> + 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.

Short and sweet.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 2/4] *: use singular they in comments
  2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
  2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
@ 2021-06-07 19:02   ` Junio C Hamano
  2021-06-07 21:44     ` Felipe Contreras
  2021-06-08 17:36   ` Emily Shaffer
  2 siblings, 1 reply; 124+ messages in thread
From: Junio C Hamano @ 2021-06-07 19:02 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

> @@ -1178,7 +1178,7 @@ static void handle_signed_tag(struct commit *parent, struct commit_extra_header
>  	/*
>  	 * 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
>  	 * later auditor may have it while auditing, so let's not run
>  	 * verify-signed-buffer here for now...
>  	 *

This is not wrong per-se, but "the tag being merged" is something I
would have written, as naive non-native English speakers would find
it disturbing and ungrammatical that "the integrator" singular is
matched with "singular" they, which goes opposite from what they
were taught in their foreign language classes [*1*].

Perhaps offer a passive voice as a weaker alternative to the
singular they in the guidelines patch?


[Footnote]

*1* I started writing this paragraph first with a singular subject
    "a naive non-native speaker", found "his or her foreign language
    class" problematic, and worked it around by make the statement
    about plural speakers.  That may qualify as the third option.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 18:56   ` Junio C Hamano
@ 2021-06-07 19:05     ` Derrick Stolee
  2021-06-08  0:05       ` Junio C Hamano
  2021-06-10 21:34       ` brian m. carlson
  2021-06-10  8:39     ` Johannes Schindelin
  1 sibling, 2 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-07 19:05 UTC (permalink / raw)
  To: Junio C Hamano, Derrick Stolee via GitGitGadget
  Cc: git, sandals, jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

On 6/7/2021 2:56 PM, Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> 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):
> 
> The use of "their" here I found going overboard, given that (1) it
> is outside the topic of this change, where you are not referring to
> a non-specific person, and (2) as Brian's siglines indicate, the
> preferred pronouns for the particular person you are referring to is
> "he/him or they/them".

I'll admit that I was trying to be instructive in my commit message
whenever possible, so specifically chose that option among brian's
preferred pronouns. If I misinterpreted the purpose of "he/him or
they/them" then I will absolutely change this instance.

For my part, I did run this message by brian before sending the patch,
to be sure that my use of the quote was appropriate. (Also, I'm
purposefully lower-casing "brian m. carlson" to match chosen email
signatures, but perhaps that is also incorrect?)

Thanks,
-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
  2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
  2021-06-07 18:56   ` Junio C Hamano
@ 2021-06-07 20:00   ` Felipe Contreras
  2021-06-09 18:29     ` Phillip Susi
  2021-06-07 20:20   ` Robert Karszniewicz
                     ` (2 subsequent siblings)
  5 siblings, 1 reply; 124+ messages in thread
From: Felipe Contreras @ 2021-06-07 20:00 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> 
> 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.

This is linguistic prescription [3]:

  Linguistic prescription, or prescriptive grammar, is the attempt to
  establish rules defining preferred or correct usage of language.

You can't eat your cake and have it too.

Cheers.

[1] https://www.atlasobscura.com/articles/the-linguistic-turf-wars-over-the-singular-they
[2] https://en.wikipedia.org/wiki/Nucular
[3] https://en.wikipedia.org/wiki/Linguistic_prescription

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 0/4] Use singular "they" when appropriate
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
                   ` (3 preceding siblings ...)
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
@ 2021-06-07 20:10 ` Felipe Contreras
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
  2021-06-12  4:40 ` [PATCH 0/4] Use singular "they" when appropriate Bagas Sanjaya
  6 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-07 20:10 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> 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/

And in that same thread I argued otherwise:

https://lore.kernel.org/git/60aaa09aebce4_454920811@natae.notmuch/

> 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/

To which I also argued against:

https://lore.kernel.org/git/60aafecba4279_8eb820875@natae.notmuch/

> 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.

> I would appreciate ACKs in support on patch 4.

A firm NAK from me.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
                     ` (2 preceding siblings ...)
  2021-06-07 20:00   ` Felipe Contreras
@ 2021-06-07 20:20   ` Robert Karszniewicz
  2021-06-07 22:18     ` Felipe Contreras
  2021-06-08  7:10   ` Jeff King
  2021-06-08 17:39   ` Emily Shaffer
  5 siblings, 1 reply; 124+ messages in thread
From: Robert Karszniewicz @ 2021-06-07 20:20 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee, Robert Karszniewicz

On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> 
> 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
  2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
@ 2021-06-07 21:36   ` Felipe Contreras
  2021-06-09 18:47     ` Phillip Susi
  2021-06-08  1:18   ` Junio C Hamano
  2021-06-08 17:33   ` Emily Shaffer
  3 siblings, 1 reply; 124+ messages in thread
From: Felipe Contreras @ 2021-06-07 21:36 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -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.

> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 2/4] *: use singular they in comments
  2021-06-07 19:02   ` Junio C Hamano
@ 2021-06-07 21:44     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-07 21:44 UTC (permalink / raw)
  To: Junio C Hamano, Derrick Stolee via GitGitGadget
  Cc: git, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > @@ -1178,7 +1178,7 @@ static void handle_signed_tag(struct commit *parent, struct commit_extra_header
> >  	/*
> >  	 * 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
> >  	 * later auditor may have it while auditing, so let's not run
> >  	 * verify-signed-buffer here for now...
> >  	 *
> 
> This is not wrong per-se, but "the tag being merged" is something I
> would have written, as naive non-native English speakers would find
> it disturbing and ungrammatical that "the integrator" singular is
> matched with "singular" they, which goes opposite from what they
> were taught in their foreign language classes [*1*].

It's not just non-native English speakers. According to linguists the
singular "they" only makes sense when the antecedent is plural (comes
from a pool of people), in this case "the integrator" is semantically
singular.

58% of the Usage Panel of the American Heritage Dictionary would
disagree with this usage [1].

> Perhaps offer a passive voice as a weaker alternative to the
> singular they in the guidelines patch?

Yes, "of the tag being merged" does read correctly to me, unlike the
version above.

Cheers.

[1] https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 20:20   ` Robert Karszniewicz
@ 2021-06-07 22:18     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-07 22:18 UTC (permalink / raw)
  To: Robert Karszniewicz, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee, Robert Karszniewicz

Robert Karszniewicz wrote:
> On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
> > From: Derrick Stolee <dstolee@microsoft.com>
> > 
> > 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.

> > 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 19:05     ` Derrick Stolee
@ 2021-06-08  0:05       ` Junio C Hamano
  2021-06-10 21:34       ` brian m. carlson
  1 sibling, 0 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-08  0:05 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Derrick Stolee via GitGitGadget, git, sandals, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

Derrick Stolee <stolee@gmail.com> writes:

> I'll admit that I was trying to be instructive in my commit message
> whenever possible, so specifically chose that option among brian's
> preferred pronouns. If I misinterpreted the purpose of "he/him or
> they/them" then I will absolutely change this instance.
>
> For my part, I did run this message by brian before sending the patch,
> to be sure that my use of the quote was appropriate. (Also, I'm
> purposefully lower-casing "brian m. carlson" to match chosen email
> signatures, but perhaps that is also incorrect?)

I upcased out of habit, even I know his preference is all lowercase,
purely by mistake.  This is talking about a particular person and
using the name that particular person wants to be called with, so
honoring that wish is good regardless of how an unspecified person
should be referred to as, and I should have double checked.



^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
  2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
  2021-06-07 21:36   ` Felipe Contreras
@ 2021-06-08  1:18   ` Junio C Hamano
  2021-06-08  8:51     ` Kerry, Richard
  2021-06-08 17:33   ` Emily Shaffer
  3 siblings, 1 reply; 124+ messages in thread
From: Junio C Hamano @ 2021-06-08  1:18 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 55287d72e0ef..b518d3157f70 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -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

All the other changes in this step, including the one that is a
quote of past e-mail sent to the list, didn't sound so awkward and
good, but this one does sound strange for this non-native speaker.

Granted, the use of "she" here is already awkward (in the sense "why
do we assume that the reviewer is of certain gender?"), but "they"
looks ungrammatical on top of that awkwardness.

    `Reviewed-by:`, unlike the other tags, can only be offered by
    reviewers themselves when they are completely satisified with
    the patch.  It is offered only after a detailed review by
    reviewers who are known to be experts in the affected area by
    the community members.

perhaps?

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
@ 2021-06-08  1:47     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-08  1:47 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee

Ævar Arnfjörð Bjarmason wrote:
> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:

> > 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
                     ` (3 preceding siblings ...)
  2021-06-07 20:20   ` Robert Karszniewicz
@ 2021-06-08  7:10   ` Jeff King
  2021-06-08  8:11     ` Felipe Contreras
  2021-06-10 22:06     ` brian m. carlson
  2021-06-08 17:39   ` Emily Shaffer
  5 siblings, 2 replies; 124+ messages in thread
From: Jeff King @ 2021-06-08  7:10 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-08  7:10   ` Jeff King
@ 2021-06-08  8:11     ` Felipe Contreras
  2021-06-09 13:23       ` Derrick Stolee
  2021-06-10 22:06     ` brian m. carlson
  1 sibling, 1 reply; 124+ messages in thread
From: Felipe Contreras @ 2021-06-08  8:11 UTC (permalink / raw)
  To: Jeff King, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee

Jeff King wrote:
> 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.

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:

You should look into a carefully crafted usage note written by a panel
of linguists and writers.

https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they

Not a blog post written by a psychologist for an association actively
criticized by many scolars (Twelve Scholars Respond to the APA’s
Guidance for Treating Men and Boys).

https://quillette.com/2019/02/04/psychologists-respond-to-the-apas-guidance-for-treating-men-and-boys/

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08  1:18   ` Junio C Hamano
@ 2021-06-08  8:51     ` Kerry, Richard
  2021-06-08 23:21       ` Junio C Hamano
  0 siblings, 1 reply; 124+ messages in thread
From: Kerry, Richard @ 2021-06-08  8:51 UTC (permalink / raw)
  To: Junio C Hamano, Derrick Stolee via GitGitGadget
  Cc: git, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee


Or:

    `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.

Sentence one uses singular they to refer to one of a pool of reviewers.  
In the second all items are plural.


Regards,
Richard.

-----Original Message-----
From: Junio C Hamano <gitster@pobox.com> 
Sent: 08 June 2021 02:19
To: Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org; sandals@crustytoothpaste.net; stolee@gmail.com; jrnieder@gmail.com; emilyshaffer@google.com; Derrick Stolee <derrickstolee@github.com>; Derrick Stolee <dstolee@microsoft.com>
Subject: Re: [PATCH 1/4] Documentation: use singular they when appropriate

Caution! External email. Do not open attachments or click links, unless this email comes from a known sender and you know the content is safe.

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/SubmittingPatches 
> b/Documentation/SubmittingPatches index 55287d72e0ef..b518d3157f70 
> 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -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

All the other changes in this step, including the one that is a quote of past e-mail sent to the list, didn't sound so awkward and good, but this one does sound strange for this non-native speaker.

Granted, the use of "she" here is already awkward (in the sense "why do we assume that the reviewer is of certain gender?"), but "they"
looks ungrammatical on top of that awkwardness.

    `Reviewed-by:`, unlike the other tags, can only be offered by
    reviewers themselves when they are completely satisified with
    the patch.  It is offered only after a detailed review by
    reviewers who are known to be experts in the affected area by
    the community members.

perhaps?


^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
                     ` (2 preceding siblings ...)
  2021-06-08  1:18   ` Junio C Hamano
@ 2021-06-08 17:33   ` Emily Shaffer
  2021-06-08 18:03     ` Felipe Contreras
                       ` (2 more replies)
  3 siblings, 3 replies; 124+ messages in thread
From: Emily Shaffer @ 2021-06-08 17:33 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee

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 <emilyshaffer@google.com>

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 2/4] *: use singular they in comments
  2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
  2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
  2021-06-07 19:02   ` Junio C Hamano
@ 2021-06-08 17:36   ` Emily Shaffer
  2 siblings, 0 replies; 124+ messages in thread
From: Emily Shaffer @ 2021-06-08 17:36 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee

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 <emilyshaffer@google.com>

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 3/4] *: fix typos
  2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
@ 2021-06-08 17:37   ` Emily Shaffer
  2021-06-10  8:36   ` Johannes Schindelin
  1 sibling, 0 replies; 124+ messages in thread
From: Emily Shaffer @ 2021-06-08 17:37 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee

On Mon, Jun 07, 2021 at 04:57:47PM +0000, Derrick Stolee via GitGitGadget wrote:
> 
> 
> These typos were found while searching the codebase for gendered
> pronouns.

Around snickering to myself trying to figure out alternate meanings
where these aren't typos,

Reviewed-by: Emily Shaffer <emilyshaffer@google.com>

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
                     ` (4 preceding siblings ...)
  2021-06-08  7:10   ` Jeff King
@ 2021-06-08 17:39   ` Emily Shaffer
  2021-06-09  4:44     ` Junio C Hamano
  5 siblings, 1 reply; 124+ messages in thread
From: Emily Shaffer @ 2021-06-08 17:39 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee

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 <dstolee@microsoft.com>

Well said.
Acked-by: Emily Shaffer <emilyshaffer@google.com>

> ---
>  Documentation/CodingGuidelines | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index e3af089ecf26..78cd399f7cf5 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -648,3 +648,8 @@ Writing Documentation:
>   inline substituted text+ instead of `monospaced literal text`, and with
>   the former, the part that should not get substituted must be
>   quoted/escaped.
> +
> + When referring to an anonymous user, use singular "they/them" pronouns
> + as opposed to choosing between "he/him" and "she/her". Do not use more
> + complicated constructs such as "he or she" or "s/he". This recommendation
> + also applies to code comments and commit messages.
> -- 
> gitgitgadget

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08 17:33   ` Emily Shaffer
@ 2021-06-08 18:03     ` Felipe Contreras
  2021-06-09 13:44       ` Kerry, Richard
  2021-06-09  4:48     ` Junio C Hamano
  2021-06-10  8:18     ` Johannes Schindelin
  2 siblings, 1 reply; 124+ messages in thread
From: Felipe Contreras @ 2021-06-08 18:03 UTC (permalink / raw)
  To: Emily Shaffer, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee

Emily Shaffer wrote:
> On Mon, Jun 07, 2021 at 04:57:45PM +0000, Derrick Stolee via GitGitGadget wrote:
> > 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08  8:51     ` Kerry, Richard
@ 2021-06-08 23:21       ` Junio C Hamano
  2021-06-09 13:13         ` Derrick Stolee
  2021-06-10  3:11         ` Junio C Hamano
  0 siblings, 2 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-08 23:21 UTC (permalink / raw)
  To: Kerry, Richard
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

"Kerry, Richard" <richard.kerry@atos.net> writes:

> Or:
>
>     `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.
>
> Sentence one uses singular they to refer to one of a pool of reviewers.  
> In the second all items are plural.

Yeah, it reads well, I'd think.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-08 17:39   ` Emily Shaffer
@ 2021-06-09  4:44     ` Junio C Hamano
  2021-06-09 13:27       ` Derrick Stolee
  0 siblings, 1 reply; 124+ messages in thread
From: Junio C Hamano @ 2021-06-09  4:44 UTC (permalink / raw)
  To: Emily Shaffer
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	Derrick Stolee, Derrick Stolee

Emily Shaffer <emilyshaffer@google.com> writes:

> On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
>> 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 <dstolee@microsoft.com>
>
> Well said.
> Acked-by: Emily Shaffer <emilyshaffer@google.com>
>
>> ---
>>  Documentation/CodingGuidelines | 5 +++++
>>  1 file changed, 5 insertions(+)
>> 
>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
>> index e3af089ecf26..78cd399f7cf5 100644
>> --- a/Documentation/CodingGuidelines
>> +++ b/Documentation/CodingGuidelines
>> @@ -648,3 +648,8 @@ Writing Documentation:
>>   inline substituted text+ instead of `monospaced literal text`, and with
>>   the former, the part that should not get substituted must be
>>   quoted/escaped.
>> +
>> + When referring to an anonymous user, use singular "they/them" pronouns
>> + as opposed to choosing between "he/him" and "she/her". Do not use more
>> + complicated constructs such as "he or she" or "s/he". This recommendation
>> + also applies to code comments and commit messages.

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

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

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

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08 17:33   ` Emily Shaffer
  2021-06-08 18:03     ` Felipe Contreras
@ 2021-06-09  4:48     ` Junio C Hamano
  2021-06-10  8:18     ` Johannes Schindelin
  2 siblings, 0 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-09  4:48 UTC (permalink / raw)
  To: Emily Shaffer
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	Derrick Stolee, Derrick Stolee

Emily Shaffer <emilyshaffer@google.com> writes:

> 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.

Heh, I used to refer to a hypothethical user in my writing as a
female and a male on alternate days (Tuesdays and Thursdays were
male day).  It quickly got confusing when I had to compose my reply
on an even day to a response to my earlier message that was written
on an odd day, and I had to abandon the practice ;-)

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08 23:21       ` Junio C Hamano
@ 2021-06-09 13:13         ` Derrick Stolee
  2021-06-10  3:11         ` Junio C Hamano
  1 sibling, 0 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-09 13:13 UTC (permalink / raw)
  To: Junio C Hamano, Kerry, Richard
  Cc: Derrick Stolee via GitGitGadget, git, sandals, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

On 6/8/2021 7:21 PM, Junio C Hamano wrote:
> "Kerry, Richard" <richard.kerry@atos.net> writes:
> 
>> Or:
>>
>>     `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.
>>
>> Sentence one uses singular they to refer to one of a pool of reviewers.  
>> In the second all items are plural.
> 
> Yeah, it reads well, I'd think.
 
I agree. Thanks!

-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-08  8:11     ` Felipe Contreras
@ 2021-06-09 13:23       ` Derrick Stolee
  2021-06-09 15:20         ` Felipe Contreras
  0 siblings, 1 reply; 124+ messages in thread
From: Derrick Stolee @ 2021-06-09 13:23 UTC (permalink / raw)
  To: Felipe Contreras, Jeff King, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

On 6/8/2021 4:11 AM, Felipe Contreras wrote:
> Jeff King wrote:
>> 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.
> 
> 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-09  4:44     ` Junio C Hamano
@ 2021-06-09 13:27       ` Derrick Stolee
  0 siblings, 0 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-09 13:27 UTC (permalink / raw)
  To: Junio C Hamano, Emily Shaffer
  Cc: Derrick Stolee via GitGitGadget, git, sandals, jrnieder,
	Derrick Stolee, Derrick Stolee

On 6/9/2021 12:44 AM, Junio C Hamano wrote:
> Emily Shaffer <emilyshaffer@google.com> writes:
> 
>> On Mon, Jun 07, 2021 at 04:57:48PM +0000, Derrick Stolee via GitGitGadget wrote:
...
>>> +
>>> + When referring to an anonymous user, use singular "they/them" pronouns
>>> + as opposed to choosing between "he/him" and "she/her". Do not use more
>>> + complicated constructs such as "he or she" or "s/he". This recommendation
>>> + also applies to code comments and commit messages.
> 
> I am not sure if this "here is the rule and you will follow it" is
> helpful without hinting what the rule is trying to achieve.  It is
> more so that the four-bullet-point list in the proposed log message
> that says when not to blindly apply the singular they rule will not
> be seen by intended readers---we who are reviewing this change in
> the patch form may understand and embrace it, but the readers have
> less than we have to go with.

I went to far trying to be brief in CodingGuidelines in favor of a
long commit message (that can be blamed). But you're right. "Start
with why" is a good strategy.
 
> Perhaps start the whole paragraph a bit differently, like this?
> 
>     Refer to an anonymous user in a gender neutral way.  Use
>     singular "they/them" pronouns as opposed to ...
> 
> The added single phase will be a sufficient clue to readers that
> this is about inclusion, and will tell readers that singular they is
> not a hard and fast rule but one of the suggested ways to achieve
> that goal.  To be even clearer, we may probably want to add "One way
> to do so is to" before the second sentence.

That's a good idea.

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

Thanks,
-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08 18:03     ` Felipe Contreras
@ 2021-06-09 13:44       ` Kerry, Richard
  2021-06-09 17:44         ` Felipe Contreras
  0 siblings, 1 reply; 124+ messages in thread
From: Kerry, Richard @ 2021-06-09 13:44 UTC (permalink / raw)
  To: Felipe Contreras, Emily Shaffer, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee


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.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
                   ` (4 preceding siblings ...)
  2021-06-07 20:10 ` [PATCH 0/4] Use singular "they" when appropriate Felipe Contreras
@ 2021-06-09 13:54 ` Derrick Stolee via GitGitGadget
  2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
                     ` (5 more replies)
  2021-06-12  4:40 ` [PATCH 0/4] Use singular "they" when appropriate Bagas Sanjaya
  6 siblings, 6 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-09 13:54 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee

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 <richard.kerry@atos.net>
     +    Helped-by: Junio C Hamano <gitster@pobox.com>
          Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
      
       ## 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 <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
     -@@ 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 <felipe.contreras@gmail.com>
          Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
      
       ## 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 <gitster@pobox.com>
          Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
      
       ## 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* [PATCH v2 1/4] Documentation: use singular they when appropriate
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
@ 2021-06-09 13:54   ` Derrick Stolee via GitGitGadget
  2021-06-09 15:33     ` Felipe Contreras
  2021-06-09 13:54   ` [PATCH v2 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
                     ` (4 subsequent siblings)
  5 siblings, 1 reply; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-09 13:54 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <richard.kerry@atos.net>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/SubmittingPatches | 8 ++++----
 Documentation/git-push.txt      | 4 ++--
 Documentation/user-manual.txt   | 2 +-
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 55287d72e0ef..f519a8dfff7c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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.
 
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a953c7c38790..2f25aa3a291b 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -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
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index f9e54b867417..4fe9be117c4a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -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:
 
 ................................................
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH v2 2/4] *: use singular they in comments
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
  2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
@ 2021-06-09 13:54   ` Derrick Stolee via GitGitGadget
  2021-06-09 15:41     ` Felipe Contreras
  2021-06-09 13:54   ` [PATCH v2 3/4] *: fix typos Derrick Stolee via GitGitGadget
                     ` (3 subsequent siblings)
  5 siblings, 1 reply; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-09 13:54 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <felipe.contreras@gmail.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 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(-)

diff --git a/commit.c b/commit.c
index 8ea55a447fa9..143f472c0f24 100644
--- a/commit.c
+++ b/commit.c
@@ -1178,7 +1178,7 @@ static void handle_signed_tag(struct commit *parent, struct commit_extra_header
 	/*
 	 * 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 being merged, while a
 	 * later auditor may have it while auditing, so let's not run
 	 * verify-signed-buffer here for now...
 	 *
diff --git a/config.h b/config.h
index 9038538ffdcb..7107b41a8933 100644
--- a/config.h
+++ b/config.h
@@ -451,7 +451,7 @@ 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
- * 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
  * the function returns -1.
  */
 int git_configset_add_file(struct config_set *cs, const char *filename);
diff --git a/date.c b/date.c
index f9ea807b3a9f..2da0f80b9bfa 100644
--- a/date.c
+++ b/date.c
@@ -908,7 +908,7 @@ 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
 		 * the past, and by definition reflogs are the record
 		 * of the past, and there is nothing from the future
 		 * to be kept.
diff --git a/pathspec.h b/pathspec.h
index fceebb876f7a..6e84099bea22 100644
--- a/pathspec.h
+++ b/pathspec.h
@@ -108,7 +108,7 @@ 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
  * caught at parse_pathspec() in commands that cannot handle the new magic in
  * some cases. grepping parse_pathspec() should help.
  */
diff --git a/strbuf.h b/strbuf.h
index 223ee2094af8..b543e354f0ed 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -338,7 +338,7 @@ const char *strbuf_join_argv(struct strbuf *buf, int argc,
  *
  * In order to facilitate caching and to make it possible to give
  * 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.
  */
 typedef size_t (*expand_fn_t) (struct strbuf *sb,
 			       const char *placeholder,
diff --git a/wt-status.c b/wt-status.c
index 42b673571696..bd7ef3e4fd02 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -639,7 +639,7 @@ static void wt_status_collect_changes_index(struct wt_status *s)
 		 * mode by passing a command line option we do not ignore any
 		 * 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
 		 * staged to be committed), which would be really confusing.
 		 */
 		handle_ignore_submodules_arg(&rev.diffopt, "dirty");
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH v2 3/4] *: fix typos
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
  2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
  2021-06-09 13:54   ` [PATCH v2 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
@ 2021-06-09 13:54   ` Derrick Stolee via GitGitGadget
  2021-06-09 13:54   ` [PATCH v2 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
                     ` (2 subsequent siblings)
  5 siblings, 0 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-09 13:54 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

These typos were found while searching the codebase for gendered
pronouns.

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 config.c               | 2 +-
 t/t9300-fast-import.sh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/config.c b/config.c
index f9c400ad3062..7bb96f8f7124 100644
--- a/config.c
+++ b/config.c
@@ -2837,7 +2837,7 @@ static void maybe_remove_section(struct config_store_data *store,
 	begin = store->parsed[i].begin;
 
 	/*
-	 * Next, make sure that we are removing he last key(s) in the section,
+	 * Next, make sure that we are removing the last key(s) in the section,
 	 * and that there are no comments that are possibly about the current
 	 * section.
 	 */
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index 5c47ac4465cb..7039b5c6028d 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' '
 	commit refs/heads/O1
 	# -- 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
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH v2 4/4] CodingGuidelines: recommend singular they
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
                     ` (2 preceding siblings ...)
  2021-06-09 13:54   ` [PATCH v2 3/4] *: fix typos Derrick Stolee via GitGitGadget
@ 2021-06-09 13:54   ` Derrick Stolee via GitGitGadget
  2021-06-09 15:50     ` Felipe Contreras
  2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
  2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
  5 siblings, 1 reply; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-09 13:54 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/CodingGuidelines | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index e3af089ecf26..c75da9d131cb 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -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.").
-- 
gitgitgadget

^ permalink raw reply related	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-09 13:23       ` Derrick Stolee
@ 2021-06-09 15:20         ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 15:20 UTC (permalink / raw)
  To: Derrick Stolee, Felipe Contreras, Jeff King,
	Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

Derrick Stolee wrote:
> On 6/8/2021 4:11 AM, Felipe Contreras wrote:
> > Jeff King wrote:
> >> 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.
> > 
> > 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.

That was not the question.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH v2 1/4] Documentation: use singular they when appropriate
  2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
@ 2021-06-09 15:33     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 15:33 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> 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.

> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -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.

> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH v2 2/4] *: use singular they in comments
  2021-06-09 13:54   ` [PATCH v2 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
@ 2021-06-09 15:41     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 15:41 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> Replace these uses with "they/them" which universally includes all
> potential readers.

Not me, and others on the mailing list who are being ignored.

I guess only some people are worthy of "inclusion".

> Helped-by: Felipe Contreras <felipe.contreras@gmail.com>
> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
> ---
>  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(-)
> 
> diff --git a/commit.c b/commit.c
> index 8ea55a447fa9..143f472c0f24 100644
> --- a/commit.c
> +++ b/commit.c
> @@ -1178,7 +1178,7 @@ static void handle_signed_tag(struct commit *parent, struct commit_extra_header
>  	/*
>  	 * 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 being merged, while a

This one is OK.

>  	 * later auditor may have it while auditing, so let's not run
>  	 * verify-signed-buffer here for now...
>  	 *
> diff --git a/config.h b/config.h
> index 9038538ffdcb..7107b41a8933 100644
> --- a/config.h
> +++ b/config.h
> @@ -451,7 +451,7 @@ 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
> - * 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

Yet again a semantically singular antecedent.

Doesn't sound grammatically correct to me.

>   * the function returns -1.
>   */
>  int git_configset_add_file(struct config_set *cs, const char *filename);
> diff --git a/date.c b/date.c
> index f9ea807b3a9f..2da0f80b9bfa 100644
> --- a/date.c
> +++ b/date.c
> @@ -908,7 +908,7 @@ 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

Semantically singular antecedent.

>  		 * the past, and by definition reflogs are the record
>  		 * of the past, and there is nothing from the future
>  		 * to be kept.
> diff --git a/pathspec.h b/pathspec.h
> index fceebb876f7a..6e84099bea22 100644
> --- a/pathspec.h
> +++ b/pathspec.h
> @@ -108,7 +108,7 @@ 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

Semantically singular antecedent.

>   * caught at parse_pathspec() in commands that cannot handle the new magic in
>   * some cases. grepping parse_pathspec() should help.
>   */
> diff --git a/strbuf.h b/strbuf.h
> index 223ee2094af8..b543e354f0ed 100644
> --- a/strbuf.h
> +++ b/strbuf.h
> @@ -338,7 +338,7 @@ const char *strbuf_join_argv(struct strbuf *buf, int argc,
>   *
>   * In order to facilitate caching and to make it possible to give
>   * 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.

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.

>   */
>  typedef size_t (*expand_fn_t) (struct strbuf *sb,
>  			       const char *placeholder,
> diff --git a/wt-status.c b/wt-status.c
> index 42b673571696..bd7ef3e4fd02 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -639,7 +639,7 @@ static void wt_status_collect_changes_index(struct wt_status *s)
>  		 * mode by passing a command line option we do not ignore any
>  		 * 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

Semantically singular antecedent.


So only 1 out of 6 was correct.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
                     ` (3 preceding siblings ...)
  2021-06-09 13:54   ` [PATCH v2 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
@ 2021-06-09 15:44   ` Ævar Arnfjörð Bjarmason
  2021-06-09 17:22     ` Felipe Contreras
                       ` (2 more replies)
  2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
  5 siblings, 3 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-09 15:44 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Derrick Stolee


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.
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index e3af089ecf..204935186e 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -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.
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a953c7c387..47d0cdf7cc 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -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.
 +
diff --git a/config.h b/config.h
index 9038538ffd..a2200f3111 100644
--- a/config.h
+++ b/config.h
@@ -450,8 +450,8 @@ 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
- * if he wants 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);
diff --git a/strbuf.h b/strbuf.h
index 223ee2094a..c7c67cfe14 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -337,8 +337,8 @@ 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,
- * which can be used by the programmer of the callback as she sees fit.
+ * parameters to the callback, `strbuf_expand()` passes a
+ * `void *context` to the callback `fn`
  */
 typedef size_t (*expand_fn_t) (struct strbuf *sb,
 			       const char *placeholder,

^ permalink raw reply related	[flat|nested] 124+ messages in thread

* RE: [PATCH v2 4/4] CodingGuidelines: recommend singular they
  2021-06-09 13:54   ` [PATCH v2 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
@ 2021-06-09 15:50     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 15:50 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Derrick Stolee, Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
@ 2021-06-09 17:22     ` Felipe Contreras
  2021-06-10  2:03     ` Junio C Hamano
  2021-06-10 22:32     ` brian m. carlson
  2 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 17:22 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Derrick Stolee

Æ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.

!00% agreed.

> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -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...

I'm a big fan of this succinct approach.

> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -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.

>  the ref without explicitly locking it, and the remote ref is updated
>  only if the "lease" is still valid.
>  +
> diff --git a/config.h b/config.h
> index 9038538ffd..a2200f3111 100644
> --- a/config.h
> +++ b/config.h
> @@ -450,8 +450,8 @@ 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
> - * if he wants 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

Gramatically correct and clear. This is a good change.

>   * the function returns -1.
>   */
>  int git_configset_add_file(struct config_set *cs, const char *filename);
> diff --git a/strbuf.h b/strbuf.h
> index 223ee2094a..c7c67cfe14 100644
> --- a/strbuf.h
> +++ b/strbuf.h
> @@ -337,8 +337,8 @@ 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,
> - * which can be used by the programmer of the callback as she sees fit.
> + * parameters to the callback, `strbuf_expand()` passes a
> + * `void *context` to the callback `fn`

Simple and to the point. +1

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-09 13:44       ` Kerry, Richard
@ 2021-06-09 17:44         ` Felipe Contreras
  2021-06-25 14:30           ` Kerry, Richard
  0 siblings, 1 reply; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 17:44 UTC (permalink / raw)
  To: Kerry, Richard, Felipe Contreras, Emily Shaffer,
	Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 20:00   ` Felipe Contreras
@ 2021-06-09 18:29     ` Phillip Susi
  2021-06-09 20:18       ` Felipe Contreras
  0 siblings, 1 reply; 124+ messages in thread
From: Phillip Susi @ 2021-06-09 18:29 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee


Felipe Contreras <felipe.contreras@gmail.com> writes:

> Derrick Stolee via GitGitGadget wrote:
>> From: Derrick Stolee <dstolee@microsoft.com>
>> 
>> 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.


^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 21:36   ` Felipe Contreras
@ 2021-06-09 18:47     ` Phillip Susi
  2021-06-09 20:26       ` Felipe Contreras
  2021-06-10 18:30       ` Derrick Stolee
  0 siblings, 2 replies; 124+ messages in thread
From: Phillip Susi @ 2021-06-09 18:47 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee


Felipe Contreras <felipe.contreras@gmail.com> writes:

> Derrick Stolee via GitGitGadget wrote:
>> From: Derrick Stolee <dstolee@microsoft.com>
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -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".


^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-09 18:29     ` Phillip Susi
@ 2021-06-09 20:18       ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 20:18 UTC (permalink / raw)
  To: Phillip Susi, Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

Phillip Susi wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > Derrick Stolee via GitGitGadget wrote:
> >> From: Derrick Stolee <dstolee@microsoft.com>
> >> 
> >> 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.

> > 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.

> > 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.

I didn't argue either of those things.

Yes, I did argue that "single they" isn't part of standard English (with
a semantically singular antecedent), that doesn't necessary mean we
shouldn't use it.

And I did argue "nucular" is part of standard English (many people use
it), that doesn't mean we should use it.

Basically whether or not a word is part of "standard English" is
orthogonal to the fact that we should use it. In my view.


Let me be clear on what I do argue: we shouldn't ban perfectly standard
words such as "she" and "he".

Cheers.

[1] https://lore.kernel.org/git/fb7a7573782ae8ba3bc5341d6aaee704af88fdcf.1623246878.git.gitgitgadget@gmail.com/
[2] https://www.lexico.com/en/definition/nucular
[3] https://slate.com/human-interest/2015/02/cute-etymology-and-history-from-sharp-keen-or-shrewd-to-charming-and-attractive.html

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-09 18:47     ` Phillip Susi
@ 2021-06-09 20:26       ` Felipe Contreras
  2021-06-11 15:40         ` Phillip Susi
  2021-06-10 18:30       ` Derrick Stolee
  1 sibling, 1 reply; 124+ messages in thread
From: Felipe Contreras @ 2021-06-09 20:26 UTC (permalink / raw)
  To: Phillip Susi, Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

Phillip Susi wrote:
> 
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > Derrick Stolee via GitGitGadget wrote:
> >> From: Derrick Stolee <dstolee@microsoft.com>
> >> --- a/Documentation/SubmittingPatches
> >> +++ b/Documentation/SubmittingPatches
> >> @@ -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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
  2021-06-09 17:22     ` Felipe Contreras
@ 2021-06-10  2:03     ` Junio C Hamano
  2021-06-10  2:28       ` Junio C Hamano
  2021-06-10  3:30       ` Felipe Contreras
  2021-06-10 22:32     ` brian m. carlson
  2 siblings, 2 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-10  2:03 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> + 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.

Because I still get a funny feeling whenever I see a singular they,
which I was taught to be ungrammatical in my foreign language
classes long time ago, I kind of like this approach better, if we
can pull it off.

I wonder if we can avoid third-person entirely, though.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-10  2:03     ` Junio C Hamano
@ 2021-06-10  2:28       ` Junio C Hamano
  2021-06-10  3:30       ` Felipe Contreras
  1 sibling, 0 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-10  2:28 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

Junio C Hamano <gitster@pobox.com> writes:

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> + 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.
>
> Because I still get a funny feeling whenever I see a singular they,
> which I was taught to be ungrammatical in my foreign language
> classes long time ago, I kind of like this approach better, if we
> can pull it off.
>
> I wonder if we can avoid third-person entirely, though.

Git is primarily a communication medium used among developers, and
when one side is referred to as "you", the other side needs some
pronoun to explain inter-developer interactions.  We could say "you
as the integrator would have to ask my sign-off from me as a
contributor" to avoid third-person, but I suspect that this quickly
becomes just as awkward as using singular they.

I wonder if this makes it more workable:

    When it becomes awkward to stick to this style prefer "you" when
    addressing the the hypothetical user, and "they" in plural when
    you need to talk about a third-party that interacts with "you",
    and possibly "we" when discussing how the program might react to
    the user.

That way, we'd say "You'd ask their sign-off from contributors".

I'd stop here and continue watching from sidelines.

I think the topic tries to solve an issue worth solving, but I
suspect that a solution that requires singular they would not work
as well as a solution that doesn't would, especially for non native
speakers like me.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08 23:21       ` Junio C Hamano
  2021-06-09 13:13         ` Derrick Stolee
@ 2021-06-10  3:11         ` Junio C Hamano
  1 sibling, 0 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-10  3:11 UTC (permalink / raw)
  To: Kerry, Richard
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

Junio C Hamano <gitster@pobox.com> writes:

> "Kerry, Richard" <richard.kerry@atos.net> writes:
>
>> Or:
>>
>>     `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.
>>
>> Sentence one uses singular they to refer to one of a pool of reviewers.  
>> In the second all items are plural.
>
> Yeah, it reads well, I'd think.

Actually, I take half of it back.  The first sentence can talk about
reviewers (not just a single reviewer), which would naturally match
the pronoun "they", which would be even better.  After all, more
people looking at patches is a good thing ;-)

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-10  2:03     ` Junio C Hamano
  2021-06-10  2:28       ` Junio C Hamano
@ 2021-06-10  3:30       ` Felipe Contreras
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-10  3:30 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> 
> > + 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.
> 
> Because I still get a funny feeling whenever I see a singular they,
> which I was taught to be ungrammatical in my foreign language
> classes long time ago, I kind of like this approach better, if we
> can pull it off.

Once again; we non-native English speakers shouldn't forgo our
instincts. Even professional English linguists agree this isn't OK:

  We thank the anonymous reviewer for their helpful comments

https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
  2021-06-07 17:32     ` Derrick Stolee
@ 2021-06-10  7:44     ` Johannes Schindelin
  2021-06-10 14:35       ` Felipe Contreras
  1 sibling, 1 reply; 124+ messages in thread
From: Johannes Schindelin @ 2021-06-10  7:44 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 1147 bytes --]

Hi Ævar,

On Mon, 7 Jun 2021, Ævar Arnfjörð Bjarmason wrote:

> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
>
> >  .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------
>
> This is a quote from a mail of Junio's[1] (date and all). I don't think
> it makes sense to copyedit that after the fact without at least editing
> the header that indicates that it's a verbatim reproduction.
>
> 1. https://lore.kernel.org/git/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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-08 17:33   ` Emily Shaffer
  2021-06-08 18:03     ` Felipe Contreras
  2021-06-09  4:48     ` Junio C Hamano
@ 2021-06-10  8:18     ` Johannes Schindelin
  2021-06-10 14:42       ` Felipe Contreras
  2021-06-14 22:10       ` Robert Karszniewicz
  2 siblings, 2 replies; 124+ messages in thread
From: Johannes Schindelin @ 2021-06-10  8:18 UTC (permalink / raw)
  To: Emily Shaffer
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, Derrick Stolee, Derrick Stolee

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:
>
> > 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 2/4] *: use singular they in comments
  2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
  2021-06-07 17:20     ` Derrick Stolee
@ 2021-06-10  8:20     ` Johannes Schindelin
  1 sibling, 0 replies; 124+ messages in thread
From: Johannes Schindelin @ 2021-06-10  8:20 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 1092 bytes --]

Hi,

On Mon, 7 Jun 2021, Ævar Arnfjörð Bjarmason wrote:

> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:
>
> > From: Derrick Stolee <dstolee@microsoft.com>
> >
> > 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 <dstolee@microsoft.com>
> > ---
> >  commit.c                                 | 2 +-
> >  config.h                                 | 2 +-
> >  contrib/hooks/multimail/git_multimail.py | 4 ++--
>
> We should not change upstream projects we pull in like that, see
> README.Git in that directory +
> https://github.com/git-multimail/git-multimail.

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 3/4] *: fix typos
  2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
  2021-06-08 17:37   ` Emily Shaffer
@ 2021-06-10  8:36   ` Johannes Schindelin
  2021-06-10 19:53     ` Derrick Stolee
  1 sibling, 1 reply; 124+ messages in thread
From: Johannes Schindelin @ 2021-06-10  8:36 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Derrick Stolee, Derrick Stolee

Hi,

On Mon, 7 Jun 2021, Derrick Stolee via GitGitGadget wrote:

> diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
> index 5c47ac4465cb..7039b5c6028d 100755
> --- a/t/t9300-fast-import.sh
> +++ b/t/t9300-fast-import.sh
> @@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' '
>  	commit refs/heads/O1
>  	# -- 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.

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 18:56   ` Junio C Hamano
  2021-06-07 19:05     ` Derrick Stolee
@ 2021-06-10  8:39     ` Johannes Schindelin
  1 sibling, 0 replies; 124+ messages in thread
From: Johannes Schindelin @ 2021-06-10  8:39 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

Hi Junio,

On Tue, 8 Jun 2021, Junio C Hamano wrote:

> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > 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):
>
> The use of "their" here I found going overboard, given that (1) it
> is outside the topic of this change, where you are not referring to
> a non-specific person, and (2) as Brian's siglines indicate, the
> preferred pronouns for the particular person you are referring to is
> "he/him or they/them".

For your record, while I sometimes mention that I use "he/him" to refer to
myself, I promise I will never be offended if you refer to me via
"they/them".

;-)

Ciao,
Dscho

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-10  7:44     ` Johannes Schindelin
@ 2021-06-10 14:35       ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-10 14:35 UTC (permalink / raw)
  To: Johannes Schindelin, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-10  8:18     ` Johannes Schindelin
@ 2021-06-10 14:42       ` Felipe Contreras
  2021-06-14 22:10       ` Robert Karszniewicz
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-10 14:42 UTC (permalink / raw)
  To: Johannes Schindelin, Emily Shaffer
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, Derrick Stolee, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-09 18:47     ` Phillip Susi
  2021-06-09 20:26       ` Felipe Contreras
@ 2021-06-10 18:30       ` Derrick Stolee
  2021-06-11  0:16         ` Junio C Hamano
                           ` (2 more replies)
  1 sibling, 3 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-10 18:30 UTC (permalink / raw)
  To: Phillip Susi, Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

On 6/9/2021 2:47 PM, Phillip Susi wrote:
> 
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
>> Derrick Stolee via GitGitGadget wrote:
>>> From: Derrick Stolee <dstolee@microsoft.com>
>>> --- a/Documentation/SubmittingPatches
>>> +++ b/Documentation/SubmittingPatches
>>> @@ -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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 3/4] *: fix typos
  2021-06-10  8:36   ` Johannes Schindelin
@ 2021-06-10 19:53     ` Derrick Stolee
  2021-06-11  9:55       ` Johannes Schindelin
  0 siblings, 1 reply; 124+ messages in thread
From: Derrick Stolee @ 2021-06-10 19:53 UTC (permalink / raw)
  To: Johannes Schindelin, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

On 6/10/2021 4:36 AM, Johannes Schindelin wrote:
> Hi,
> 
> On Mon, 7 Jun 2021, Derrick Stolee via GitGitGadget wrote:
> 
>> diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
>> index 5c47ac4465cb..7039b5c6028d 100755
>> --- a/t/t9300-fast-import.sh
>> +++ b/t/t9300-fast-import.sh
>> @@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' '
>>  	commit refs/heads/O1
>>  	# -- 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.
> 
> 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-07 19:05     ` Derrick Stolee
  2021-06-08  0:05       ` Junio C Hamano
@ 2021-06-10 21:34       ` brian m. carlson
  1 sibling, 0 replies; 124+ messages in thread
From: brian m. carlson @ 2021-06-10 21:34 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Junio C Hamano, Derrick Stolee via GitGitGadget, git, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 1835 bytes --]

On 2021-06-07 at 19:05:19, Derrick Stolee wrote:
> On 6/7/2021 2:56 PM, Junio C Hamano wrote:
> > "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > 
> >> 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):
> > 
> > The use of "their" here I found going overboard, given that (1) it
> > is outside the topic of this change, where you are not referring to
> > a non-specific person, and (2) as Brian's siglines indicate, the
> > preferred pronouns for the particular person you are referring to is
> > "he/him or they/them".
> 
> I'll admit that I was trying to be instructive in my commit message
> whenever possible, so specifically chose that option among brian's
> preferred pronouns. If I misinterpreted the purpose of "he/him or
> they/them" then I will absolutely change this instance.

The intended meaning is that either is fine, whichever the speaker
prefers.  Most people do use he/him for me, probably because most people
are more comfortable doing that, but either option is equally
acceptable.

> For my part, I did run this message by brian before sending the patch,
> to be sure that my use of the quote was appropriate. (Also, I'm
> purposefully lower-casing "brian m. carlson" to match chosen email
> signatures, but perhaps that is also incorrect?)

Also correct.  I typically lowercase my name, and I prefer it that way.
For legal purposes, at least in the locales which are relevant to me,
case is not considered important, and most legal documents scream my
name in uppercase.  But when I have an option, I prefer lowercase when
that's possible.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-08  7:10   ` Jeff King
  2021-06-08  8:11     ` Felipe Contreras
@ 2021-06-10 22:06     ` brian m. carlson
  2021-06-11 16:11       ` Felipe Contreras
  1 sibling, 1 reply; 124+ messages in thread
From: brian m. carlson @ 2021-06-10 22:06 UTC (permalink / raw)
  To: Jeff King
  Cc: Derrick Stolee via GitGitGadget, git, gitster, stolee, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 3792 bytes --]

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:
> 
> > 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:
> 
> > 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
  2021-06-09 17:22     ` Felipe Contreras
  2021-06-10  2:03     ` Junio C Hamano
@ 2021-06-10 22:32     ` brian m. carlson
  2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
  2 siblings, 1 reply; 124+ messages in thread
From: brian m. carlson @ 2021-06-10 22:32 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, gitster, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 3158 bytes --]

On 2021-06-09 at 15:44:59, Ævar Arnfjörð Bjarmason wrote:
> 
> 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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-10 22:32     ` brian m. carlson
@ 2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
  2021-06-11 16:32         ` Felipe Contreras
  2021-06-11 17:18         ` Derrick Stolee
  0 siblings, 2 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-10 22:58 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Derrick Stolee via GitGitGadget, git, gitster, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee


On Thu, Jun 10 2021, brian m. carlson wrote:

> [[PGP Signed Part:Undecided]]
> On 2021-06-09 at 15:44:59, Ævar Arnfjörð Bjarmason wrote:
>> 
>> 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.
>
> 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.

>> 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.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-10 18:30       ` Derrick Stolee
@ 2021-06-11  0:16         ` Junio C Hamano
  2021-06-11 16:00         ` Felipe Contreras
  2021-06-12 14:02         ` Phillip Susi
  2 siblings, 0 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-11  0:16 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Phillip Susi, Felipe Contreras, Derrick Stolee via GitGitGadget,
	git, sandals, jrnieder, emilyshaffer, Derrick Stolee,
	Derrick Stolee

Derrick Stolee <stolee@gmail.com> writes:

> 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 for references.  [1] was an amusing and illuminating read.

    ... Anyone who said thou and thee was seen as a fool and an
    idiot, or a Quaker, or at least hopelessly out of date.

    Singular you has become normal and unremarkable. Also
    unremarkable are the royal we and, in countries without a
    monarchy, the editorial we: first-person plurals used regularly
    as singulars and nobody calling anyone an idiot and a fool. And
    singular they is well on its way to being normal and
    unremarkable as well.


^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 3/4] *: fix typos
  2021-06-10 19:53     ` Derrick Stolee
@ 2021-06-11  9:55       ` Johannes Schindelin
  0 siblings, 0 replies; 124+ messages in thread
From: Johannes Schindelin @ 2021-06-11  9:55 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

Hi Stolee,

On Thu, 10 Jun 2021, Derrick Stolee wrote:

> On 6/10/2021 4:36 AM, Johannes Schindelin wrote:
> >
> > On Mon, 7 Jun 2021, Derrick Stolee via GitGitGadget wrote:
> >
> >> diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
> >> index 5c47ac4465cb..7039b5c6028d 100755
> >> --- a/t/t9300-fast-import.sh
> >> +++ b/t/t9300-fast-import.sh
> >> @@ -1538,7 +1538,7 @@ test_expect_success 'O: comments are all skipped' '
> >>  	commit refs/heads/O1
> >>  	# -- 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.
> >
> > 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?

D'oh! That's the best solution. Just delete that line.

Thanks,
Dscho

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-09 20:26       ` Felipe Contreras
@ 2021-06-11 15:40         ` Phillip Susi
  2021-06-11 17:03           ` Felipe Contreras
  0 siblings, 1 reply; 124+ messages in thread
From: Phillip Susi @ 2021-06-11 15:40 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee


Felipe Contreras <felipe.contreras@gmail.com> writes:

> 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?


^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-10 18:30       ` Derrick Stolee
  2021-06-11  0:16         ` Junio C Hamano
@ 2021-06-11 16:00         ` Felipe Contreras
  2021-06-12 14:02         ` Phillip Susi
  2 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-11 16:00 UTC (permalink / raw)
  To: Derrick Stolee, Phillip Susi, Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 4/4] CodingGuidelines: recommend singular they
  2021-06-10 22:06     ` brian m. carlson
@ 2021-06-11 16:11       ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-11 16:11 UTC (permalink / raw)
  To: brian m. carlson, Jeff King
  Cc: Derrick Stolee via GitGitGadget, git, gitster, stolee, jrnieder,
	emilyshaffer, Derrick Stolee, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
@ 2021-06-11 16:32         ` Felipe Contreras
  2021-06-11 17:18         ` Derrick Stolee
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-11 16:32 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, brian m. carlson
  Cc: Derrick Stolee via GitGitGadget, git, gitster, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

Æ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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-11 15:40         ` Phillip Susi
@ 2021-06-11 17:03           ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-11 17:03 UTC (permalink / raw)
  To: Phillip Susi, Felipe Contreras
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee

Phillip Susi wrote:
> 
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
  2021-06-11 16:32         ` Felipe Contreras
@ 2021-06-11 17:18         ` Derrick Stolee
  2021-06-11 20:38           ` Felipe Contreras
                             ` (2 more replies)
  1 sibling, 3 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-11 17:18 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, brian m. carlson
  Cc: Derrick Stolee via GitGitGadget, git, gitster, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:
> 
> On Thu, Jun 10 2021, brian m. carlson wrote:
> 
...
>> 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-11 17:18         ` Derrick Stolee
@ 2021-06-11 20:38           ` Felipe Contreras
  2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
  2021-06-14  0:47           ` Junio C Hamano
  2 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-11 20:38 UTC (permalink / raw)
  To: Derrick Stolee, Ævar Arnfjörð Bjarmason, brian m. carlson
  Cc: Derrick Stolee via GitGitGadget, git, gitster, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

Derrick Stolee wrote:
> On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:

> > 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 0/4] Use singular "they" when appropriate
  2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
                   ` (5 preceding siblings ...)
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
@ 2021-06-12  4:40 ` Bagas Sanjaya
  2021-06-12 14:19   ` Phillip Susi
  6 siblings, 1 reply; 124+ messages in thread
From: Bagas Sanjaya @ 2021-06-12  4:40 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-10 18:30       ` Derrick Stolee
  2021-06-11  0:16         ` Junio C Hamano
  2021-06-11 16:00         ` Felipe Contreras
@ 2021-06-12 14:02         ` Phillip Susi
  2 siblings, 0 replies; 124+ messages in thread
From: Phillip Susi @ 2021-06-12 14:02 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Felipe Contreras, Derrick Stolee via GitGitGadget, git, gitster,
	sandals, jrnieder, emilyshaffer, Derrick Stolee, Derrick Stolee


Derrick Stolee <stolee@gmail.com> writes:

> 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.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 0/4] Use singular "they" when appropriate
  2021-06-12  4:40 ` [PATCH 0/4] Use singular "they" when appropriate Bagas Sanjaya
@ 2021-06-12 14:19   ` Phillip Susi
  0 siblings, 0 replies; 124+ messages in thread
From: Phillip Susi @ 2021-06-12 14:19 UTC (permalink / raw)
  To: Bagas Sanjaya
  Cc: Derrick Stolee via GitGitGadget, git, gitster, sandals, stolee,
	jrnieder, emilyshaffer, Derrick Stolee


Bagas Sanjaya <bagasdotme@gmail.com> writes:

> As an alternative while still keeping singular constructs, why don't
> we use gender neutral pronoun "it"?

Because "it" refers to a thing, not a person.  It is dehumanizing.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-11 17:18         ` Derrick Stolee
  2021-06-11 20:38           ` Felipe Contreras
@ 2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
  2021-06-15  6:02             ` Junio C Hamano
  2021-06-14  0:47           ` Junio C Hamano
  2 siblings, 1 reply; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-13  7:17 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: brian m. carlson, Derrick Stolee via GitGitGadget, git, gitster,
	jrnieder, emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee


On Fri, Jun 11 2021, Derrick Stolee wrote:

> On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:
>> 
>> On Thu, Jun 10 2021, brian m. carlson wrote:
>> 
> ...
>>> 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 <20210611202819.47077-1-felipe.contreras@gmail.com>
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.

>> 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
<20210611202819.47077-1-felipe.contreras@gmail.com> and more generally
look at the leftover hunks as noted in my
<87a6nz2fda.fsf@evledraar.gmail.com>?

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-11 17:18         ` Derrick Stolee
  2021-06-11 20:38           ` Felipe Contreras
  2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
@ 2021-06-14  0:47           ` Junio C Hamano
  2 siblings, 0 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-14  0:47 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Ævar Arnfjörð Bjarmason, brian m. carlson,
	Derrick Stolee via GitGitGadget, git, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Derrick Stolee

Derrick Stolee <stolee@gmail.com> writes:

> 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.

Is it fair to say that a concise summary of this discussion so far
is:

 - Avoiding gendered pronous is a good way to ensure inclusive
   documentation.

 - Our documentation does not have too many instances of "gendered
   pronouns" issue, and all of them can be corrected without
   resorting to singular "they" (to which those who learned in some
   parts of the world may not be ready yet), and it results in more
   concise and clearer description anyway.

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.  One thing
that the "let's use they" approach does better is that it brings the
"gender neutral" concern upfront, exactly because "let's make sure
the document is easier to read by everybody" is a superset and does
not have to bother singling out the "gender" as an issue.

It may be easier to move the discussion forward if we (half)
separated the concerns.

Because the "gender neutral" is so out of place relative to the
existing guidelines that focus on ensuring consistency that appear
in the "Writing Documentation" section, it is hard to make it into a
single bullet item among many others.  Perhaps we want to have a new
paragraph between "mixes US and UK English" and "Every user-visible
change" paragraphs.

    In order to ensure the documentation appears to be inclusive,
    avoid assuming that an unspecified "cast" who appears in
    description and examples is male or female, and think twice
    after writing "he", "him", "she", or "her".  Here are some tips
    to avoid use of gendered pronouns:

    - Rethink if your example or description needs to talk about a
      human "cast" in the first place.  Do you need to say "The
      programmer chooses between X and Y as she sees fit", or is it
      sufficient to say "Valid choices are X and Y" to make the
      resulting sentence more concise and clear?

    - If you need to talk about human "cast", think if the role the
      cast plays can be second person (e.g. "If you want X to
      happen, you'd pass option Y", instead of "If the user wants X
      to happen, she'd ..."), or can be more than one person
      (e.g. "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 talk about a human "cast" that is
      third-person singluar, you may resort to "singular they" (e.g.
      "A contributor asks their upstream to pull from them").  Note
      however that this sounds ungrammatical and unnatural to those
      who learned English as a second language in some parts of the
      world.

If we were to go that route, I think the first two points (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.  Also,
I do not mind losing "Note however" from the third point, but in the
name of inclusive documentation, it may not be a bad idea to remind
ourselves.



^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-10  8:18     ` Johannes Schindelin
  2021-06-10 14:42       ` Felipe Contreras
@ 2021-06-14 22:10       ` Robert Karszniewicz
  1 sibling, 0 replies; 124+ messages in thread
From: Robert Karszniewicz @ 2021-06-14 22:10 UTC (permalink / raw)
  To: Johannes Schindelin
  Cc: Emily Shaffer, Derrick Stolee via GitGitGadget, git, gitster,
	sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee,
	Robert Karszniewicz

On Thu, Jun 10, 2021 at 10:18:11AM +0200, Johannes Schindelin wrote:
> 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"?

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
@ 2021-06-15  6:02             ` Junio C Hamano
  2021-06-15 13:36               ` Derrick Stolee
  0 siblings, 1 reply; 124+ messages in thread
From: Junio C Hamano @ 2021-06-15  6:02 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee, brian m. carlson,
	Derrick Stolee via GitGitGadget, git, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Derrick Stolee

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> 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.

I suspect that may be a bit too optimistic.  It is too easy to
discuss interaction among users and introduce pronouns to refer to
them, and when it happens, it is far easier to have a document to
point at and tell them why we want them to rephrase if not how
exactly.  For that reason, I'd prefer to have some word about the
desire to make examples and explanations gender-neutral in the
guidelines.  The mechanics we recommend to achieve the goal does not
have to be specified if we want brevity---that can be learned by
imitating existing practices.

> If and when Felipe's <20210611202819.47077-1-felipe.contreras@gmail.com>
> is applied how small is the diff you'll still have rebased on top of
> that?

I just retried a "competing" merge that got ugly ;-)

Between Derrick's two "singular they" patches (one for comments, the
other for docs) and Felipe's two patches (the same split), they
touch identical base text.  Only the way they neuter the description
is different, and to me the latter feels a bit more ESL friendly.

So, the main things that are missing from Felipe's version that we
may want to build on top before the whole discussion can be
concluded are:

 - Derrick's "typofix" patch, but if I recall correctly it needed a
   fix-up in one of its hunks?

 - Guidelines; you had a more generic readability tips that would
   (incidentally) result in nudging the writers to be more gender
   neutral, which I think is going in the right direction, but I do
   prefer to see an explicit mention of gender-neutrality as one
   bullet item.

Thanks.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-15  6:02             ` Junio C Hamano
@ 2021-06-15 13:36               ` Derrick Stolee
  2021-06-15 17:03                 ` Felipe Contreras
  0 siblings, 1 reply; 124+ messages in thread
From: Derrick Stolee @ 2021-06-15 13:36 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: brian m. carlson, Derrick Stolee via GitGitGadget, git, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

On 6/15/2021 2:02 AM, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> 
>> 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.
> 
> I suspect that may be a bit too optimistic.  It is too easy to
> discuss interaction among users and introduce pronouns to refer to
> them, and when it happens, it is far easier to have a document to
> point at and tell them why we want them to rephrase if not how
> exactly.  For that reason, I'd prefer to have some word about the
> desire to make examples and explanations gender-neutral in the
> guidelines.  The mechanics we recommend to achieve the goal does not
> have to be specified if we want brevity---that can be learned by
> imitating existing practices.

Thanks. This was the whole intention of this series: to land on
a policy that improves our understanding of gendered pronouns
and be able to point to it when the situation arises again, even
if that is a rare occasion.

While my initial recommendation wasn't accepted, I'm glad we are
coming to an agreement.

>> If and when Felipe's <20210611202819.47077-1-felipe.contreras@gmail.com>
>> is applied how small is the diff you'll still have rebased on top of
>> that?
> 
> I just retried a "competing" merge that got ugly ;-)
> 
> Between Derrick's two "singular they" patches (one for comments, the
> other for docs) and Felipe's two patches (the same split), they
> touch identical base text.  Only the way they neuter the description
> is different, and to me the latter feels a bit more ESL friendly.
> 
> So, the main things that are missing from Felipe's version that we
> may want to build on top before the whole discussion can be
> concluded are:
> 
>  - Derrick's "typofix" patch, but if I recall correctly it needed a
>    fix-up in one of its hunks?
> 
>  - Guidelines; you had a more generic readability tips that would
>    (incidentally) result in nudging the writers to be more gender
>    neutral, which I think is going in the right direction, but I do
>    prefer to see an explicit mention of gender-neutrality as one
>    bullet item.

I will send a v3 soon with Felipe's two patches, a fixed typo patch,
and a new set of guidelines.

Thanks,
-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* [PATCH v3 0/4] Avoid gendered pronouns
  2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
                     ` (4 preceding siblings ...)
  2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
@ 2021-06-15 14:11   ` Derrick Stolee via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 1/4] doc: avoid using the gender of other people Felipe Contreras via GitGitGadget
                       ` (3 more replies)
  5 siblings, 4 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-15 14:11 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Phillip Susi, Johannes Schindelin, Bagas Sanjaya, Derrick Stolee

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 <dstolee@microsoft.com>
     +Author: Felipe Contreras <felipe.contreras@gmail.com>
      
       ## 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 <richard.kerry@atos.net>
     -    Helped-by: Junio C Hamano <gitster@pobox.com>
     +    Inspired-by: Derrick Stolee <dstolee@microsoft.com>
     +    Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
          Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
      
       ## 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 <dstolee@microsoft.com>
     +Author: Felipe Contreras <felipe.contreras@gmail.com>
      
       ## 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 <felipe.contreras@gmail.com>
     +    Inspired-by: Derrick Stolee <dstolee@microsoft.com>
     +    Helped-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     +    Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
          Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
      
       ## 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 <dstolee@microsoft.com>
      
     @@ 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* [PATCH v3 1/4] doc: avoid using the gender of other people
  2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
@ 2021-06-15 14:11     ` Felipe Contreras via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 2/4] comments: avoid using the gender of our users Felipe Contreras via GitGitGadget
                       ` (2 subsequent siblings)
  3 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras via GitGitGadget @ 2021-06-15 14:11 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Phillip Susi, Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Felipe Contreras

From: Felipe Contreras <felipe.contreras@gmail.com>

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 <dstolee@microsoft.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/SubmittingPatches | 5 ++---
 Documentation/git-push.txt      | 4 ++--
 Documentation/user-manual.txt   | 2 +-
 3 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 55287d72e0ef..3e215f4d8085 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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.
 
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a953c7c38790..2f25aa3a291b 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -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
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index f9e54b867417..96240598e3f5 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -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:
 
 ................................................
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH v3 2/4] comments: avoid using the gender of our users
  2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 1/4] doc: avoid using the gender of other people Felipe Contreras via GitGitGadget
@ 2021-06-15 14:11     ` Felipe Contreras via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 3/4] *: fix typos Derrick Stolee via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
  3 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras via GitGitGadget @ 2021-06-15 14:11 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Phillip Susi, Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Felipe Contreras

From: Felipe Contreras <felipe.contreras@gmail.com>

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 <dstolee@microsoft.com>
Helped-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 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(-)

diff --git a/commit.c b/commit.c
index 8ea55a447fa9..143f472c0f24 100644
--- a/commit.c
+++ b/commit.c
@@ -1178,7 +1178,7 @@ static void handle_signed_tag(struct commit *parent, struct commit_extra_header
 	/*
 	 * 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 being merged, while a
 	 * later auditor may have it while auditing, so let's not run
 	 * verify-signed-buffer here for now...
 	 *
diff --git a/config.h b/config.h
index 9038538ffdcb..a2200f311156 100644
--- a/config.h
+++ b/config.h
@@ -450,8 +450,8 @@ 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
- * if he wants 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);
diff --git a/date.c b/date.c
index f9ea807b3a9f..c55ea47e96ad 100644
--- a/date.c
+++ b/date.c
@@ -908,7 +908,7 @@ 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 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.
diff --git a/pathspec.h b/pathspec.h
index fceebb876f7a..2341dc990102 100644
--- a/pathspec.h
+++ b/pathspec.h
@@ -108,7 +108,7 @@ 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 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.
  */
diff --git a/strbuf.h b/strbuf.h
index 223ee2094af8..a86dcaaf44d1 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -337,8 +337,8 @@ 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,
- * which can be used by the programmer of the callback as she sees 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,
diff --git a/wt-status.c b/wt-status.c
index 42b673571696..ebc0c0da1a84 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -639,7 +639,7 @@ static void wt_status_collect_changes_index(struct wt_status *s)
 		 * mode by passing a command line option we do not ignore any
 		 * 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 manually added (and which are
 		 * staged to be committed), which would be really confusing.
 		 */
 		handle_ignore_submodules_arg(&rev.diffopt, "dirty");
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH v3 3/4] *: fix typos
  2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 1/4] doc: avoid using the gender of other people Felipe Contreras via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 2/4] comments: avoid using the gender of our users Felipe Contreras via GitGitGadget
@ 2021-06-15 14:11     ` Derrick Stolee via GitGitGadget
  2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
  3 siblings, 0 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-15 14:11 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Phillip Susi, Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <dstolee@microsoft.com>
---
 config.c               | 2 +-
 t/t9300-fast-import.sh | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/config.c b/config.c
index f9c400ad3062..7bb96f8f7124 100644
--- a/config.c
+++ b/config.c
@@ -2837,7 +2837,7 @@ static void maybe_remove_section(struct config_store_data *store,
 	begin = store->parsed[i].begin;
 
 	/*
-	 * Next, make sure that we are removing he last key(s) in the section,
+	 * Next, make sure that we are removing the last key(s) in the section,
 	 * and that there are no comments that are possibly about the current
 	 * section.
 	 */
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index 5c47ac4465cb..7607ef65cb99 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -1538,7 +1538,6 @@ test_expect_success 'O: comments are all skipped' '
 	commit refs/heads/O1
 	# -- ignore all of this text
 	committer $GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL> $GIT_COMMITTER_DATE
-	# $GIT_COMMITTER_NAME has inserted here for his benefit.
 	data <<COMMIT
 	dirty directory copy
 	COMMIT
-- 
gitgitgadget


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
                       ` (2 preceding siblings ...)
  2021-06-15 14:11     ` [PATCH v3 3/4] *: fix typos Derrick Stolee via GitGitGadget
@ 2021-06-15 14:11     ` Derrick Stolee via GitGitGadget
  2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
  2021-06-15 17:08       ` Felipe Contreras
  3 siblings, 2 replies; 124+ messages in thread
From: Derrick Stolee via GitGitGadget @ 2021-06-15 14:11 UTC (permalink / raw)
  To: git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Phillip Susi, Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

From: Derrick Stolee <dstolee@microsoft.com>

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 <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/CodingGuidelines | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index e3af089ecf26..0282f836548a 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -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.
-- 
gitgitgadget

^ permalink raw reply related	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
@ 2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
  2021-06-15 17:26         ` Felipe Contreras
  2021-06-16  2:47         ` Junio C Hamano
  2021-06-15 17:08       ` Felipe Contreras
  1 sibling, 2 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-15 16:19 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Phillip Susi, Johannes Schindelin, Bagas Sanjaya,
	Derrick Stolee, Derrick Stolee


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].

> [...]
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index e3af089ecf26..0282f836548a 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -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/

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v2 0/4] Use singular "they" when appropriate
  2021-06-15 13:36               ` Derrick Stolee
@ 2021-06-15 17:03                 ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-15 17:03 UTC (permalink / raw)
  To: Derrick Stolee, Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: brian m. carlson, Derrick Stolee via GitGitGadget, git, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Derrick Stolee

Derrick Stolee wrote:
> On 6/15/2021 2:02 AM, Junio C Hamano wrote:

> > I just retried a "competing" merge that got ugly ;-)
> > 
> > Between Derrick's two "singular they" patches (one for comments, the
> > other for docs) and Felipe's two patches (the same split), they
> > touch identical base text.  Only the way they neuter the description
> > is different, and to me the latter feels a bit more ESL friendly.
> > 
> > So, the main things that are missing from Felipe's version that we
> > may want to build on top before the whole discussion can be
> > concluded are:
> > 
> >  - Derrick's "typofix" patch, but if I recall correctly it needed a
> >    fix-up in one of its hunks?
> > 
> >  - Guidelines; you had a more generic readability tips that would
> >    (incidentally) result in nudging the writers to be more gender
> >    neutral, which I think is going in the right direction, but I do
> >    prefer to see an explicit mention of gender-neutrality as one
> >    bullet item.
> 
> I will send a v3 soon with Felipe's two patches, a fixed typo patch,
> and a new set of guidelines.

I don't believe it's necessary to tie the guideline with the fixes. The
guideline might be desirable without the fixes (depending what the
guideline says), and the fixes can be applied without the guideline. In
other words: they are orthogonal.

Tying them together only ensures the fixes are going to be unnecessarily
delayed until we find appropriate guideliens (if we ever do).

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
  2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
@ 2021-06-15 17:08       ` Felipe Contreras
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-15 17:08 UTC (permalink / raw)
  To: Derrick Stolee via GitGitGadget, git
  Cc: gitster, sandals, stolee, jrnieder, emilyshaffer,
	Ævar Arnfjörð Bjarmason, Andrei Rybak,
	Felipe Contreras, Robert Karszniewicz, Jeff King, Kerry, Richard,
	Phillip Susi, Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> 
> 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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
@ 2021-06-15 17:26         ` Felipe Contreras
  2021-06-16  2:47         ` Junio C Hamano
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-15 17:26 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Phillip Susi, Johannes Schindelin, Bagas Sanjaya,
	Derrick Stolee, Derrick Stolee

Æ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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
  2021-06-15 17:26         ` Felipe Contreras
@ 2021-06-16  2:47         ` Junio C Hamano
  2021-06-16  5:06           ` Junio C Hamano
  2021-06-17 14:46           ` Felipe Contreras
  1 sibling, 2 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-16  2:47 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote:
> ...
>> + 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.

"singular".

By the way, I do not mind toning down "if you absolutely need to
... resort to" that discourages "singular they".  I just wanted
writers to consider that the language evolves slowly, and if they
think "singular they" is the best vehicle to phrase what they want
to say even after considering that it may sound distracting to
foreigners, I would not stop them.

> 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.

FWIW, I am not happy with this version for that reason, either.

I wonder if replacing the first two bullet points ("Removing" and
"If you need to talk about") above with what was added to the
CodingGuidelines by the "succinct matter-of-factly description" in

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

would be sufficient.

Thanks.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16  2:47         ` Junio C Hamano
@ 2021-06-16  5:06           ` Junio C Hamano
  2021-06-16  9:26             ` Bagas Sanjaya
                               ` (3 more replies)
  2021-06-17 14:46           ` Felipe Contreras
  1 sibling, 4 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-16  5:06 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Junio C Hamano <gitster@pobox.com> writes:

> FWIW, I am not happy with this version for that reason, either.
>
> I wonder if replacing the first two bullet points ("Removing" and
> "If you need to talk about") above with what was added to the
> CodingGuidelines by the "succinct matter-of-factly description" in
>
> https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/
>
> would be sufficient.

So, here is what I plan to queue on top of these four patches to
replace my "not even draft" garbage with what you wrote, with a bit
of copyediting.

Comments?

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 605f924981..476b840d30 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -546,28 +546,43 @@ Writing Documentation:
  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.
+  - Prefer succinctness and matter-of-factly describing functionality
+    in the abstract.  E.g.
+
+     --short:: Emit output in the short-format.
+
+    and avoid 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...
+
+    This practice often eliminates the need to involve human actors in
+    your description, but it is a good practice regardless of the
+    avoidance of gendered pronouns.
+
+  - 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.  E.g.
+
+      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.
+
+  - If you still need to refer to an example person that is
+    third-person singular, you may resort to "singular they" to avoid
+    "he/she/him/her", 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.
 
  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing
-- 
2.32.0-241-g31cd86ad06


^ permalink raw reply related	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16  5:06           ` Junio C Hamano
@ 2021-06-16  9:26             ` Bagas Sanjaya
  2021-06-16 17:44             ` Derrick Stolee
                               ` (2 subsequent siblings)
  3 siblings, 0 replies; 124+ messages in thread
From: Bagas Sanjaya @ 2021-06-16  9:26 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Derrick Stolee, Derrick Stolee

On 16/06/21 12.06, Junio C Hamano wrote:
> +  - If you still need to refer to an example person that is
> +    third-person singular, you may resort to "singular they" to avoid
> +    "he/she/him/her", 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.
>   

I'm also confused and found that using singular they may sound odd. So 
IMO either avoid referring to third-person singular (gendered pronouns) 
or write using plural actors. In the case above it should be 
`Contributors ask their upstream to pull from them, potentially with 
reviews`.

A prime example of rewriting using plural actors is in "doc: avoid using 
the gender of other people" patch [1], which said the diff:

> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 55287d72e0..3e215f4d80 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -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.

I'm OK with using they in plural context, but not as singular they.

[1]: 
https://lore.kernel.org/git/20210611202819.47077-2-felipe.contreras@gmail.com/

-- 
An old man doll... just what I always wanted! - Clara

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16  5:06           ` Junio C Hamano
  2021-06-16  9:26             ` Bagas Sanjaya
@ 2021-06-16 17:44             ` Derrick Stolee
  2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
  2021-06-17 15:12             ` Felipe Contreras
  3 siblings, 0 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-16 17:44 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

On 6/16/2021 1:06 AM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> FWIW, I am not happy with this version for that reason, either.
>>
>> I wonder if replacing the first two bullet points ("Removing" and
>> "If you need to talk about") above with what was added to the
>> CodingGuidelines by the "succinct matter-of-factly description" in
>>
>> https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/
>>
>> would be sufficient.
> 
> So, here is what I plan to queue on top of these four patches to
> replace my "not even draft" garbage with what you wrote, with a bit
> of copyediting.
> 
> Comments?
...
> +  - Prefer succinctness and matter-of-factly describing functionality
> +    in the abstract.  E.g.
> +
> +     --short:: Emit output in the short-format.
> +
> +    and avoid 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...
> +
> +    This practice often eliminates the need to involve human actors in
> +    your description, but it is a good practice regardless of the
> +    avoidance of gendered pronouns.

I wasn't a huge fan of this "example first" approach, but you did
a good job of tying it to the purpose and the rest of the
recommendations.

> +  - 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.  E.g.
> +
> +      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.
> +
> +  - If you still need to refer to an example person that is
> +    third-person singular, you may resort to "singular they" to avoid
> +    "he/she/him/her", 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.

This version looks good to me. It is probably worth adding Ævar in
a Co-authored-by line.

Thanks,
-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16  5:06           ` Junio C Hamano
  2021-06-16  9:26             ` Bagas Sanjaya
  2021-06-16 17:44             ` Derrick Stolee
@ 2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
  2021-06-16 23:22               ` Felipe Contreras
                                 ` (2 more replies)
  2021-06-17 15:12             ` Felipe Contreras
  3 siblings, 3 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-16 19:54 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee


On Wed, Jun 16 2021, Junio C Hamano wrote:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> FWIW, I am not happy with this version for that reason, either.
>>
>> I wonder if replacing the first two bullet points ("Removing" and
>> "If you need to talk about") above with what was added to the
>> CodingGuidelines by the "succinct matter-of-factly description" in
>>
>> https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/
>>
>> would be sufficient.
>
> So, here is what I plan to queue on top of these four patches to
> replace my "not even draft" garbage with what you wrote, with a bit
> of copyediting.
>
> Comments?
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 605f924981..476b840d30 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -546,28 +546,43 @@ Writing Documentation:
>   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.
> +  - Prefer succinctness and matter-of-factly describing functionality
> +    in the abstract.  E.g.
> +
> +     --short:: Emit output in the short-format.
> +
> +    and avoid 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...
> +
> +    This practice often eliminates the need to involve human actors in
> +    your description, but it is a good practice regardless of the
> +    avoidance of gendered pronouns.
> +
> +  - 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.  E.g.
> +
> +      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.
> +
> +  - If you still need to refer to an example person that is
> +    third-person singular, you may resort to "singular they" to avoid
> +    "he/she/him/her", 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.
>  
>   Every user-visible change should be reflected in the documentation.
>   The same general rule as for code applies -- imitate the existing

That mostly-my-draft was hastily a written one-off, perhaps this is
better and a more exhaustive discussion of common cases:

  - Discussing command-line options, and program functionality:

    Prefer succinctness and matter-of-factly describing functionality in
    the abstract.  E.g.

     --short:: Emit output in the short-format.

    Avoid more verbose constructions, such as:

     --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...

  - Addressing the reader:

    Address the reader of the documentation directly with "you",
    e.g. "you can do xyz".

  - Discussing Git, "the command" etc.:

    Use "we" when discussing how the program might react to the user, or
    perhaps "git" or "the command", e.g.:

        we might store the data[...]
        git will emit[...]
        the command will[...]

  - Discussing other users:

    When referring to other users on the same system prefer talking
    about "a user" or "another user". There's usually no reason to
    invent a cast of characters with names, titles and hobbies.

    Your OS's users don't cleanly map onto any particular people, a user
    of git might be having a merge conflict with another person, or an
    automated commit from a cron daemon.

    We prefer the style typical of standard library adn system tooling
    documentation in this and most other cases, you can look at the
    documentation of chmod(2) and other commands, syscalls and libraries
    that deal with UIDs or GIDs for examples.

  - Discussing other systems:

    As with discussing other users, git might interact with other
    systems over the network. In these cases we also avoid a cast of
    characters, preferring to talk about concepts like "fetching data
    from a remote", having a conflict with "diverging histories" etc.

The references to "gendered prounouns" etc. are gone, perhaps there's a
good reason to re-include them, but the point of "isn't that issue
solved by recommending an orthagonal approach?" is one of the many
things Stolee hasn't been addressing in the threads related to this
series.

To me that whole approach is somewhere between a solution in search of a
problem and a "let's fix it and move on". Not something we need
explicitly carry in our CodingGuidelines forever.

The v1 of this series started with decreeing that nobody should be using
gendered language in commit messages. It seems that the discussion I
started that perhaps that was overly pedantic and unfriendly to people
struggling with English won out, so that's gone in recent revisions.

That's left only a handful of examples \b(?:she|he)\b in our docs, we
have outstanding patches to fix those, and draft guidelines (amended
above) to thoroughly lead documentation writers in other directions.

It just seems superfluous to me to insist on enumerating increasingly
obscure and disfavored alternatives to what we suggest as preferred
prose in our documentation. For example, we have around the same order
of magnitude of "one might" in Documentation/, I think we should
probably just fix that and move on, not forever have a guideline against
overly formal or "Shakespearean language" in the guidelines.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
@ 2021-06-16 23:22               ` Felipe Contreras
  2021-06-17  0:09               ` Junio C Hamano
  2021-06-18  0:53               ` brian m. carlson
  2 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-16 23:22 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Junio C Hamano
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Ævar Arnfjörð Bjarmason wrote:

> It just seems superfluous to me to insist on enumerating increasingly
> obscure and disfavored alternatives to what we suggest as preferred
> prose in our documentation. For example, we have around the same order
> of magnitude of "one might" in Documentation/, I think we should
> probably just fix that and move on, not forever have a guideline against
> overly formal or "Shakespearean language" in the guidelines.

I also don't see much point in writing guidelines for something that
doesn't come up often, and hasn't come up in more than 15 years of life
of the project.

Does not smell like an issue.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
  2021-06-16 23:22               ` Felipe Contreras
@ 2021-06-17  0:09               ` Junio C Hamano
  2021-06-17 13:22                 ` Derrick Stolee
                                   ` (2 more replies)
  2021-06-18  0:53               ` brian m. carlson
  2 siblings, 3 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-17  0:09 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

>   - Discussing command-line options, and program functionality:
>
>     Prefer succinctness and matter-of-factly describing functionality in
>     the abstract.  E.g.
>
>      --short:: Emit output in the short-format.
>
>     Avoid more verbose constructions, such as:
>
>      --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...

This applies the most broadly and addresses common readability
issues, which is why I like this part the most.

>   - Addressing the reader:
>   - Discussing Git, "the command" etc.:

I am not sure if these are even worth saying, especially when we do
not explain why we recommend to do so.

>   - Discussing other users:
>
>     When referring to other users on the same system prefer talking
>     about "a user" or "another user". There's usually no reason to
>     invent a cast of characters with names, titles and hobbies.
>
>     Your OS's users don't cleanly map onto any particular people, a user
>     of git might be having a merge conflict with another person, or an
>     automated commit from a cron daemon.
>
>     We prefer the style typical of standard library adn system tooling
>     documentation in this and most other cases, you can look at the
>     documentation of chmod(2) and other commands, syscalls and libraries
>     that deal with UIDs or GIDs for examples.

I cannot exactly put my fingers on where this feeling comes from,
but this part appears to spend many lines to tell me very little.

For example, it is unclear why the second paragraph is there at all.
Sure, some commits may be created by a non people, but how does that
fact affect how I write the documentation?  Writing about such an
activity by non people, what are our recommendations?  The third
paragraph does not do much better.  Unless you have UNIX man pages
handy, chmod(2) may not be very easily accessible.  It feels as if
it wants to encourage descriptions without human actors, without
doing a very good job at explaining to readers why the guideline
does not want to see them in our documentation.

Unlike chmod(2) and getpwnam(3), but more like any dSCM, Git is a
tool to help inter-person communication, and at some point we will
have to talk about contributors asking their upstreams to pull their
work from their repositories.  It won't be like system calls dealing
with pure numbers.  We do not have to give them names like Alice and
Bob, but we do have to refer to repositories of these cast of
characters individually to clearly explain/describe how data flow
among them.

>   - Discussing other systems:
>
>     As with discussing other users, git might interact with other
>     systems over the network. In these cases we also avoid a cast of
>     characters, preferring to talk about concepts like "fetching data
>     from a remote", having a conflict with "diverging histories" etc.

Unlike the above "other users", I have littleproblem with this part.
It however feels funny to warn against use of "cast of characters",
when the first sentence talks about "with other systems", which are
clearly not people.  Even when you are "fetching from a remote", you
are getting the result of work by "other people", so I would not
have separated "other users" and "other systems" in separate
sections.

> The references to "gendered prounouns" etc. are gone, perhaps there's a
> good reason to re-include them, but the point of "isn't that issue
> solved by recommending an orthagonal approach?" is one of the many
> things Stolee hasn't been addressing in the threads related to this
> series.
>
> To me that whole approach is somewhere between a solution in search of a
> problem and a "let's fix it and move on". Not something we need
> explicitly carry in our CodingGuidelines forever.

This I think is the crux of the differences between you two.  I'd
love to hear Derrick's response and eventually see a middle ground
reached.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17  0:09               ` Junio C Hamano
@ 2021-06-17 13:22                 ` Derrick Stolee
  2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
                                     ` (2 more replies)
  2021-06-17 15:23                 ` Felipe Contreras
  2021-06-17 15:58                 ` Ævar Arnfjörð Bjarmason
  2 siblings, 3 replies; 124+ messages in thread
From: Derrick Stolee @ 2021-06-17 13:22 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

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

I disagree that removing gendered pronouns and updating the
guidelines are orthogonal. At minimum, we shouldn't have
guidelines that we do not follow, especially when they are
small in number and we can fix them in a few patches.

The entire point of this series was to reach a decision about
gendered pronouns so we can stop having arguments about them
when they come up. We should just be able to point to "here is
the decision we made" and it's not enough to say "If you go
look at the mailing list archive you can see that we removed
all gendered pronouns so you shouldn't add them again."

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

Thanks,
-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16  2:47         ` Junio C Hamano
  2021-06-16  5:06           ` Junio C Hamano
@ 2021-06-17 14:46           ` Felipe Contreras
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-17 14:46 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> 
> > On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote:

> By the way, I do not mind toning down "if you absolutely need to
> ... resort to" that discourages "singular they".  I just wanted
> writers to consider that the language evolves slowly, and if they
> think "singular they" is the best vehicle to phrase what they want
> to say even after considering that it may sound distracting to
> foreigners,

Once again, it's not just foreigners. Even native speakers who are
professional lingusits see a problem with some usages of singular
"they".

Like mushrooms: not all uses of singular "they" are good.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17 13:22                 ` Derrick Stolee
@ 2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
  2021-06-17 17:06                     ` Felipe Contreras
  2021-06-17 15:25                   ` Felipe Contreras
  2021-06-18  0:26                   ` brian m. carlson
  2 siblings, 1 reply; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-17 14:53 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Junio C Hamano, Derrick Stolee via GitGitGadget, git, sandals,
	jrnieder, emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee


On Thu, Jun 17 2021, Derrick Stolee wrote:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

But I digress.

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

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

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16  5:06           ` Junio C Hamano
                               ` (2 preceding siblings ...)
  2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
@ 2021-06-17 15:12             ` Felipe Contreras
  3 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-17 15:12 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Junio C Hamano wrote:

> -  - 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").

Here is another escape hatch recommended by linguists before attempting
to use singular "they":

 - Use a generic alternative and count on the reader's common sense.
   Instead of saying "she made a mistake", say "a mistake was made".

> -    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.

For the nth time, it's not just foreign speakers:

https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they

> +  - Prefer succinctness and matter-of-factly describing functionality
> +    in the abstract.  E.g.
> +
> +     --short:: Emit output in the short-format.
> +
> +    and avoid 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...
> +
> +    This practice often eliminates the need to involve human actors in
> +    your description, but it is a good practice regardless of the
> +    avoidance of gendered pronouns.
> +
> +  - 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.  E.g.
> +
> +      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.
> +
> +  - If you still need to refer to an example person that is
> +    third-person singular, you may resort to "singular they" to avoid
> +    "he/she/him/her", 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.

These look OK to me, but I wonder why we have writing tips in *coding*
guidelines.

We are not writing a style manual, there's plenty of other tips writers
of documentation, commit messages and comments could use, why are we
only giving tips for gender pronouns?

Why don't we have a section on passive vs. active voice? How about
avoiding zombie nouns? Adjectives and adverbs? That vs. which? Who and
whom?

I don't think there's much value in trying to codify what is a good
sense of style while writing just for one particular non-issue.

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17  0:09               ` Junio C Hamano
  2021-06-17 13:22                 ` Derrick Stolee
@ 2021-06-17 15:23                 ` Felipe Contreras
  2021-06-17 15:58                 ` Ævar Arnfjörð Bjarmason
  2 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-17 15:23 UTC (permalink / raw)
  To: Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> > The references to "gendered prounouns" etc. are gone, perhaps there's a
> > good reason to re-include them, but the point of "isn't that issue
> > solved by recommending an orthagonal approach?" is one of the many
> > things Stolee hasn't been addressing in the threads related to this
> > series.
> >
> > To me that whole approach is somewhere between a solution in search of a
> > problem and a "let's fix it and move on". Not something we need
> > explicitly carry in our CodingGuidelines forever.
> 
> This I think is the crux of the differences between you two.  I'd
> love to hear Derrick's response and eventually see a middle ground
> reached.

A middle ground is not always the best solution. The solution between
punching people you disagree with and tolerance is not punching them a
little bit.

Sometimes one side is just incorrect.

Also, a principle of logic is the burden of proof. Ævar doesn't have to
prove that there's something wrong with Derek's proposal, Derek has the
burden of proof.

Why do we need a writing style lesson for one particular issue (that has
never really been an issue) in CodingGuidelines?

I have not seen an answer to that question--let alone a satisfactory
one.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17 13:22                 ` Derrick Stolee
  2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
@ 2021-06-17 15:25                   ` Felipe Contreras
  2021-06-18  0:26                   ` brian m. carlson
  2 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-17 15:25 UTC (permalink / raw)
  To: Derrick Stolee, Junio C Hamano, Ævar Arnfjörð Bjarmason
  Cc: Derrick Stolee via GitGitGadget, git, sandals, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

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

We already know that. We are waiting for an *explanation*.

Why?

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17  0:09               ` Junio C Hamano
  2021-06-17 13:22                 ` Derrick Stolee
  2021-06-17 15:23                 ` Felipe Contreras
@ 2021-06-17 15:58                 ` Ævar Arnfjörð Bjarmason
  2 siblings, 0 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-17 15:58 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: Derrick Stolee via GitGitGadget, git, sandals, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee


On Thu, Jun 17 2021, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>>   - Discussing command-line options, and program functionality:
>>
>>     Prefer succinctness and matter-of-factly describing functionality in
>>     the abstract.  E.g.
>>
>>      --short:: Emit output in the short-format.
>>
>>     Avoid more verbose constructions, such as:
>>
>>      --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...
>
> This applies the most broadly and addresses common readability
> issues, which is why I like this part the most.

*nod*

>>   - Addressing the reader:
>>   - Discussing Git, "the command" etc.:
>
> I am not sure if these are even worth saying, especially when we do
> not explain why we recommend to do so.

Maybe not, I tried to just grep around / search in my memory for how we
talk about this, to cover that base. I.e. when we talk about "you", then
other commands (this part), permissions, remote users etc...

>>   - Discussing other users:
>>
>>     When referring to other users on the same system prefer talking
>>     about "a user" or "another user". There's usually no reason to
>>     invent a cast of characters with names, titles and hobbies.
>>
>>     Your OS's users don't cleanly map onto any particular people, a user
>>     of git might be having a merge conflict with another person, or an
>>     automated commit from a cron daemon.
>>
>>     We prefer the style typical of standard library adn system tooling
>>     documentation in this and most other cases, you can look at the
>>     documentation of chmod(2) and other commands, syscalls and libraries
>>     that deal with UIDs or GIDs for examples.
>
> I cannot exactly put my fingers on where this feeling comes from,
> but this part appears to spend many lines to tell me very little.
>
> For example, it is unclear why the second paragraph is there at all.
> Sure, some commits may be created by a non people, but how does that
> fact affect how I write the documentation?  Writing about such an
> activity by non people, what are our recommendations?  The third
> paragraph does not do much better.  Unless you have UNIX man pages
> handy, chmod(2) may not be very easily accessible.  It feels as if
> it wants to encourage descriptions without human actors, without
> doing a very good job at explaining to readers why the guideline
> does not want to see them in our documentation.

The real problem here is that a clearly overly verbose person is trying
to write guidelines about how to be less verbose :) Yes, that can
probably go entirely.

> Unlike chmod(2) and getpwnam(3), but more like any dSCM, Git is a
> tool to help inter-person communication, and at some point we will
> have to talk about contributors asking their upstreams to pull their
> work from their repositories.  It won't be like system calls dealing
> with pure numbers.  We do not have to give them names like Alice and
> Bob, but we do have to refer to repositories of these cast of
> characters individually to clearly explain/describe how data flow
> among them.

I'd think that the *nix permission model in general and FS-like
permission models (including pseudo-implementations thereof, such as
Google Docs sharing etc.) in general are a much bigger helper of
inter-persion communication than Git is.

Which is what I was trying to aim for, the documentation for such
systems can usually talk about the permission models and "foreign" data
in matter of fact terms. E.g. we really don't need to drag up an example
of another person on the system to explain core.sharedRepository to you,
or more generally why you get a permission error when you "cat"
something on a *nix system.

But yes, could be improved etc.; does anyone have a better suggestion? I
think whatever I come up with at this point is probably much better
copyedited by others.

>>   - Discussing other systems:
>>
>>     As with discussing other users, git might interact with other
>>     systems over the network. In these cases we also avoid a cast of
>>     characters, preferring to talk about concepts like "fetching data
>>     from a remote", having a conflict with "diverging histories" etc.
>
> Unlike the above "other users", I have littleproblem with this part.
> It however feels funny to warn against use of "cast of characters",
> when the first sentence talks about "with other systems", which are
> clearly not people.  Even when you are "fetching from a remote", you
> are getting the result of work by "other people", so I would not
> have separated "other users" and "other systems" in separate
> sections.

What I was trying to go for here is that we could say you do a fetch,
get a divergent branch, and a conflict, and then proceed from
there. It's just a distraction in such examples to set up a scenario
where J. Doe is the author of those commits, you can't reach them at the
office right now (maybe they're at lunch), but you need to resolve the
conflict yourself etc...

>> The references to "gendered prounouns" etc. are gone, perhaps there's a
>> good reason to re-include them, but the point of "isn't that issue
>> solved by recommending an orthagonal approach?" is one of the many
>> things Stolee hasn't been addressing in the threads related to this
>> series.
>>
>> To me that whole approach is somewhere between a solution in search of a
>> problem and a "let's fix it and move on". Not something we need
>> explicitly carry in our CodingGuidelines forever.
>
> This I think is the crux of the differences between you two.  I'd
> love to hear Derrick's response and eventually see a middle ground
> reached.

Covered downthread.

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
@ 2021-06-17 17:06                     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-17 17:06 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Derrick Stolee
  Cc: Junio C Hamano, Derrick Stolee via GitGitGadget, git, sandals,
	jrnieder, emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

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

Agreed, but what about *our* time?

I feel like we already have spent more than ten times the amount of time
this non-issue warranted. Can we return to do something actually
productive?

I vote for a moratorium on this issue. Can we leave this as it is and
return back to it in a month or so?

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-17 13:22                 ` Derrick Stolee
  2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
  2021-06-17 15:25                   ` Felipe Contreras
@ 2021-06-18  0:26                   ` brian m. carlson
  2021-06-18 16:12                     ` Felipe Contreras
  2 siblings, 1 reply; 124+ messages in thread
From: brian m. carlson @ 2021-06-18  0:26 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Junio C Hamano, Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget, git, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Phillip Susi, Johannes Schindelin, Bagas Sanjaya,
	Derrick Stolee, Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 1322 bytes --]

On 2021-06-17 at 13:22:21, Derrick Stolee wrote:
> On 6/16/2021 8:09 PM, Junio C Hamano wrote:
> I disagree that removing gendered pronouns and updating the
> guidelines are orthogonal. At minimum, we shouldn't have
> guidelines that we do not follow, especially when they are
> small in number and we can fix them in a few patches.
> 
> The entire point of this series was to reach a decision about
> gendered pronouns so we can stop having arguments about them
> when they come up. We should just be able to point to "here is
> the decision we made" and it's not enough to say "If you go
> look at the mailing list archive you can see that we removed
> all gendered pronouns so you shouldn't add them again."

I agree.  Part of the complaint in the previous thread was that we were
overly debating people's commit messages, which can be demoralizing to
contributors, especially new ones.  It's much better to decide on an
approach, document it, and then, if there's an issue, we can just point
people to the documentation.

And, judging by the amount of discussion around this topic, it would be
helpful to avoid rehashing the same discussion again and again.  I
certainly would prefer to not have this discussion multiple times.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
  2021-06-16 23:22               ` Felipe Contreras
  2021-06-17  0:09               ` Junio C Hamano
@ 2021-06-18  0:53               ` brian m. carlson
  2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
  2021-06-19  7:03                 ` Junio C Hamano
  2 siblings, 2 replies; 124+ messages in thread
From: brian m. carlson @ 2021-06-18  0:53 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, Derrick Stolee via GitGitGadget, git, stolee,
	jrnieder, emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

[-- Attachment #1: Type: text/plain, Size: 1526 bytes --]

On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote:
> The references to "gendered prounouns" etc. are gone, perhaps there's a
> good reason to re-include them, but the point of "isn't that issue
> solved by recommending an orthagonal approach?" is one of the many
> things Stolee hasn't been addressing in the threads related to this
> series.

I think I've addressed this.  Sometimes you can avoid referring to
people and therefore avoiding pronouns, and sometimes the prose reads
better if you talk about the user or actor.  Also, sometimes you need to
discuss a matter at length and using variety in your language is
desirable, so you may want to, for example, avoid continually using the
passive voice to discuss the topic.

I don't think it's fair to just say "don't refer to the user or other
humans if you'd need to use third-person pronouns" because I don't think
that's applicable in all cases.  I, for one, don't intend to write my
commit messages in that way because I think it will make them
substantially worse.  For example, I often discuss the behavior or
expectations of users when writing FAQ entries or other documentation
and sometimes we'll need to use pronouns.

I agree that in many cases we can effectively rephrase to avoid needing
to do this, but if we acknowledge that sometimes we will need to write
using third-person personal pronouns in some cases, it's worth
documenting what those should be.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-18  0:53               ` brian m. carlson
@ 2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
  2021-06-18 16:40                   ` Felipe Contreras
  2021-06-19  7:03                 ` Junio C Hamano
  1 sibling, 1 reply; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-18  7:24 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Junio C Hamano, Derrick Stolee via GitGitGadget, git, stolee,
	jrnieder, emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee


On Fri, Jun 18 2021, brian m. carlson wrote:

> [[PGP Signed Part:Undecided]]
> On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote:
>> The references to "gendered prounouns" etc. are gone, perhaps there's a
>> good reason to re-include them, but the point of "isn't that issue
>> solved by recommending an orthagonal approach?" is one of the many
>> things Stolee hasn't been addressing in the threads related to this
>> series.
>
> I think I've addressed this.  Sometimes you can avoid referring to
> people and therefore avoiding pronouns, and sometimes the prose reads
> better if you talk about the user or actor.  Also, sometimes you need to
> discuss a matter at length and using variety in your language is
> desirable, so you may want to, for example, avoid continually using the
> passive voice to discuss the topic.
>
> I don't think it's fair to just say "don't refer to the user or other
> humans if you'd need to use third-person pronouns" because I don't think
> that's applicable in all cases.  I, for one, don't intend to write my
> commit messages in that way because I think it will make them
> substantially worse.

You won't have to. Reading this and your slightly earlier
<YMvoNcFXnHo0KXH3@camp.crustytoothpaste.net> I think you've missed that
as of v2[1] of this series the proposal to is not to enforce this policy
on people's commit messages; so we're only talking about code comments
and documentation at this point.

> [...]For example, I often discuss the behavior or
> expectations of users when writing FAQ entries or other documentation
> and sometimes we'll need to use pronouns.
>
> I agree that in many cases we can effectively rephrase to avoid needing
> to do this, but if we acknowledge that sometimes we will need to write
> using third-person personal pronouns in some cases, it's worth
> documenting what those should be.

I agree with you as a general matter that anything we come up with,
whether it's a prose guideline, coding style etc. won't cover all
cases.

But perhaps we disagree on whether that should be a goal of our
guidelines at all. I don't think it should. It shouldn't because it
simply won't work, the amount of guidelines we ask contributors to read
becomes a zero-sum game at some point.

Assuming that most contributors attempt to at least skim them we've
already reached that point. It's a trivial task to find recent
submissions of patches that violate one guideline or another.

So the criteria for inclusion shouldn't be whether we can think of cases
they apply to, but whether those cases are common enough to warrant
explicit mention, keeping in mind that any new addition will dilute
whatever advice we're already giving. Having gone over the number of
occurances we're fixing [2] I don't see how this qualifies.

As Stolee said upthread[3], referring to Documentation/CodingGuidelines
("[]" edits of what I understood him to mean are mine):

    [It's the document that we] should just be able to point to [say] "here
    is the decision we made"

I just don't think that should be a primary or secondary goal of that
document. We have e.g. this mailing list discussion to point to for some
decision we made.

The CodingGuidelines is what we're asking people to read when they've
e.g. found some data-eating bug in git and are about to send us a patch,
but before that we're asking them to go through a fuzzy checklist of
items checklist. It's already 20 pages in my browser if I were to try to
print it.

1. https://lore.kernel.org/git/pull.975.v2.git.1623246878.gitgitgadget@gmail.com/
2. https://lore.kernel.org/git/87o8c4wkn7.fsf@evledraar.gmail.com/
3. https://lore.kernel.org/git/5755690e-ef13-e12c-4b10-9cb303ae843a@gmail.com/

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-18  0:26                   ` brian m. carlson
@ 2021-06-18 16:12                     ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-18 16:12 UTC (permalink / raw)
  To: brian m. carlson, Derrick Stolee
  Cc: Junio C Hamano, Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget, git, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Phillip Susi, Johannes Schindelin, Bagas Sanjaya,
	Derrick Stolee, Derrick Stolee

brian m. carlson wrote:
> And, judging by the amount of discussion around this topic, it would be
> helpful to avoid rehashing the same discussion again and again.  I
> certainly would prefer to not have this discussion multiple times.

I'm sure plenty of people would prefer not to have a discussion about
abortion multiple times either, but that's the nature of living in a
society.

There will always be differing opinions, and as long you are trying to
impose your opinion on others, there will be discussion.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
@ 2021-06-18 16:40                   ` Felipe Contreras
  0 siblings, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-18 16:40 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, brian m. carlson
  Cc: Junio C Hamano, Derrick Stolee via GitGitGadget, git, stolee,
	jrnieder, emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Ævar Arnfjörð Bjarmason wrote:

> The CodingGuidelines is what we're asking people to read when they've
> e.g. found some data-eating bug in git and are about to send us a patch,
> but before that we're asking them to go through a fuzzy checklist of
> items checklist. It's already 20 pages in my browser if I were to try to
> print it.

Exactly.

Moreover, the point a guideline is on the name: guide. After reading it
developers should feel they are heading in the right direction, but they
won't know everything there is to know about git.git development, that
requires many years of practice, and mistakes.

More importantly than what it is, is what it's not: by-laws.

A developer that misses a point in the guidelines should not be
reprimended and sent to the brig. Instead she should merely be directed
to it.

Another thing it shouldn't be is a tool to win arguments. If two
developers argue about sentence spacing (one space vs. two spaces), even
if the whole community agrees two spaces is preferable--and thus one
developer "won" the argument--that still doesn't merit writing it down
to further rub it in.

Not everything belongs in the guideline; only the most salient tips that
guide newcomers in the right direction.

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-18  0:53               ` brian m. carlson
  2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
@ 2021-06-19  7:03                 ` Junio C Hamano
  2021-06-28 22:32                   ` Junio C Hamano
  1 sibling, 1 reply; 124+ messages in thread
From: Junio C Hamano @ 2021-06-19  7:03 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget, git, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> I agree that in many cases we can effectively rephrase to avoid needing
> to do this, but if we acknowledge that sometimes we will need to write
> using third-person personal pronouns in some cases, it's worth
> documenting what those should be.

I think we've heard enough from both sides and there probably is not
misunderstanding among the folks, even though there are differences
of opinions.

I would like to consider that the last draft I did [*1*] based on
earlier suggestions by Derrick and Ævar would be a reasonable middle
ground.

I'll go mostly offline next week---I'd notice if the list came up
with a vastly different concensus when I come back, but hopefully
not ;-)

Thanks.


[Reference]

*1* https://lore.kernel.org/git/xmqqbl86qtyf.fsf@gitster.g/


^ permalink raw reply	[flat|nested] 124+ messages in thread

* RE: [PATCH 1/4] Documentation: use singular they when appropriate
  2021-06-09 17:44         ` Felipe Contreras
@ 2021-06-25 14:30           ` Kerry, Richard
  0 siblings, 0 replies; 124+ messages in thread
From: Kerry, Richard @ 2021-06-25 14:30 UTC (permalink / raw)
  To: Felipe Contreras, Emily Shaffer, Derrick Stolee via GitGitGadget
  Cc: git, gitster, sandals, stolee, jrnieder, Derrick Stolee, Derrick Stolee


> From: Felipe Contreras <felipe.contreras@gmail.com>
> Sent: 09 June 2021 18:45
> Subject: RE: [PATCH 1/4] Documentation: use singular they when appropriate
> 
> > [RK]  Or rephrase to sidestep the issue 
> 
> 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.
 
Sorry.  Yes.  Will do.
When I first looked for reply options In Outlook I couldn't find "indent with prefix".
I've just looked again and found it.
Though it is still giving me "[RK}" on new lines, so I need another look to get that turned off.

Regards,
Richard.



^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-19  7:03                 ` Junio C Hamano
@ 2021-06-28 22:32                   ` Junio C Hamano
  2021-06-29  1:31                     ` Felipe Contreras
  2021-06-29  1:53                     ` Derrick Stolee
  0 siblings, 2 replies; 124+ messages in thread
From: Junio C Hamano @ 2021-06-28 22:32 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget, git, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Junio C Hamano <gitster@pobox.com> writes:

> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>
>> I agree that in many cases we can effectively rephrase to avoid needing
>> to do this, but if we acknowledge that sometimes we will need to write
>> using third-person personal pronouns in some cases, it's worth
>> documenting what those should be.
>
> I think we've heard enough from both sides and there probably is not
> misunderstanding among the folks, even though there are differences
> of opinions.
>
> I would like to consider that the last draft I did [*1*] based on
> earlier suggestions by Derrick and Ævar would be a reasonable middle
> ground.
>
> I'll go mostly offline next week---I'd notice if the list came up
> with a vastly different concensus when I come back, but hopefully
> not ;-)

Well, I misspoke.  If the list reached a consensus while I was away,
then that would have been a happy outcome, whether it was close to,
or vastly different from, the one I suggested.

In any case, I haven't even started to try catching up with the list
traffic last week, so hopefully I'll see soon enough what you folks
decided (or not).


> Thanks.
>
>
> [Reference]
>
> *1* https://lore.kernel.org/git/xmqqbl86qtyf.fsf@gitster.g/

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-28 22:32                   ` Junio C Hamano
@ 2021-06-29  1:31                     ` Felipe Contreras
  2021-06-29  1:53                     ` Derrick Stolee
  1 sibling, 0 replies; 124+ messages in thread
From: Felipe Contreras @ 2021-06-29  1:31 UTC (permalink / raw)
  To: Junio C Hamano, brian m. carlson
  Cc: Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget, git, stolee, jrnieder,
	emilyshaffer, Andrei Rybak, Felipe Contreras,
	Robert Karszniewicz, Jeff King, Kerry, Richard, Phillip Susi,
	Johannes Schindelin, Bagas Sanjaya, Derrick Stolee,
	Derrick Stolee

Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
> > "brian m. carlson" <sandals@crustytoothpaste.net> writes:
> >
> >> I agree that in many cases we can effectively rephrase to avoid needing
> >> to do this, but if we acknowledge that sometimes we will need to write
> >> using third-person personal pronouns in some cases, it's worth
> >> documenting what those should be.
> >
> > I think we've heard enough from both sides and there probably is not
> > misunderstanding among the folks, even though there are differences
> > of opinions.
> >
> > I would like to consider that the last draft I did [*1*] based on
> > earlier suggestions by Derrick and Ævar would be a reasonable middle
> > ground.
> >
> > I'll go mostly offline next week---I'd notice if the list came up
> > with a vastly different concensus when I come back, but hopefully
> > not ;-)
> 
> Well, I misspoke.  If the list reached a consensus while I was away,
> then that would have been a happy outcome, whether it was close to,
> or vastly different from, the one I suggested.
> 
> In any case, I haven't even started to try catching up with the list
> traffic last week, so hopefully I'll see soon enough what you folks
> decided (or not).

I took "I think we've heard enough" as "don't discuss about this
anymore". And judging from the lack of responses from oher people I
think others did interpret it in a similar vein.

I still haven't seen a single argument as to why the fixes in the
wording have to be necessarily tied to an update in the guidelines, so I
don't see why would have changed my mind.

They are orthogonal.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-28 22:32                   ` Junio C Hamano
  2021-06-29  1:31                     ` Felipe Contreras
@ 2021-06-29  1:53                     ` Derrick Stolee
  2021-06-29 12:29                       ` Ævar Arnfjörð Bjarmason
  1 sibling, 1 reply; 124+ messages in thread
From: Derrick Stolee @ 2021-06-29  1:53 UTC (permalink / raw)
  To: Junio C Hamano, brian m. carlson
  Cc: Ævar Arnfjörð Bjarmason,
	Derrick Stolee via GitGitGadget, git, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Phillip Susi, Johannes Schindelin, Bagas Sanjaya,
	Derrick Stolee, Derrick Stolee

On 6/28/2021 6:32 PM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>> I would like to consider that the last draft I did [*1*] based on
>> earlier suggestions by Derrick and Ævar would be a reasonable middle
>> ground.
>>
>> I'll go mostly offline next week---I'd notice if the list came up
>> with a vastly different concensus when I come back, but hopefully
>> not ;-)
> 
> Well, I misspoke.  If the list reached a consensus while I was away,
> then that would have been a happy outcome, whether it was close to,
> or vastly different from, the one I suggested.

I hope that my reply to your attempt was clear that I found it to
be a good approach. I'm happy with it.

Thanks,
-Stolee

^ permalink raw reply	[flat|nested] 124+ messages in thread

* Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
  2021-06-29  1:53                     ` Derrick Stolee
@ 2021-06-29 12:29                       ` Ævar Arnfjörð Bjarmason
  0 siblings, 0 replies; 124+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-29 12:29 UTC (permalink / raw)
  To: Derrick Stolee
  Cc: Junio C Hamano, brian m. carlson,
	Derrick Stolee via GitGitGadget, git, jrnieder, emilyshaffer,
	Andrei Rybak, Felipe Contreras, Robert Karszniewicz, Jeff King,
	Kerry, Richard, Phillip Susi, Johannes Schindelin, Bagas Sanjaya,
	Derrick Stolee, Derrick Stolee


On Mon, Jun 28 2021, Derrick Stolee wrote:

> On 6/28/2021 6:32 PM, Junio C Hamano wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>> I would like to consider that the last draft I did [*1*] based on
>>> earlier suggestions by Derrick and Ævar would be a reasonable middle
>>> ground.
>>>
>>> I'll go mostly offline next week---I'd notice if the list came up
>>> with a vastly different concensus when I come back, but hopefully
>>> not ;-)
>> 
>> Well, I misspoke.  If the list reached a consensus while I was away,
>> then that would have been a happy outcome, whether it was close to,
>> or vastly different from, the one I suggested.
>
> I hope that my reply to your attempt was clear that I found it to
> be a good approach. I'm happy with it.

Since you posted the v3 of this patch series there's been on the order
of 30 E-Mails dowthread of v3 4/4, but your only replies have been to
Junio.

What phrasing (if any) we use for prose guidelines in the
CodingGuidelines doesn't cover the various outstanding questions. Mostly
point-by-point feedback from myself & Felipe.

Per my upthread [1] do you plan to address that feedback & re-roll, or
ignore it?

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

^ permalink raw reply	[flat|nested] 124+ messages in thread

end of thread, other threads:[~2021-06-29 12:48 UTC | newest]

Thread overview: 124+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
2021-06-07 17:32     ` Derrick Stolee
2021-06-07 17:42       ` Andrei Rybak
2021-06-07 18:21       ` Ævar Arnfjörð Bjarmason
2021-06-10  7:44     ` Johannes Schindelin
2021-06-10 14:35       ` Felipe Contreras
2021-06-07 21:36   ` Felipe Contreras
2021-06-09 18:47     ` Phillip Susi
2021-06-09 20:26       ` Felipe Contreras
2021-06-11 15:40         ` Phillip Susi
2021-06-11 17:03           ` Felipe Contreras
2021-06-10 18:30       ` Derrick Stolee
2021-06-11  0:16         ` Junio C Hamano
2021-06-11 16:00         ` Felipe Contreras
2021-06-12 14:02         ` Phillip Susi
2021-06-08  1:18   ` Junio C Hamano
2021-06-08  8:51     ` Kerry, Richard
2021-06-08 23:21       ` Junio C Hamano
2021-06-09 13:13         ` Derrick Stolee
2021-06-10  3:11         ` Junio C Hamano
2021-06-08 17:33   ` Emily Shaffer
2021-06-08 18:03     ` Felipe Contreras
2021-06-09 13:44       ` Kerry, Richard
2021-06-09 17:44         ` Felipe Contreras
2021-06-25 14:30           ` Kerry, Richard
2021-06-09  4:48     ` Junio C Hamano
2021-06-10  8:18     ` Johannes Schindelin
2021-06-10 14:42       ` Felipe Contreras
2021-06-14 22:10       ` Robert Karszniewicz
2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
2021-06-07 17:20     ` Derrick Stolee
2021-06-10  8:20     ` Johannes Schindelin
2021-06-07 19:02   ` Junio C Hamano
2021-06-07 21:44     ` Felipe Contreras
2021-06-08 17:36   ` Emily Shaffer
2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-08 17:37   ` Emily Shaffer
2021-06-10  8:36   ` Johannes Schindelin
2021-06-10 19:53     ` Derrick Stolee
2021-06-11  9:55       ` Johannes Schindelin
2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
2021-06-08  1:47     ` Felipe Contreras
2021-06-07 18:56   ` Junio C Hamano
2021-06-07 19:05     ` Derrick Stolee
2021-06-08  0:05       ` Junio C Hamano
2021-06-10 21:34       ` brian m. carlson
2021-06-10  8:39     ` Johannes Schindelin
2021-06-07 20:00   ` Felipe Contreras
2021-06-09 18:29     ` Phillip Susi
2021-06-09 20:18       ` Felipe Contreras
2021-06-07 20:20   ` Robert Karszniewicz
2021-06-07 22:18     ` Felipe Contreras
2021-06-08  7:10   ` Jeff King
2021-06-08  8:11     ` Felipe Contreras
2021-06-09 13:23       ` Derrick Stolee
2021-06-09 15:20         ` Felipe Contreras
2021-06-10 22:06     ` brian m. carlson
2021-06-11 16:11       ` Felipe Contreras
2021-06-08 17:39   ` Emily Shaffer
2021-06-09  4:44     ` Junio C Hamano
2021-06-09 13:27       ` Derrick Stolee
2021-06-07 20:10 ` [PATCH 0/4] Use singular "they" when appropriate Felipe Contreras
2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
2021-06-09 15:33     ` Felipe Contreras
2021-06-09 13:54   ` [PATCH v2 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
2021-06-09 15:41     ` Felipe Contreras
2021-06-09 13:54   ` [PATCH v2 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-09 13:54   ` [PATCH v2 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-09 15:50     ` Felipe Contreras
2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
2021-06-09 17:22     ` Felipe Contreras
2021-06-10  2:03     ` Junio C Hamano
2021-06-10  2:28       ` Junio C Hamano
2021-06-10  3:30       ` Felipe Contreras
2021-06-10 22:32     ` brian m. carlson
2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
2021-06-11 16:32         ` Felipe Contreras
2021-06-11 17:18         ` Derrick Stolee
2021-06-11 20:38           ` Felipe Contreras
2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
2021-06-15  6:02             ` Junio C Hamano
2021-06-15 13:36               ` Derrick Stolee
2021-06-15 17:03                 ` Felipe Contreras
2021-06-14  0:47           ` Junio C Hamano
2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 1/4] doc: avoid using the gender of other people Felipe Contreras via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 2/4] comments: avoid using the gender of our users Felipe Contreras via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
2021-06-15 17:26         ` Felipe Contreras
2021-06-16  2:47         ` Junio C Hamano
2021-06-16  5:06           ` Junio C Hamano
2021-06-16  9:26             ` Bagas Sanjaya
2021-06-16 17:44             ` Derrick Stolee
2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
2021-06-16 23:22               ` Felipe Contreras
2021-06-17  0:09               ` Junio C Hamano
2021-06-17 13:22                 ` Derrick Stolee
2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
2021-06-17 17:06                     ` Felipe Contreras
2021-06-17 15:25                   ` Felipe Contreras
2021-06-18  0:26                   ` brian m. carlson
2021-06-18 16:12                     ` Felipe Contreras
2021-06-17 15:23                 ` Felipe Contreras
2021-06-17 15:58                 ` Ævar Arnfjörð Bjarmason
2021-06-18  0:53               ` brian m. carlson
2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
2021-06-18 16:40                   ` Felipe Contreras
2021-06-19  7:03                 ` Junio C Hamano
2021-06-28 22:32                   ` Junio C Hamano
2021-06-29  1:31                     ` Felipe Contreras
2021-06-29  1:53                     ` Derrick Stolee
2021-06-29 12:29                       ` Ævar Arnfjörð Bjarmason
2021-06-17 15:12             ` Felipe Contreras
2021-06-17 14:46           ` Felipe Contreras
2021-06-15 17:08       ` Felipe Contreras
2021-06-12  4:40 ` [PATCH 0/4] Use singular "they" when appropriate Bagas Sanjaya
2021-06-12 14:19   ` Phillip Susi

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.