Welcome to the 112th edition of Git Rev News, a digest of all things Git. For our goals, the archives, the way we work, and how to contribute or to subscribe, see the Git Rev News page on git.github.io.
This edition covers what happened during the months of May and June 2024.
[RFC PATCH] docs: document upcoming breaking changes
Patrick Steinhardt sent an RFC patch to the mailing list that created a new “UpcomingBreakingChanges.md” document. The goal of the document was to inform users and developers of deprecations and breaking changes, and to encourage discussion of the direction of the project regarding these topics in advance.
Patrick noted that the changes listed in the document, along with links to mailing list threads where they had been discussed, were a work in progress with controversial and missing items, and that he didn’t want to push for a Git 3.0 release with the listed changes soon.
The idea for that new document had been discussed previously
in a thread about a patch series from Patrick
that introduced subcommands like get, set, etc, in git config.
In that thread, after Patrick asked if we wanted to introduce a
document to keep track of upcoming removals for a potential Git 3.0
release, Junio Hamano, the Git maintainer, replied to Patrick that
in a few of his “What’s cooking” emails
before the Git 2.44.0 release, he had written:
It may not be a bad idea to reflect on what technical debt and UI warts we have accumulated so far to see if we have enough of them to start planning for a breaking Git 3.0 release (or, of course, keep incrementally improve the system, which is much more preferable – continuity and stability is good).
So Junio was happy that “somebody has bit it ;-)” and suggested a
number of topics that could be added to the document Patrick wanted
to create. This started a discussion about the possibility of
deprecating some features, such as the restore, switch,
submodules and worktrees subcommands.
In the RFC patch to add the document, Patrick mentioned some of the topics suggested by Junio, but not others that seemed controversial in the previous discussion.
Johannes Schindelin, alias Dscho, replied to Patrick’s RFC patch saying he loved it. Dscho also gave his opinion about the topics, and suggested to deprecate or remove additional rarely used features.
Junio replied to Patrick’s patch suggesting to add features that we don’t want to drop and why, and to mention that we deprecate but, for backward compatibility, rarely remove old ways to do things. Patrick agreed to Junio’s suggestion and proposed a “superseded” section for the features we don’t want to drop.
Dragan Simic, who had participated in the discussions of the preceding
git config thread, repeated that he didn’t want to see any of
git restore, git switch or git checkout deprecated, which
Patrick agreed shouldn’t be done.
Phillip Wood, replying to Patrick’s patch, asked if the document should track the progress of some unfinished work, like the config based hooks implementation. Patrick said he was planning on creating a separate document for long running projects, projects already discussed, and also small or micro projects, with the additional intent to help newcomers looking for something to work on.
Justin Tobler also replied to Patrick’s patch suggesting adding the
removal of double dot and triple dot syntax (“..” and “…”) from
git diff to the document. This was discussed by Junio and Patrick
but, as it would need a lot more work, Patrick decided to not add it
to the document for now.
Patrick then sent a
version 2 of his patch
adding a section about features “that are not to be
deprecated” and proposing some further deprecations, while withdrawing
the $GITDIR/hooks directory deprecation proposal.
Karthik Nayak replied to the patch version 2, listing a number of
commands not mentioned in the document that do similar things, which
might indicate that some of them could be deprecated too. Patrick,
Junio and Dragan discussed these commands, but decided that only
git pickaxe, which is an alias for git blame, could be removed
for now.
So Patrick sent a
version 3 of his patch,
which only added the removal of git pickaxe.
Junio replied to this version 3 with a lot of comments to discuss how each item was justified and how we could improve on justifying items in general. Patrick then agreed on ways to improve the document.
Patrick sent a version 4 where the single patch had been broken down into 4 patches. In the process a lot of the proposed deprecations from the previous version were removed and the document name was changed from “UpcomingBreakingChanges.md” to “BreakingChanges.md” as some changes listed in the “Superseded features that will not be deprecated” section should not be considered upcoming.
The goal was to introduce the document in a skeletal form in the first patch and then add only one item to each of the three sections in the following patches. This way each of the last 3 patches should be an example of how other items should later be added to the document.
Junio, Patrick and Todd Zullinger then discussed relatively small improvements to the form and content of the document.
Patrick sent a version 5 of the patch series where the main change was that the document was converted to AsciiDoc instead of Markdown and renamed from “BreakingChanges.md” to “BreakingChanges.txt” for format compatibility with most other documents in the codebase.
Junio, Phillip Wood and Patrick discussed other small improvements, which Patrick integrated into version 6 of the patch series.
Junio then suggested a few more small improvements, which Patrick finally integrated into version 7 of the patch series, which was later merged into the ‘master’ branch.