[PATCH v3 0/4] Avoid gendered pronouns

["Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>]

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