Hi Christian, On Thu, 2 Nov 2023, Christian Couder wrote: > On Sun, Oct 29, 2023 at 7:02 AM Elijah Newren <newren@xxxxxxxxx> wrote: > > > On Thu, Oct 26, 2023 at 6:44 AM Johannes Schindelin > > <Johannes.Schindelin@xxxxxx> wrote: > > > > > > As mentioned in > > > https://lore.kernel.org/git/03460733-0219-c648-5757-db1958f8042e@xxxxxx/, > > > I would like the `EXPERIMENTAL` label to be shown prominently here. > > > Probably not only the `SYNOPSIS` as I had originally suggested but > > > also in the `NAME`. > > Ok, I have made changes in the v6 I just sent, so that there is > EXPERIMENTAL both in the NAME and SYNOPSIS. > > > > Otherwise we may end up with the same situation as with the (from my > > > perspective, failed) `git switch`/`git restore` experiment, where we > > > wanted to explore a better user experience than the overloaded `git > > > checkout` command, only to now be stuck with having to maintain > > > backward-compatibility for `git switch`/`git restore` command-line options > > > that were not meant to be set in stone but to be iterated on, instead. A > > > real-life demonstration of [Hyrum's Law](hyrumslaw.com/), if you like. Or, > > > from a different angle, we re-enacted https://xkcd.com/927/ in a way. > > Nit: Hyrum's Law says: > > "With a sufficient number of users of an API, > it does not matter what you promise in the contract: > all observable behaviors of your system > will be depended on by somebody." > > The doc is part of the contract, which according to this law doesn't > matter. So I don't see why you use this law to suggest a doc change. You're right. In addition to the documentation (where we definitely need to state the experimental nature of the command), we may want to consider adding the `EXPERIMENTAL` label not only to the output of `git replay -h`, but show also a warning for every `git replay` invocation cautioning users against depending on the current command-line options of this command. Ciao, Johannes
