howto-maintain: update daily tasks
Some "implementation details" of how I perform these integration tasks day to day have changed since the document was originally written. Update to reflect the way things are currently done. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jul 19, 2024 at 13:52 UTC
bb0498b1bbfccaa0b7d31494eab49a5aab2cc718
1 file changed
+63
-43
Documentation/howto/maintain-git.txt
+63
-43
@@ -211,12 +211,12 @@ by doing the following:
211
The initial round is done with:
212
213
$ git checkout ai/topic ;# or "git checkout -b ai/topic master"
214
- $ git am -sc3 mailbox
214
+ $ git am -sc3 --whitespace=warn mailbox
215
216
and replacing an existing topic with subsequent round is done with:
217
218
$ git checkout master...ai/topic ;# try to reapply to the same base
219
- $ git am -sc3 mailbox
219
+ $ git am -sc3 --whitespace=warn mailbox
220
221
to prepare the new round on a detached HEAD, and then
222
@@ -241,39 +241,59 @@ by doing the following:
241
(trivial typofixes etc. are often squashed directly into the
242
patches that need fixing, without being applied as a separate
243
"SQUASH???" commit), so that they can be removed easily as needed.
244
+ The expectation is that the original author will make corrections
245
+ in a reroll.
246
247
+ - By now, new topic branches are created and existing topic
248
+ branches are updated. The integration branches 'next', 'jch',
249
+ and 'seen' need to be updated to contain them.
250
246
- - Merge maint to master as needed:
251
+ - If there are topics that have been merged to 'master' and should
252
+ be merged to 'maint', merge them to 'maint', and update the
253
+ release notes to the next maintenance release.
254
248
- $ git checkout master
249
- $ git merge maint
250
- $ make test
255
+ - Review the latest issue of "What's cooking" again. Are topics
256
+ that have been sufficiently long in 'next' ready to be merged to
257
+ 'master'? Are topics we saw earlier and are in 'seen' now got
258
+ positive reviews and are ready to be merged to 'next'?
259
252
- - Merge master to next as needed:
260
+ - If there are topics that have been cooking in 'next' long enough
261
+ and should be merged to 'master', merge them to 'master', and
262
+ update the release notes to the next feature release.
263
254
- $ git checkout next
255
- $ git merge master
256
- $ make test
264
+ - If there were patches directly made on 'maint', merge 'maint' to
265
+ 'master'; make sure that the result is what you want.
266
258
- - Review the last issue of "What's cooking" again and see if topics
259
- that are ready to be merged to 'next' are still in good shape
260
- (e.g. has there any new issue identified on the list with the
261
- series?)
267
+ $ git checkout master
268
+ $ git merge -m "Sync with 'maint'" --no-log maint
269
+ $ git log -p --first-parent ORIG_HEAD..
270
+ $ make test
271
263
- - Prepare 'jch' branch, which is used to represent somewhere
264
- between 'master' and 'seen' and often is slightly ahead of 'next'.
272
+ - Prepare to update the 'jch' branch, which is used to represent
273
+ somewhere between 'master' and 'seen' and often is slightly ahead
274
+ of 'next', and the 'seen' branch, which is used to hold the rest.
275
276
$ Meta/Reintegrate master..jch >Meta/redo-jch.sh
277
278
The result is a script that lists topics to be merged in order to
269
- rebuild 'seen' as the input to Meta/Reintegrate script. Remove
270
- later topics that should not be in 'jch' yet. Add a line that
271
- consists of '### match next' before the name of the first topic
272
- in the output that should be in 'jch' but not in 'next' yet.
279
+ rebuild the current 'jch'. Do the same for 'seen'.
280
+
281
+ - Review the Meta/redo-jch.sh and Meta/redo-seen.sh scripts. The
282
+ former should have a line '### match next'---the idea is that
283
+ merging the topics listed before the line on top of 'master'
284
+ should result in a tree identical to that of 'next'.
285
274
- - Now we are ready to start merging topics to 'next'. For each
275
- branch whose tip is not merged to 'next', one of three things can
276
- happen:
286
+ - As newly created topics are usually merged near the tip of
287
+ 'seen', add them to the end of the Meta/redo-seen.sh script.
288
+ Among the topics that were in 'seen', there may be ones that
289
+ are not quite ready for 'next' but are getting there. Move
290
+ them from Meta/redo-seen.sh to the end of Meta/redo-jch.sh.
291
+ The expectation is that you'd use 'jch' as your daily driver
292
+ as the first guinea pig, so you should choose carefully.
293
+
294
+ - Now we are ready to start rebuilding 'jch' and merging topics to
295
+ 'next'. For each branch whose tip is not merged to 'next', one
296
+ of three things can happen:
297
298
- The commits are all next-worthy; merge the topic to next;
299
- The new parts are of mixed quality, but earlier ones are
@@ -284,10 +304,12 @@ by doing the following:
304
If a topic that was already in 'next' gained a patch, the script
305
would list it as "ai/topic~1". To include the new patch to the
306
updated 'next', drop the "~1" part; to keep it excluded, do not
287
- touch the line. If a topic that was not in 'next' should be
288
- merged to 'next', add it at the end of the list. Then:
307
+ touch the line.
308
+
309
+ If a topic that was not in 'next' should be merged to 'next', add
310
+ it before the '### match next' line. Then:
311
290
- $ git checkout -B jch master
312
+ $ git checkout --detach master
313
$ sh Meta/redo-jch.sh -c1
314
315
to rebuild the 'jch' branch from scratch. "-c1" tells the script
@@ -299,26 +321,29 @@ by doing the following:
321
reference to the variable under its old name), in which case
322
prepare an appropriate merge-fix first (see appendix), and
323
rebuild the 'jch' branch from scratch, starting at the tip of
302
- 'master'.
324
+ 'master', this time without using "-c1" to merge all topics.
325
304
- Then do the same to 'next'
326
+ Then do the same to 'next'.
327
328
$ git checkout next
329
$ sh Meta/redo-jch.sh -c1 -e
330
331
The "-e" option allows the merge message that comes from the
332
history of the topic and the comments in the "What's cooking" to
311
- be edited. The resulting tree should match 'jch' as the same set
312
- of topics are merged on 'master'; otherwise there is a mismerge.
313
- Investigate why and do not proceed until the mismerge is found
314
- and rectified.
333
+ be edited. The resulting tree should match 'jch^{/^### match next'}'
334
+ as the same set of topics are merged on 'master'; otherwise there
335
+ is a mismerge. Investigate why and do not proceed until the mismerge
336
+ is found and rectified.
337
316
- $ git diff jch next
338
+ If 'master' was updated before you started redoing 'next', then
339
318
- Then build the rest of 'jch':
340
+ $ git diff 'jch^{/^### match next}' next
341
320
- $ git checkout jch
321
- $ sh Meta/redo-jch.sh
342
+ would show differences that went into 'master' (which 'jch' has,
343
+ but 'next' does not yet---often it is updates to the release
344
+ notes). Merge 'master' back to 'next' if that is the case.
345
+
346
+ $ git merge -m "Sync with 'master'" --no-log master
347
348
When all is well, clean up the redo-jch.sh script with
349
@@ -328,12 +353,7 @@ by doing the following:
353
merged to 'master'. This may lose '### match next' marker;
354
add it again to the appropriate place when it happens.
355
331
- - Rebuild 'seen'.
332
-
333
- $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh
334
-
335
- Edit the result by adding new topics that are not still in 'seen'
336
- in the script. Then
356
+ - Rebuild 'seen' on top of 'jch'.
357
358
$ git checkout -B seen jch
359
$ sh Meta/redo-seen.sh
@@ -344,7 +364,7 @@ by doing the following:
364
365
Double check by running
366
347
- $ git branch --no-merged seen
367
+ $ git branch --no-merged seen '??/*'
368
369
to see there is no unexpected leftover topics.
370