| Message ID | pull.975.v2.git.1623246878.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | Use singular "they" when appropriate | expand |
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,
Æ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.
Æ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.
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.
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
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.
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.
Æ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.
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
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.
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>?
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.
Æ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.
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
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).
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.").