[PATCH v2 0/4] you-still-use-that??: improve breaking changes troubleshooting

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Based on the recent i-still-use-that reports about whatchanged, improve
the error reporting with this command in mind:

1. Give more possible actions instead of just (only) asking them to send
   an email
2. Hint how to replace their git-whatchanged(1) use with git-log(1)
3. Minor documentation changes

Also:[1] an alternative to linking to www.git-scm.com (in patch 1/4) is
to move this document to a regular installed man page:

    gitbreaking-changes(7)

[1]: Not mentioned on the v1 cover letter

§ What the errors now look like

    $ ./git pack-redundant
    'git pack-redundant' is nominated for removal.
    If you still use this command, here's what you can do:

    - read https://git-scm.com/docs/BreakingChanges.html
    - check if anyone has discussed this on the mailing
      list and if they came up with something that can
      help you: https://lore.kernel.org/git/?q=git%20pack-redundant
    - send an email to <git@vger.kernel.org> to let us
      know that you still use this command and were unable
      to determine a suitable replacement

    fatal: refusing to run without --i-still-use-this
    $ ./git whatchanged
    'git whatchanged' is nominated for removal.

    hint: You can replace 'git whatchanged <opts>' with:
        git log <opts> --raw --no-merges

    If you still use this command, here's what you can do:

    - read https://git-scm.com/docs/BreakingChanges.html
    - check if anyone has discussed this on the mailing
      list and if they came up with something that can
      help you: https://lore.kernel.org/git/?q=git%20whatchanged
    - send an email to <git@vger.kernel.org> to let us
      know that you still use this command and were unable
      to determine a suitable replacement

    fatal: refusing to run without --i-still-use-this

§ Changes in v2

These are also posted on the patches.

• Patch 1/4:
  • Change send-an-email bullet point
  • Change the area
  • Use www.git-scm.com, not simply git-scm
• Patch 2/4:
  • Fix whitespace error (I should have used `ci/check-whitespace.sh
    v2.51.0`)
  • Add missing colon (:) to footnote
  • Expand on footnote; a sentence is enough to summarize the difference

Kristoffer Haugsbakk (4):
  you-still-use-that??: help the user help themselves
  whatchanged: tell users the git-log(1) equivalent
  whatchanged: remove not-even-shorter clause
  BreakingChanges: remove claim about whatchanged reports

 Documentation/BreakingChanges.adoc |  2 +-
 Documentation/git-whatchanged.adoc |  8 ++++++--
 builtin/log.c                      |  6 +++++-
 builtin/pack-redundant.c           |  2 +-
 git-compat-util.h                  |  2 +-
 usage.c                            | 33 +++++++++++++++++++++++-------
 6 files changed, 40 insertions(+), 13 deletions(-)

Interdiff against v1:
diff --git a/builtin/log.c b/builtin/log.c
index 2f9e5e5a898..5dbb90c014d 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -542,7 +542,7 @@ int cmd_whatchanged(int argc,
 	opt.revarg_opt = REVARG_COMMITTISH;
 	cmd_log_init(argc, argv, prefix, &rev, &opt, &cfg);
 
-        if (!cfg.i_still_use_this)
+	if (!cfg.i_still_use_this)
 		you_still_use_that("git whatchanged",
 				   _("\n"
 				     "hint: You can replace 'git whatchanged <opts>' with:\n"
diff --git a/usage.c b/usage.c
index c661561b149..7545a616453 100644
--- a/usage.c
+++ b/usage.c
@@ -397,7 +397,9 @@ NORETURN void you_still_use_that(const char *command_name, const char *hint)
 		  "- check if anyone has discussed this on the mailing\n"
 		  "  list and if they came up with something that can\n"
 		  "  help you: https://lore.kernel.org/git/?q=%s\n"
-		  "- send an email to <git@vger.kernel.org>\n"
+		  "- send an email to <git@vger.kernel.org> to let us\n"
+		  "  know that you still use this command and were unable\n"
+		  "  to determine a suitable replacement\n"
 		  "\n"),
 		percent_encoded.buf);
 	strbuf_release(&percent_encoded);
Range-diff against v1:
1:  e81023edb2d ! 1:  6803e2cc6c3 usage: help the user help themselves
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    usage: help the user help themselves
    +    you-still-use-that??: help the user help themselves
     
         Give the user a list of suggestions for what to do when they run a
         deprecated command.
    @@ Commit message
     
         Also drop “Thanks” since it now would require a new paragraph.
     
    -    [1]: git-scm has a disclaimer for these internal documents that says
    -        that “This information is specific to the Git project”.  That’s
    +    [1]: www.git-scm.com has a disclaimer for these internal documents that
    +        says that “This information is specific to the Git project”.  That’s
             misleading in this particular case.  But users are unlikely to get
    -        discouraged from reading about why they (or their programs) cannot
    -        run a command any more; it clearly concerns them.
    +        discouraged from reading about why they (or their programs) cannot run a
    +        command any more; it clearly concerns them.
     
    +    Helped-by: Eric Sunshine <sunshine@sunshineco.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    -    An alternative to linking to git-scm is to move this document to a
    -    regular installed man page:
    +    v2:
    +
    +    I had second thoughts about the bullet point about send-an-email.
    +    Change it to the one Eric Sunshine proposed;[1] make sure to spell
    +    out that you can send an email conditioned on not finding a suitable
    +    replacement.
    +
    +    Also change the area to something more pointed.
    +
    +    And also use a clear URL to refer to www.git-scm.com.
    +
    +    [1]: https://lore.kernel.org/git/CAPig+cQkVP57n_FE6dJ0uxvai-J7usxKFp8gzfEbPY=Ytsd6=Q@mail.gmail.com/
    +
    +    • Change send-an-email bullet point
    +    • Change the area
    +    • Use www.git-scm.com, not simply git-scm
    +
    +    v1:
    +
    +    An alternative to linking to www.git-scm.com is to move this document to
    +    a regular installed man page:
     
             gitbreaking-changes(7)
     
    @@ usage.c: void bug_fl(const char *file, int line, const char *fmt, ...)
     +		  "- check if anyone has discussed this on the mailing\n"
     +		  "  list and if they came up with something that can\n"
     +		  "  help you: https://lore.kernel.org/git/?q=%s\n"
    -+		  "- send an email to <git@vger.kernel.org>\n"
    ++		  "- send an email to <git@vger.kernel.org> to let us\n"
    ++		  "  know that you still use this command and were unable\n"
    ++		  "  to determine a suitable replacement\n"
     +		  "\n"),
     +		command_name, percent_encoded.buf);
     +	strbuf_release(&percent_encoded);
