MaintNotes: spring cleaning
Junio C Hamano committed
Mar 20, 2024 at 09:01 UTC
ff5dce782f51d7380525b625fed84cb0325e2cbd
2 files changed
+146
-115
MaintNotes
+88
-80
@@ -6,15 +6,14 @@ Welcome to the Git development community.
6
This message is written by the maintainer and talks about how Git
7
project is managed, and how you can work with it.
8
9
-The current maintainer is Junio C Hamano <gitster@pobox.com>; please
10
-do not send any message to this address unless it also goes to the
11
-mailing list, because it is likely that such a message will not be
12
-seen by any human being. Spam filters learned that legitimate
13
-messages to the address come only from a very few sender addresses
14
-that are known to be good, and messages from all others are likely to
15
-be spam unless they are also sent to the mailing list at the same time
16
-(i.e. "Reply-all" to the list message would reach the mailbox, but
17
-"Reply" will likely be thrown into the spam folder).
9
+The current maintainer is Junio C Hamano <gitster@pobox.com>. Spam
10
+filters learned that legitimate messages come only from a very few
11
+sender addresses that are known to be good to this address, and all
12
+other messages are likely to be spam unless they are also sent to the
13
+mailing list at the same time (i.e. "Reply-all" to the list message
14
+would reach the mailbox, but "Reply" will likely be thrown into the
15
+spam folder), so please do not send a message to this address unless
16
+it is also sent to the mailing list as well.
17
18
19
* Mailing list and the community
@@ -45,9 +44,9 @@ becomes calmer before sending such a reminder.
44
45
The list archive is available at a few public sites:
46
48
- http://lore.kernel.org/git/
49
- http://marc.info/?l=git
50
- http://www.spinics.net/lists/git/
47
+ https://lore.kernel.org/git/
48
+ https://marc.info/?l=git
49
+ https://www.spinics.net/lists/git/
50
51
For those who prefer to read it over NNTP:
52
@@ -60,7 +59,7 @@ When you point at a message in a mailing list archive, using its
59
message ID is often the most robust (if not very friendly) way to do
60
so, like this:
61
63
- http://lore.kernel.org/git/Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org
62
+ https://lore.kernel.org/git/Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org
63
64
Often these web interfaces accept the message ID with enclosing <>
65
stripped (like the above example to point at one of the most important
@@ -70,11 +69,11 @@ Some members of the development community can sometimes be found on
69
the #git and #git-devel IRC channels on Libera Chat. Their logs are
70
available at:
71
73
- http://colabti.org/irclogger/irclogger_log/git
74
- http://colabti.org/irclogger/irclogger_log/git-devel
72
+ https://colabti.org/ircloggy/git/last
73
+ https://colabti.org/ircloggy/git-devel/last
74
75
There is a volunteer-run newsletter to serve our community ("Git Rev
77
-News" http://git.github.io/rev_news/).
76
+News" https://git.github.io/rev_news/).
77
78
Git is a member project of software freedom conservancy, a non-profit
79
organization (https://sfconservancy.org/). To reach a committee of
@@ -94,8 +93,8 @@ your bug report with just "git does not work". "I used git in this
93
way, but it did not work" is not much better, neither is "I used git
94
in this way, and X happend, which is broken". It often is that git is
95
correct to cause X happen in such a case, and it is your expectation
97
-that is broken. People would not know what other result Y you expected
98
-to see instead of X, if you left it unsaid.
96
+that is broken. People would not know what other result Y you
97
+expected to see instead of X, if you left it unsaid.
98
99
Please remember to always state
100
@@ -110,7 +109,7 @@ Please remember to always state
109
110
- how the last two are different.
111
113
-See http://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further
112
+See https://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further
113
hints. Our `git bugreport` tool gives you a handy way you can use to
114
make sure you do not forget these points when filing a bug report.
115
@@ -145,9 +144,9 @@ individual topics broken out:
144
145
A few web interfaces are found at:
146
148
- http://git.kernel.org/pub/scm/git/git.git
147
+ https://git.kernel.org/pub/scm/git/git.git
148
https://kernel.googlesource.com/pub/scm/git/git
150
- http://repo.or.cz/w/alt-git.git
149
+ https://repo.or.cz/w/alt-git.git
150
151
Preformatted documentation from the tip of the "master" branch can be
152
found in:
@@ -168,77 +167,81 @@ There are four "integration" branches in git.git repository that track
167
the source tree of git: "master", "maint", "next", and "seen". They
168
however almost never get new commits made directly on them. Instead,
169
a branch is forked from either "master" or "maint" for each "topic",
171
-whether it is a new feature or fix for a bug, and holds a set of
172
-commits that belong to the same theme, and then such a "topic branch"
173
-is merged to these integration branches.
170
+whether it is a new feature or a fix for a bug, and holds a set of
171
+commits that belong to the same theme. Such a "topic branch" is then
172
+merged to these integration branches.
173
174
The "master" branch is meant to contain what are very well tested and
175
ready to be used in a production setting. Every now and then, a
176
"feature release" is cut from the tip of this branch. They used to be
178
-named with three dotted decimal digits (e.g. "1.8.5"), but we have
177
+named with three dotted decimal digits (e.g., "1.8.5"), but we have
178
switched the versioning scheme and "feature releases" are named with
180
-three-dotted decimal digits that ends with ".0" (e.g. "1.9.0").
179
+three-dotted decimal digits that ends with ".0" (e.g., "1.9.0").
180
182
-The last such release was 2.40 done on Mar 13rd, 2023. You can expect
181
+The last such release was 2.44 done on Feb 22nd, 2024. We aim to keep
182
that the tip of the "master" branch is always more stable than any of
183
the released versions.
184
185
Whenever a feature release is made, "maint" branch is forked off from
186
"master" at that point. Obvious and safe fixes after a feature
187
release are merged to this branch and maintenance releases are cut
189
-from it. Usually these fixes are merged to the "master" branch first,
190
-several days before merged to the "maint" branch, to reduce the chance
191
-of last-minute issues, but things like embargoed security fixes may
192
-first appear in the maintenance tracks and merged up to "master" at
193
-the same time. The maintenance releases used to be named with
194
-four dotted decimal, named after the feature release they are updates
195
-to (e.g. "1.8.5.1" was the first maintenance release for "1.8.5"
196
-feature release). These days, maintenance releases are named by
197
-incrementing the last digit of three-dotted decimal name (e.g.
198
-"2.29.2" was the second maintenance release for the "2.29" series).
199
-
200
-New features never go to the "maint" branch. It is merged into
188
+from it. Usually the topic branches that contain these fixes are
189
+merged to the "master" branch first, before getting merged to the
190
+"maint" branch, to reduce the chance of last-minute issues, but
191
+things like embargoed security fixes may first appear in the "maint"
192
+and merged up to "master" at the same time. The maintenance releases
193
+used to be named with four dotted decimal, named after the feature
194
+release they are updates to (e.g., "1.8.5.1" was the first maintenance
195
+release for "1.8.5" feature release). These days, maintenance releases
196
+are named by incrementing the last digit of three-dotted decimal name
197
+(e.g., "2.43.2" was the second maintenance release for the "2.43" series).
198
+
199
+New features almost never go to the "maint" branch. It is merged into
200
"master" primarily to propagate the description in the release notes
201
forward.
202
204
-A new development does not usually happen on "master". When you send a
205
-series of patches, after review on the mailing list, a separate topic
206
-branch is forked from the tip of "master" (or somewhere older, especially
207
-when the topic is about fixing an earlier bug) and your patches are queued
208
-there, and kept out of "master" while people test it out. The quality of
209
-topic branches are judged primarily by the mailing list discussions.
210
-
211
-Topic branches that are in good shape are merged to the "next" branch. In
212
-general, the "next" branch always contains the tip of "master". It might
213
-not be quite rock-solid, but is expected to work more or less without major
214
-breakage. The "next" branch is where new and exciting things take place. A
215
-topic that is in "next" is expected to be polished to perfection before it
216
-is merged to "master". Please help this process by building & using the
217
-"next" branch for your daily work, and reporting any new bugs you find to
218
-the mailing list, before the breakage is merged down to the "master".
219
-
220
-The "seen" (formerly "pu", proposed updates) branch bundles all the
221
-remaining topic branches the maintainer happens to have seen. There
222
-is no guarantee that the maintainer has enough bandwidth to pick up any
223
-and all topics that are remotely promising from the list traffic, so
224
-please do not read too much into a topic being on (or not on) the "seen"
225
-branch. This branch is mainly to remind the maintainer that the topics
226
-in them may turn out to be interesting when they are polished, nothing
227
-more, but can be used by contributors to anticipate what topics from
228
-others may cause conflict with your work, and find people who are working.
229
-on these topics to talk to before the potential conflicts get out of
230
-control. The topics on this branch aren't usually complete, well tested,
231
-or well documented and they often need further work. When a topic that
232
-was in "seen" proves to be in a testable shape, it is merged to "next".
233
-
234
-You can run "git log --first-parent master..seen" to see what topics are
235
-currently in flight. Sometimes, an idea that looked promising turns out
236
-to be not so good and the topic can be dropped from "seen" in such a case.
237
-The output of the above "git log" talks about a "jch" branch, which is an
238
-early part of the "seen" branch; that branch contains all topics that
239
-are in "next" and a bit more (but not all of "seen") and is used by the
240
-maintainer for his daily work. Using the tip of this branch, instead of
241
-'next', as your daily driver is also recommended.
203
+When you send a series of patches, after review discussions on the
204
+mailing list, a separate topic branch is forked from the tip of
205
+"master" (or somewhere older, especially when the topic is about
206
+fixing an earlier bug) and your patches are applied on that topic
207
+branch, and kept out of "master" while people test it out. The
208
+quality of topic branches are judged primarily by the mailing list
209
+discussions.
210
+
211
+Topic branches that are in good shape are merged to the "next" branch.
212
+The "next" branch is where new and exciting things take place. In
213
+general, the "next" branch always contains the tip of "master". It
214
+might not be quite rock-solid, but is expected to work more or less
215
+without major breakage. A topic that is in "next" is expected to be
216
+polished to perfection before it is merged to "master". Please help
217
+this process by building & using the "next" branch for your daily
218
+work, and reporting any new bugs you find to the mailing list, before
219
+the breakage is merged down to the "master".
220
+
221
+The "seen" (formerly "pu", proposed updates) branch bundles the
222
+remaining topic branches the maintainer happens to have seen to remind
223
+the maintainer that the topics in them might become interesting when
224
+they are polished.
225
+
226
+The contributors can use it to anticipate what topics from others
227
+may cause conflict with their own work, and find people who are
228
+working on these topics to talk to before the potential conflicts
229
+get out of control. It would be a good idea to fork from maint or
230
+master to grow a topic and to test (1) it by itself, (2) a temporary
231
+merge of it to 'next' and (3) a temporary merge to it to 'seen',
232
+before publishing it.
233
+
234
+Consider that a topic only in "seen" is not part of "git" yet. When a
235
+topic that was in "seen" proves to be in a testable shape, it is
236
+merged to "next".
237
+
238
+You can run "git log --first-parent master..seen" to see what topics
239
+are currently in flight. Sometimes, a topic that looked promising
240
+proves to be a bad idea and the topic gets dropped from "seen" in such
241
+a case. The output of the above "git log" talks about a "jch" branch,
242
+which is an early part of the "seen" branch; that branch contains all
243
+topics that are in "next" and a bit more (but not all of "seen") and
244
+is used by the maintainer for his daily work.
245
246
The two branches "master" and "maint" are never rewound, and "next"
247
usually will not be either. After a feature release is made from
@@ -249,10 +252,15 @@ get ejected from "next" when this happens.
252
253
A natural consequence of how "next" and "seen" bundles topics together
254
is that until a topic is merged to "next", updates to it is expected
252
-by replacing the patch(es) in the topic with an improved version,
253
-and once a topic is merged to "next", updates to it needs to come as
255
+by replacing the patch(es) in the topic with an improved version, and
256
+once a topic is merged to "next", updates to it needs to come as
257
incremental patches, pointing out what was wrong in the previous
255
-patches and how the problem was corrected.
258
+patches and how the problem was corrected. The idea is that if many
259
+reviewers thought it has seen enough eyeballs and is good enough for
260
+"next", yet we later find that there was something we all missed, that
261
+is worth a separate explanation, e.g., "The primary motivation behind
262
+the series is still good, but for such and such reasons we missed this
263
+case we are fixing.", hence we prefer follow-up incremental patches.
264
265
Note that being in "next" is not a guarantee to appear in the next
266
release, nor even in any future release. There were cases that topics
whats-cooking.txt
+58
-35
@@ -1,10 +1,10 @@
1
To: git@vger.kernel.org
2
-Subject: What's cooking in git.git (Mar 2024, #05; Tue, 19)
2
+Subject: What's cooking in git.git (Mar 2024, #06; Wed, 20)
3
X-master-at: 3bd955d26919e149552f34aacf8a4e6368c26cec
4
X-next-at: fe251e3e4dec6a6d677e61d53b316c06da172af2
5
Bcc: lwn@lwn.net, gitster@pobox.com
6
7
-What's cooking in git.git (Mar 2024, #05; Tue, 19)
7
+What's cooking in git.git (Mar 2024, #06; Wed, 20)
8
--------------------------------------------------
9
10
Here are the topics that have been cooking in my tree. Commits
@@ -46,40 +46,61 @@ Release tarballs are available at:
46
https://www.kernel.org/pub/software/scm/git/
47
48
--------------------------------------------------
49
-[Graduated to 'master']
49
+[New Topics]
50
51
-* jh/trace2-missing-def-param-fix (2024-03-07) 3 commits
52
- (merged to 'next' on 2024-03-08 at a797cfea3c)
53
- + trace2: emit 'def_param' set with 'cmd_name' event
54
- + trace2: avoid emitting 'def_param' set more than once
55
- + t0211: demonstrate missing 'def_param' events for certain commands
51
+* dg/myfirstobjectwalk-updates (2024-03-19) 5 commits
52
+ - MyFirstObjectWalk: add stderr to pipe processing
53
+ - MyFirstObjectWalk: fix description for counting omitted objects
54
+ - MyFirstObjectWalk: fix filtered object walk
55
+ - MyFirstObjectWalk: fix misspelled "builtins/"
56
+ - MyFirstObjectWalk: use additional arg in config_fn_t
57
57
- Some trace2 events that lacked def_param have learned to show it,
58
- enriching the output.
58
+ Update a more recent tutorial doc.
59
60
- Reviewed-by: Josh Steadmon <steadmon@google.com>
61
- cf. <ZejkVOVQBZhLVfHW@google.com>
62
- source: <pull.1679.v2.git.1709824949.gitgitgadget@gmail.com>
60
+ Needs review.
61
+ source: <cover.1710840596.git.dirk@gouders.net>
62
+
63
+
64
+* ds/config-internal-whitespace-fix (2024-03-19) 4 commits
65
+ - config.txt: describe handling of whitespace further
66
+ - t1300: add more tests for whitespace and inline comments
67
+ - config: really keep value-internal whitespace verbatim
68
+ - config: minor addition of whitespace
69
70
+ "git config" corrupted literal HT characters written in the
71
+ configuration file as part of a value, which has been corrected.
72
65
-* jk/doc-remote-helpers-markup-fix (2024-03-07) 1 commit
66
- (merged to 'next' on 2024-03-08 at 2cded1c696)
67
- + doc/gitremote-helpers: fix missing single-quote
73
+ Expecting a reroll. Almost there.
74
+ source: <cover.1710800549.git.dsimic@manjaro.org>
75
69
- Doc mark-up fix.
70
- source: <20240307084313.GA2072022@coredump.intra.peff.net>
76
+
77
+* jc/apply-parse-diff-git-header-names-fix (2024-03-19) 1 commit
78
+ - apply: parse names out of "diff --git" more carefully
79
+
80
+ "git apply" failed to extract the filename the patch applied to,
81
+ when the change was about an empty file created in or deleted from
82
+ a directory whose name ends with a SP, which has been corrected.
83
+
84
+ Needs review.
85
+ source: <xmqqfrwlltjn.fsf@gitster.g>
86
87
73
-* pw/rebase-i-ignore-cherry-pick-help-environment (2024-02-27) 1 commit
74
- (merged to 'next' on 2024-03-08 at e806ee9493)
75
- + rebase -i: stop setting GIT_CHERRY_PICK_HELP
88
+* jk/pretty-subject-cleanup (2024-03-19) 6 commits
89
+ - format-patch: simplify after-subject MIME header handling
90
+ - format-patch: return an allocated string from log_write_email_headers()
91
+ - log: do not set up extra_headers for non-email formats
92
+ - pretty: drop print_email_subject flag
93
+ - pretty: split oneline and email subject printing
94
+ - shortlog: stop setting pp.print_email_subject
95
77
- Code simplification by getting rid of code that sets an environment
78
- variable that is no longer used.
79
- source: <pull.1678.git.1709042783847.gitgitgadget@gmail.com>
96
+ Code clean-up in the "git log" machinery that implements custom log
97
+ message formatting.
98
+
99
+ Will merge to 'next'.
100
+ source: <20240320002555.GB903718@coredump.intra.peff.net>
101
102
--------------------------------------------------
82
-[New Topics]
103
+[Cooking]
104
105
* bb/sh-scripts-cleanup (2024-03-16) 22 commits
106
(merged to 'next' on 2024-03-18 at 4501a04796)
@@ -207,8 +228,6 @@ Release tarballs are available at:
228
Needs review.
229
source: <cover.1710706118.git.ps@pks.im>
230
210
---------------------------------------------------
211
-[Cooking]
231
232
* bb/iso-strict-utc (2024-03-13) 1 commit
233
(merged to 'next' on 2024-03-14 at d2ac616873)
@@ -402,24 +421,28 @@ Release tarballs are available at:
421
- docs: clean up `--empty` formatting in git-rebase(1) and git-am (1)
422
- docs: address inaccurate `--empty` default with `--exec`
423
405
- "cherry-pick" told to keep redundant commits needs to be allowed to
406
- create empty commits to do its job, but it required the user to
407
- give the --allow-empty option, which was unnecessary. Its UI has
408
- also been tweaked a bit.
424
+ Allow git-cherry-pick(1) to automatically drop redundant commits via
425
+ a new `--empty` option, similar to the `--empty` options for
426
+ git-rebase(1) and git-am(1). Includes a soft deprecation of
427
+ `--keep-redundant-commits` as well as some related docs changes and
428
+ sequencer code cleanup.
429
410
- Comments?
430
+ Expecting a reroll.
431
+ cf. <17be81eb83ff314d.70b1dd9aae081c6e.203dcd72f6563036@zivdesk>
432
source: <20240119060721.3734775-2-brianmlyles@gmail.com>
433
434
414
-* ie/config-includeif-hostname (2024-03-10) 1 commit
435
+* ie/config-includeif-hostname (2024-03-19) 2 commits
436
- config: learn the "hostname:" includeIf condition
437
+ - t: add a test helper for getting hostname
438
439
The conditional inclusion mechanism for configuration files learned
440
to switch on the hostname.
441
442
Expecting a reroll.
421
- cf. <fda3e8f4-fd9e-4a43-a307-c6607d982436@iencinas.com>
422
- source: <20240309181828.45496-2-ignacio@iencinas.com>
443
+ cf. <20240319210428.GC1159535@coredump.intra.peff.net>
444
+ cf. <20240320001934.GA903718@coredump.intra.peff.net>
445
+ source: <20240319183722.211300-1-ignacio@iencinas.com>
446
447
448
* ja/doc-markup-fixes (2024-03-11) 6 commits