git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: gitster@pobox.com, sandals@crustytoothpaste.net,
	stolee@gmail.com, jrnieder@gmail.com, emilyshaffer@google.com,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Andrei Rybak" <rybak.a.v@gmail.com>,
	"Felipe Contreras" <felipe.contreras@gmail.com>,
	"Robert Karszniewicz" <avoidr@posteo.de>,
	"Jeff King" <peff@peff.net>,
	"Kerry, Richard" <richard.kerry@atos.net>,
	"Phillip Susi" <phill@thesusis.net>,
	"Johannes Schindelin" <Johannes.Schindelin@gmx.de>,
	"Bagas Sanjaya" <bagasdotme@gmail.com>,
	"Derrick Stolee" <derrickstolee@github.com>
Subject: [PATCH v3 0/4] Avoid gendered pronouns
Date: Tue, 15 Jun 2021 14:11:08 +0000	[thread overview]
Message-ID: <pull.975.v3.git.1623766273.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.975.v2.git.1623246878.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

  parent reply	other threads:[~2021-06-15 14:11 UTC|newest]

Thread overview: 124+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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   ` Derrick Stolee via GitGitGadget [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=pull.975.v3.git.1623766273.gitgitgadget@gmail.com \
    --to=gitgitgadget@gmail.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=avarab@gmail.com \
    --cc=avoidr@posteo.de \
    --cc=bagasdotme@gmail.com \
    --cc=derrickstolee@github.com \
    --cc=emilyshaffer@google.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jrnieder@gmail.com \
    --cc=peff@peff.net \
    --cc=phill@thesusis.net \
    --cc=richard.kerry@atos.net \
    --cc=rybak.a.v@gmail.com \
    --cc=sandals@crustytoothpaste.net \
    --cc=stolee@gmail.com \
    --subject='Re: [PATCH v3 0/4] Avoid gendered pronouns' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox