Skip to content

Commit 66251a3

Browse files
chriscoolchriscool
committed
rn-112: add article about BreakingChange doc
1 parent c314067 commit 66251a3

File tree

1 file changed

+125
-2
lines changed

1 file changed

+125
-2
lines changed

‎rev_news/drafts/edition-112.md

Lines changed: 125 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,132 @@ This edition covers what happened during the months of May 2024 and June 2024.
2121
### General
2222
-->
2323

24-
<!---
2524
### Reviews
26-
-->
25+
26+
* [[RFC PATCH] docs: document upcoming breaking changes](https://lore.kernel.org/git/fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im/)
27+
28+
Patrick Steinhardt sent an RFC patch to the mailing list that
29+
created a new "UpcomingBreakingChanges.md" document. The goal of the
30+
document was to inform users and developers of deprecations and
31+
breaking changes, and to encourage discussion of the direction of
32+
the project regarding these topics in advance.
33+
34+
Patrick noted that the changes listed in the document, along with
35+
links to mailing list threads where they had been discussed, were a
36+
work in progress with controversial and missing items, and that he
37+
didn't want to push for a Git 3.0 release with the listed changes
38+
soon.
39+
40+
The idea for that new document had been discussed previously
41+
[in a thread about a patch series from Patrick](https://lore.kernel.org/git/ZjiL7vu5kCVwpsLd@tanuki/)
42+
that introduced subcommands like `get`, `set`, etc, in `git config`.
43+
In that thread, after Patrick asked if we wanted to introduce a
44+
document to keep track of upcoming removals for a potential Git 3.0
45+
release, Junio Hamano, the Git maintainer, replied to Patrick that
46+
in a few of his ["What's cooking" emails](https://lore.kernel.org/git/?q=s%3A%22What%27s+cooking+in+git.git%22)
47+
before the Git 2.44.0 release, he wrote:
48+
49+
> It may not be a bad idea to reflect on what technical debt and UI
50+
> warts we have accumulated so far to see if we have enough of them to
51+
> start planning for a breaking Git 3.0 release (or, of course, keep
52+
> incrementally improve the system, which is much more preferable --
53+
> continuity and stability is good).
54+
55+
So Junio was happy that "somebody has bit it ;-)" and suggested a
56+
number of topics that could be added to the document Patrick wanted
57+
to create. This started a discussion about deprecating or not some
58+
features like the `restore`, `switch`, `submodules` and `worktrees`
59+
subcommands.
60+
61+
In the RFC patch to add the document, Patrick mentioned some of the
62+
topics suggested by Junio, but not others that seemed controversial
63+
in the previous discussion.
64+
65+
Johannes Schindelin, alias Dscho, replied to Patrick's RFC patch
66+
saying he loved it. Dscho also gave his opinion about the topics,
67+
and suggested to deprecate or remove additional rarely used
68+
features.
69+
70+
Junio replied to Patrick's patch suggesting to add features that we
71+
don't want to drop and why, and to mention that we deprecate but,
72+
for backward compatibility, rarely remove old ways to do things.
73+
Patrick agreed to Junio's suggestion and proposed a "superseded"
74+
section for the features we don't want to drop.
75+
76+
Dragan Simic, who add participated in the previous discussions in
77+
the `git config` thread, repeated that he didn't want to see neither
78+
`git restore`, `git switch` or `git checkout` deprecated, which
79+
Patrick agreed shouldn't be done.
80+
81+
Phillip Wood, replying to Patrick's patch, asked if the document
82+
should track the progress of some unfinished work, like the config
83+
based hooks implementation, but Patrick said he was planning on
84+
creating a separate document for long running projects, projects
85+
already discussed and perhaps also small or micro projects to help
86+
newcomers looking for something to work on too.
87+
88+
Justin Tobler also replied to Patrick's patch suggesting adding the
89+
removal of double dot and triple dot syntax (".." and "...") from
90+
`git diff` to the document. This was discussed by Junio and Patrick
91+
but, as it would need a lot more work, Patrick decided to not add it
92+
to the document for now.
93+
94+
Patrick then sent a
95+
[version 2 of his patch](https://lore.kernel.org/git/2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im/)
96+
which added section about features "that are _not_ to be
97+
deprecated". Some features were also added while deprecating the
98+
hook directory was removed for now.
99+
100+
Karthik Nayak replied to the version 2 patch listing a number of
101+
commands not mentioned in the document that do similar things which
102+
might indicate that some of them could be deprecated too. Patrick,
103+
Junio and Dragan discussed these commands, but decided that only
104+
`git pickaxe`, which is an alias for `git blame` could be removed
105+
for now.
106+
107+
So Patrick sent a
108+
[version 3 of his patch](https://lore.kernel.org/git/84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps@pks.im/)
109+
which only added the removal of `git pickaxe`.
110+
111+
Junio replied to this version 3 with a lot of comments to discuss
112+
how each item was justified and how we could improve on justifying
113+
items in general. Patrick then agreed on ways to improve the
114+
document.
115+
116+
Patrick sent a
117+
[version 4](https://lore.kernel.org/git/[email protected]/)
118+
where the single patch had been broken down into 4 patches. In the
119+
process a lot of the proposed deprecation from the previous version
120+
were removed and the document name was changed from
121+
"UpcomingBreakingChanges.md" to "BreakingChanges.md" as some changes
122+
listed in the "Superseded features that will not be deprecated"
123+
section should not be considered as upcoming.
124+
125+
The goal was to introduce the document in a skeletal form in the
126+
first patch and then add only one item to each of the three sections
127+
in the following patches. This way each of the last 3 patches should
128+
be an example of how other items should later be added to the
129+
document.
130+
131+
Junio, Patrick and Todd Zullinger then discussed relatively small
132+
improvements to the form and content of the document.
133+
134+
Patrick sent a
135+
[version 5 of the patch series](https://lore.kernel.org/git/[email protected]/)
136+
137+
where the main change was that the document was converted to
138+
AsciiDoc instead of MarkDown and renamed from "BreakingChanges.md"
139+
to "BreakingChanges.txt" for format compatibility with most other
140+
documents in the codebase.
141+
142+
Junio, Phillip Wood and Patrick discussed other small improvements
143+
which Patrick integrated into the
144+
[version 6 of the patch series](https://lore.kernel.org/git/[email protected]/).
145+
146+
Junio then suggested a few more small improvements which Patrick
147+
integrated into the
148+
[version 6 of the patch series](https://lore.kernel.org/git/[email protected]/)
149+
which was later merged into the 'master' branch.
27150

28151
<!---
29152
### Support

0 commit comments

Comments
 (0)