2:  5407c0955af ! 2:  2f3ac952980 whatchanged: tell users the git-log(1) equivalent
    @@ Commit message
             • https://lore.kernel.org/git/1011073f-9930-4360-a42f-71eb7421fe3f@chrispalmer.uk/#t
             • https://lore.kernel.org/git/9fcbfcc4-79f9-421f-b9a4-dc455f7db485@acm.org/#t
             • https://lore.kernel.org/git/83241BDE-1E0D-489A-9181-C608E9FCC17B@gmail.com/
    -    [2] The error message on 2.51.0 does tell them to report it, unconditionally
    -    [3]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/
    +    [2]: The error message on 2.51.0 does tell them to report it, unconditionally
    +    [3]: You only get different outputs if you happen to have empty
    +         commits (no changes)[4]
    +    [4]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +
    +    Review found a whitespace error in the prev. patch version.  I found a
    +    broken footnote and wanted to expand on the last footnote.
    +
    +    • Fix whitespace error (I should have used `ci/check-whitespace.sh
    +      v2.51.0`)
    +    • Add missing colon (:) to footnote
    +    • Expand on footnote; a sentence is enough to summarize the difference
    +
      ## Documentation/git-whatchanged.adoc ##
     @@ Documentation/git-whatchanged.adoc: Shows commit logs and diff output each commit introduces.
      
    @@ Documentation/git-whatchanged.adoc: Shows commit logs and diff output each commi
     
      ## builtin/log.c ##
     @@ builtin/log.c: int cmd_whatchanged(int argc,
    - 	opt.revarg_opt = REVARG_COMMITTISH;
      	cmd_log_init(argc, argv, prefix, &rev, &opt, &cfg);
      
    --	if (!cfg.i_still_use_this)
    + 	if (!cfg.i_still_use_this)
     -		you_still_use_that("git whatchanged");
    -+        if (!cfg.i_still_use_this)
     +		you_still_use_that("git whatchanged",
     +				   _("\n"
     +				     "hint: You can replace 'git whatchanged <opts>' with:\n"
    @@ usage.c: NORETURN void you_still_use_that(const char *command_name)
      		  "- read https://git-scm.com/docs/BreakingChanges.html\n"
      		  "- check if anyone has discussed this on the mailing\n"
     @@ usage.c: NORETURN void you_still_use_that(const char *command_name)
    - 		  "  help you: https://lore.kernel.org/git/?q=%s\n"
    - 		  "- send an email to <git@vger.kernel.org>\n"
    + 		  "  know that you still use this command and were unable\n"
    + 		  "  to determine a suitable replacement\n"
      		  "\n"),
     -		command_name, percent_encoded.buf);
     +		percent_encoded.buf);
3:  5fad164d7d1 = 3:  a074e7be422 whatchanged: remove not-even-shorter clause
4:  f1bf0ea3846 = 4:  9196c3c7e33 BreakingChanges: remove claim about whatchanged reports

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.51.0.16.gcd94ab5bf81