From: "Ævar Arnfjörð Bjarmason" <firstname.lastname@example.org> To: Derrick Stolee via GitGitGadget <email@example.com> Cc: firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, Andrei Rybak <firstname.lastname@example.org>, Felipe Contreras <email@example.com>, Robert Karszniewicz <firstname.lastname@example.org>, Jeff King <email@example.com>, "Kerry, Richard" <firstname.lastname@example.org>, Derrick Stolee <email@example.com> Subject: Re: [PATCH v2 0/4] Use singular "they" when appropriate Date: Wed, 09 Jun 2021 17:44:59 +0200 [thread overview] Message-ID: <firstname.lastname@example.org> (raw) In-Reply-To: <email@example.com> 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 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 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://firstname.lastname@example.org/ 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'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,
next prev parent reply other threads:[~2021-06-09 16:06 UTC|newest] Thread overview: 124+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-06-07 16:57 [PATCH " 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 ` Ævar Arnfjörð Bjarmason [this message] 2021-06-09 17:22 ` [PATCH v2 0/4] Use singular "they" when appropriate 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
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 List information: http://vger.kernel.org/majordomo-info.html * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: [PATCH v2 0/4] Use singular "they" when appropriate' \ /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
Code repositories for project(s) associated with this inbox: https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).