path: root/Documentation/howto
diff options
authorJunio C Hamano <>2020-03-06 17:23:38 (GMT)
committerJunio C Hamano <>2020-03-09 14:57:57 (GMT)
commit564956f358c6db7cb565eb973e8768004667ad94 (patch)
tree56ea49fb866a43066a9a841a29b0c931c7500ae5 /Documentation/howto
parentd0654dc308b0ba76dd8ed7bbb33c8d8f7aacd783 (diff)
update how-to-maintain-git
Some parts of the workflow described in the document has got a bit stale with the recent toolchain improvements. Update the procedure a bit, and also describe the convention used around SQUASH??? fixups. Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/howto')
1 files changed, 39 insertions, 13 deletions
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index ca43787..73be8b4 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -154,15 +154,17 @@ by doing the following:
- Anything unobvious that is applicable to 'master' (in other
words, does not depend on anything that is still in 'next'
and not in 'master') is applied to a new topic branch that
- is forked from the tip of 'master'. This includes both
+ is forked from the tip of 'master' (or the last feature release,
+ which is a bit older than 'master'). This includes both
enhancements and unobvious fixes to 'master'. A topic
branch is named as ai/topic where "ai" is two-letter string
named after author's initial and "topic" is a descriptive name
of the topic (in other words, "what's the series is about").
- An unobvious fix meant for 'maint' is applied to a new
- topic branch that is forked from the tip of 'maint'. The
- topic is named as ai/maint-topic.
+ topic branch that is forked from the tip of 'maint' (or the
+ oldest and still relevant maintenance branch). The
+ topic may be named as ai/maint-topic.
- Changes that pertain to an existing topic are applied to
the branch, but:
@@ -174,24 +176,40 @@ by doing the following:
- Replacement patches to an existing topic are accepted only
for commits not in 'next'.
- The above except the "replacement" are all done with:
+ The initial round is done with:
$ git checkout ai/topic ;# or "git checkout -b ai/topic master"
$ git am -sc3 mailbox
- while patch replacement is often done by:
+ and replacing an existing topic with subsequent round is done with:
- $ git format-patch ai/topic~$ ;# export existing
+ $ git checkout ;# try to reapply to the same base
+ $ git am -sc3 mailbox
+ to prepare the new round on a detached HEAD, and then
+ $ git range-diff @{-1}...
+ $ git diff @{-1}
- then replace some parts with the new patch, and reapplying:
+ to double check what changed since the last round, and finally
- $ git checkout ai/topic
- $ git reset --hard ai/topic~$n
- $ git am -sc3 -s 000*.txt
+ $ git checkout -B @{-1}
+ to conclude (the last step is why a topic already in 'next' is
+ not replaced but updated incrementally).
+ Whether it is the initial round or a subsequent round, the topic
+ may not build even in isolation, or may break the build when
+ merged to integration branches due to bugs. There may already
+ be obvious and trivial improvements suggested on the list. The
+ maintainer often adds an extra commit, with "SQUASH???" in its
+ title, to fix things up, before publishing the integration
+ branches to make it usable by other developers for testing.
+ These changes are what the maintainer is not 100% committed to
+ (trivial typofixes etc. are often squashed directly into the
+ patches that need fixing, without being applied as a separate
+ "SQUASH???" commit), so that they can be removed easily as needed.
- The full test suite is always run for 'maint' and 'master'
- after patch application; for topic branches the tests are run
- as time permits.
- Merge maint to master as needed:
@@ -371,6 +389,14 @@ Some observations to be made.
be included in the next feature release. Being in the
'master' branch typically is.
+ * Due to the nature of "SQUASH???" fix-ups, if the original author
+ agrees with the suggested changes, it is OK to squash them to
+ appropriate patches in the next round (when the suggested change
+ is small enough, the author should not even bother with
+ "Helped-by"). It is also OK to drop them from the next round
+ when the original author does not agree with the suggestion, but
+ the author is expected to say why somewhere in the discussion.