[PATCH v4 0/6] Nominating "whatchanged" for removal

[Junio C Hamano <gitster@pobox.com>]

"git whatchanged" has outlived its usefulness when "git log" with
various diff-related options more than 10 years ago.  It is not even
shorter to type than its rough equivalent "git log --raw".  It is
high time to start seeing if it is still being used, declare its
official deprecation, and announce its removal in the future.

This iteration is more complete than the previous two iterations:

 * The first step is to refactor the mechanism to show the message
   to ask users to contact git@vger that they still use the command,
   out of "git pack-redundant" implementation.  This message is
   shown when the "--i-still-use-this" option is not passed to a
   command that requires it.

 * The second and the third step are to remove unnecessary mentions
   of "whatchanged" from our documentation and tests.  With these,
   we have fewer places that we need to adjust when the command gets
   truly removed.

 * Then we start to require that the "--i-still-use-this" option is
   passed from the command line.  This requires adjustment for tests
   that protect the behaviour of the command, as they must now pass
   the required option just like end-users.

 * The last two steps are for a future.  In order to make sure that
   we can cleanly ditch the feature at some future date by removing
   it from the build, test, and documentation when Git is built with
   WITH_BREAKING_CHANGES.  And finally we add "whatchanged" to the
   list of features to be removed in the BreakingChanges document.

This iteration incorporates updated log messages, and a missing
period in the documentation, helped by Elijah.


Junio C Hamano (6):
  you-still-use-that??: help deprecating commands for removal
  doc: prepare for a world without whatchanged
  tests: prepare for a world without whatchanged
  whatchanged: require --i-still-use-this
  whatchanged: remove when built with WITH_BREAKING_CHANGES
  whatschanged: list it in BreakingChanges document

 Documentation/BreakingChanges.adoc           |  9 ++++++
 Documentation/MyFirstObjectWalk.adoc         |  4 +--
 Documentation/config/format.adoc             |  6 ++++
 Documentation/config/log.adoc                | 11 +++++--
 Documentation/git-whatchanged.adoc           | 10 ++++--
 Documentation/pretty-options.adoc            |  5 +++
 Documentation/rev-list-options.adoc          |  9 ++++--
 Documentation/technical/sparse-checkout.adoc |  2 +-
 Documentation/user-manual.adoc               |  2 +-
 builtin/log.c                                | 19 +++++++++++
 builtin/pack-redundant.c                     | 10 ++----
 git-compat-util.h                            |  2 ++
 git.c                                        |  2 ++
 t/t4013-diff-various.sh                      | 27 ++++++++++++++--
 t/t4202-log.sh                               | 34 ++++++++++++++------
 t/t5323-pack-redundant.sh                    |  5 +++
 t/t9300-fast-import.sh                       | 12 +++----
 t/t9301-fast-import-notes.sh                 |  2 +-
 usage.c                                      | 12 +++++++
 19 files changed, 146 insertions(+), 37 deletions(-)

Range-diff against v3:
1:  a43a2ffdab ! 1:  fedbc30d0e you-still-use-that??: help deprecating commands for removal
    @@ Metadata
      ## Commit message ##
         you-still-use-that??: help deprecating commands for removal
     
    -    A command slated for removal like "git pack-redundant" gains a
    -    command line option "--i-still-use-this", and refuses to work when
    -    the option is not given.  The message and the instruction upon
    -    seeing what to do are both rather long, so before letting another
    -    command to use the same mechanism, factor out the message+die part
    -    into a small helper function, and use that.
    +    Commands slated for removal like "git pack-redundant" now require
    +    an explicit "--i-still-use-this" option to run.  This is to
    +    discourage casual use and surface their pending deprecation to
    +    users.
     
    -    The existing pack-redundant test lacked a test to make sure that we
    -    require the --i-still-use-this option.  Add one while we are at it.
    +    The warning message is long, so factor it into a helper function
    +    you_still_use_that() to simplify reuse by other commands.
    +
    +    Also add a missing test to ensure this enforcement works for
    +    "pack-redundant".
     
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
2:  16ccf7d92e ! 2:  7a3897acca doc: prepare for a world without whatchanged
    @@ Metadata
      ## Commit message ##
         doc: prepare for a world without whatchanged
     
    -    These documents mention "whatchanged" as an example, that can be
    -    substituted by something else.  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.
    +    Some documentation examples reference "whatchanged", either as a
    +    placeholder command or an example of source structure.
    +
    +    To reduce the need for future edits when `whatchanged` is removed,
    +    replace these references with alternatives:
    +
    +     - In `MyFirstObjectWalk.adoc`, use `version` as the nearby anchor
    +       point for `walken`, instead of `whatchanged`.
    +
    +     - In `user-manual.adoc`, cite `show` instead of `whatchanged` as
    +       a command whose source lives in the same file as `log`.
     
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
3:  6951fb8cef ! 3:  f696eed84b tests: prepare for a world without whatchanged
    @@ Commit message
         Some tests on fast-import run "git whatchanged" without even
         checking the output from the command.  It is tempting to remove the
         calls altogether since they are not doing anything useful, but they
    -    presumably were placed while the tests were developed to manually
    +    presumably were added there while the tests were developed to manually
         sanity check which paths were touched.
     
         Replace these calls with "git log --raw", which is a rough
4:  2775f628c3 = 4:  01d4ed9acd whatchanged: require --i-still-use-this
5:  b3d4d1f46a = 5:  a7aca55d5d whatchanged: remove when built with WITH_BREAKING_CHANGES
6:  7c89054731 ! 6:  9d60f38d2f whatschanged: list it in BreakingChanges document
    @@ Documentation/BreakingChanges.adoc: references.
     +  `--i-still-use-this` option is given, and asked the users to report
     +  when they do so.  So far there hasn't been a single complaint.
     ++
    -+The command will be removed
    ++The command will be removed.
     +
      == Superseded features that will not be deprecated
      
-- 
2.49.0-674-gc1e4f99c0b