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@xxxxxxxxxxxxxxxxxxx/
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,
