Skip to content

Commit 0dec352

Browse files
chriscoolchriscool
committed
rn-110: add article about series descriptions
1 parent 68685dd commit 0dec352

File tree

1 file changed

+123
-3
lines changed

1 file changed

+123
-3
lines changed

‎rev_news/drafts/edition-110.md

Lines changed: 123 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,129 @@ This edition covers what happened during the months of March 2024 and April 2024
1717

1818
## Discussions
1919

20-
<!---
2120
### General
22-
-->
21+
22+
* [What's cooking in git.git (Mar 2024, #05; Tue, 19)](https://lore.kernel.org/git/[email protected]/)
23+
24+
Last March, Junio Hamano, the Git maintainer, sent one of the usual
25+
"What's cooking in git.git" emails that describe the current state
26+
of the patch series that might be merged into the development
27+
branches (mostly "master", "next" and "seen").
28+
29+
The patch series are listed in these emails along with some related
30+
information using a custom format. That format consists in the
31+
following elements:
32+
33+
- a title line, for example:
34+
35+
> * bl/cherry-pick-empty (2024-03-11) 7 commits
36+
37+
where `bl` are the initials of the author, and `cherry-pick-empty`
38+
an actual title,
39+
40+
- a patch list, for example:
41+
42+
> - cherry-pick: add `--empty` for more robust redundant commit handling
43+
> - cherry-pick: enforce `--keep-redundant-commits` incompatibility
44+
> - sequencer: do not require `allow_empty` for redundant commit options
45+
> - sequencer: treat error reading HEAD as unborn branch
46+
> - rebase: update `--empty=ask` to `--empty=stop`
47+
> - docs: clean up `--empty` formatting in git-rebase(1) and git-am (1)
48+
> - docs: address inaccurate `--empty` default with `--exec`
49+
50+
- a description, for example:
51+
52+
> "cherry-pick" told to keep redundant commits needs to be allowed to
53+
> create empty commits to do its job, but it required the user to
54+
> give the --allow-empty option, which was unnecessary. Its UI has
55+
> also been tweaked a bit.
56+
57+
- a status, for example:
58+
59+
> Comments?
60+
61+
- a source, for example:
62+
63+
> source: <[email protected]>
64+
65+
Some of the above elements, like the description, are also
66+
automatically used to create the release notes that Junio prepares
67+
and sends when he creates a new release.
68+
69+
Brian Lyles, replied to Junio that the description of the patch
70+
series used as an example above, which Brian had sent, was "a little
71+
out-of-date". He suggested a different wording for it, and said that
72+
he was going to send a version 4 of the series.
73+
74+
Junio replied that the wording suggestion for the description was
75+
very much appreciated, and wondered if the project could adopt a
76+
better workflow where contributors could write a short description
77+
at the top of the cover letter of their patch series and that
78+
description could be packed up automatically by some tools to appear
79+
in Junio's "What's cooking in git.git" emails.
80+
81+
Brian Lyles replied that he agreed improving the process could be a
82+
good idea. He mentioned a strategy used by other projects which
83+
consists in adding an entry in a "CHANGELOG.NEXT.md" file in each
84+
important enough commit. At release time all the entries in that
85+
file would be moved into a standard "CHANGELOG.md" file. He then
86+
showed how the entry in the "CHANGELOG.NEXT.md" file would look like
87+
for his series as an example.
88+
89+
Junio replied by summarizing the current process related to these
90+
descriptions and pointing to the
91+
["Documentation/howto/maintain-git.txt" file](https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt)
92+
which describes his workflow and says that maintaining these topic
93+
descriptions is his responsibility as the project maintainer. He
94+
then mentioned some downsides of giving that responsibility to the
95+
patch series authors.
96+
97+
One downside is that the description might be harder to read because
98+
the authors "inevitably are biased by the importance of their own
99+
work ;-)". Another one is that the description might not be as
100+
consistent as when they are all written by the same person. Coming
101+
up with some description is also "a good opportunity" for the
102+
maintainer to find what is still unclear after reading the patches
103+
and cover letter. Junio agreed that "the distribution of burden is
104+
certainly attractive" though.
105+
106+
Brain replied that he thought the author should still write
107+
something and that at least he was willing to do it. He also
108+
suggested having guidelines, like for commit messages, to help
109+
authors and reviewers standardize the style of these descriptions.
110+
111+
In the meantime, in a separate email, Junio also replied that a
112+
"CHANGELOG.NEXT.md" file would make merges more difficult compared
113+
to having the description in the cover letter.
114+
115+
To that Brian agreed, and proposed writing a patch to the
116+
"Documentation/SubmittingPatches" file to document that the
117+
description can be written in the cover letter.
118+
119+
Junio replied by proposing a patch to that file himself. Brian
120+
commented that the description might need "some specific heading,
121+
phrase, or other structured text" to mark the description and make
122+
it easy to notice and extract.
123+
124+
Dragan Simic chimed into the discussion saying that writing the
125+
description should not be a strict requirement and then agreed with
126+
Junio's patch. Max Gautier also chimed in, agreeing with Brian and
127+
Dragan about using a format to mark the description. Dragan replied
128+
that adding an example of such a formatted description in the patch
129+
Junio suggested would be good.
130+
131+
Junio replied to Brian that he preferred starting "with a
132+
lightweight process that does not burden participants with too much
133+
red tape", so something like "When the first paragraph of the
134+
message looks like an entry in the Release Notes, it is used as
135+
such", as he thought that the Release Notes style was "distinct
136+
enough" as to "not require any further marking".
137+
138+
As Junio's patch was then merged, it's now
139+
[officially possible to write a short description](https://github.com/git/git/blob/v2.45.0-rc1/Documentation/SubmittingPatches#L462-L472)
140+
in patches or cover letters. This description might then be used
141+
as-is in the "What's cooking in git.git" emails and in the release
142+
notes.
23143

24144
<!---
25145
### Reviews
@@ -80,4 +200,4 @@ Christian Couder &lt;<[email protected]>&gt;,
80200
Jakub Narębski &lt;<[email protected]>&gt;,
81201
Markus Jansen &lt;<[email protected]>&gt; and
82202
Kaartic Sivaraam &lt;<[email protected]>&gt;
83-
with help from Adam Johnson.
203+
with help from Junio Hamano and Adam Johnson.

0 commit comments

Comments
 (0)