Re: [PATCH v3 2/6] doc: prepare for a world without whatchanged

From: Elijah Newren <newren@gmail.com>
Date: May 12, 2025, 17:36 UTC
Message-ID: <CABPp-BGXT5w8UxfnbELLFNvVQ1LTSj0oZVFi-XvCZ=0=NXUnEQ@mail.gmail.com>
In-Reply-To: <20250503005814.3030099-3-gitster@pobox.com>

On Fri, May 2, 2025 at 5:58 PM Junio C Hamano <gitster@pobox.com> wrote:

>
> These documents mention "whatchanged" as an example, that can be
> substituted by something else.

Perhaps:

These documents mention "whatchanged" as an example, which can be substituted with something else.

Show 9 quoted lines

>  A new hypothetical command "walken"
> would come near "whatchanged" but since the latter may be going
> away, we can say it would come near "version", as the fictitious
> command sorts between them.  Similarly, we do not have to use
> "whatchanged" as an example of a subcommand that is also implemented
> in builtin/log.c file; we can instead mention "show".
>
> Both of these changes allow us not to worry about adjusting these
> places when "whatchanged" is finally removed.

Could I suggest (now changing my previous suggestion to handle the entire commit message):

doc: prepare for a world without whatchanged

Some documentation examples reference `whatchanged`, either as a placeholder command or as an example of source structure.

To reduce the need for future edits when `whatchanged` is removed, these references are replaced with alternatives:

- In `MyFirstObjectWalk.adoc`, we use `version` as the nearby anchor
  point for `walken`, instead of `whatchanged`.
- In `user-manual.adoc`, we now cite `show` instead of `whatchanged`
  as a command that coexists with `log` in builtin/log.c.

This avoids needing further cleanup when `whatchanged` is retired.

Show 41 quoted lines

> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/MyFirstObjectWalk.adoc | 4 ++--
>  Documentation/user-manual.adoc       | 2 +-
>  2 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc
> index d6e9dfdbbe..102a465a48 100644
> --- a/Documentation/MyFirstObjectWalk.adoc
> +++ b/Documentation/MyFirstObjectWalk.adoc
> @@ -83,13 +83,13 @@ int cmd_walken(int argc, const char **argv, const char *prefix)
>  }
>  ----
>
> -Also add the relevant line in `builtin.h` near `cmd_whatchanged()`:
> +Also add the relevant line in `builtin.h` near `cmd_version()`:
>
>  ----
>  int cmd_walken(int argc, const char **argv, const char *prefix);
>  ----
>
> -Include the command in `git.c` in `commands[]` near the entry for `whatchanged`,
> +Include the command in `git.c` in `commands[]` near the entry for `version`,
>  maintaining alphabetical ordering:
>
>  ----
> diff --git a/Documentation/user-manual.adoc b/Documentation/user-manual.adoc
> index d2b478ad23..7124345966 100644
> --- a/Documentation/user-manual.adoc
> +++ b/Documentation/user-manual.adoc
> @@ -4240,7 +4240,7 @@ command `git`.  The source side of a builtin is
>  - an entry in `BUILTIN_OBJECTS` in the `Makefile`.
>
>  Sometimes, more than one builtin is contained in one source file.  For
> -example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`,
> +example, `cmd_show()` and `cmd_log()` both reside in `builtin/log.c`,
>  since they share quite a bit of code.  In that case, the commands which are
>  _not_ named like the `.c` file in which they live have to be listed in
>  `BUILT_INS` in the `Makefile`.
> --
> 2.49.0-601-ga5925c3955

Patch looks good.