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 <gitster@pobox.com>
Junio C Hamano committed
Mar 6, 2020 at 09:23 UTC
564956f358c6db7cb565eb973e8768004667ad94
1 file changed
+39
-13
Documentation/howto/maintain-git.txt
+39
-13
@@ -154,15 +154,17 @@ by doing the following:
154
- Anything unobvious that is applicable to 'master' (in other
155
words, does not depend on anything that is still in 'next'
156
and not in 'master') is applied to a new topic branch that
157
- is forked from the tip of 'master'. This includes both
157
+ is forked from the tip of 'master' (or the last feature release,
158
+ which is a bit older than 'master'). This includes both
159
enhancements and unobvious fixes to 'master'. A topic
160
branch is named as ai/topic where "ai" is two-letter string
161
named after author's initial and "topic" is a descriptive name
162
of the topic (in other words, "what's the series is about").
163
164
- An unobvious fix meant for 'maint' is applied to a new
164
- topic branch that is forked from the tip of 'maint'. The
165
- topic is named as ai/maint-topic.
165
+ topic branch that is forked from the tip of 'maint' (or the
166
+ oldest and still relevant maintenance branch). The
167
+ topic may be named as ai/maint-topic.
168
169
- Changes that pertain to an existing topic are applied to
170
the branch, but:
@@ -174,24 +176,40 @@ by doing the following:
176
- Replacement patches to an existing topic are accepted only
177
for commits not in 'next'.
178
177
- The above except the "replacement" are all done with:
179
+ The initial round is done with:
180
181
$ git checkout ai/topic ;# or "git checkout -b ai/topic master"
182
$ git am -sc3 mailbox
183
182
- while patch replacement is often done by:
184
+ and replacing an existing topic with subsequent round is done with:
185
184
- $ git format-patch ai/topic~$n..ai/topic ;# export existing
186
+ $ git checkout master...ai/topic ;# try to reapply to the same base
187
+ $ git am -sc3 mailbox
188
+
189
+ to prepare the new round on a detached HEAD, and then
190
+
191
+ $ git range-diff @{-1}...
192
+ $ git diff @{-1}
193
186
- then replace some parts with the new patch, and reapplying:
194
+ to double check what changed since the last round, and finally
195
188
- $ git checkout ai/topic
189
- $ git reset --hard ai/topic~$n
190
- $ git am -sc3 -s 000*.txt
196
+ $ git checkout -B @{-1}
197
+
198
+ to conclude (the last step is why a topic already in 'next' is
199
+ not replaced but updated incrementally).
200
+
201
+ Whether it is the initial round or a subsequent round, the topic
202
+ may not build even in isolation, or may break the build when
203
+ merged to integration branches due to bugs. There may already
204
+ be obvious and trivial improvements suggested on the list. The
205
+ maintainer often adds an extra commit, with "SQUASH???" in its
206
+ title, to fix things up, before publishing the integration
207
+ branches to make it usable by other developers for testing.
208
+ These changes are what the maintainer is not 100% committed to
209
+ (trivial typofixes etc. are often squashed directly into the
210
+ patches that need fixing, without being applied as a separate
211
+ "SQUASH???" commit), so that they can be removed easily as needed.
212
192
- The full test suite is always run for 'maint' and 'master'
193
- after patch application; for topic branches the tests are run
194
- as time permits.
213
214
- Merge maint to master as needed:
215
@@ -371,6 +389,14 @@ Some observations to be made.
389
be included in the next feature release. Being in the
390
'master' branch typically is.
391
392
+ * Due to the nature of "SQUASH???" fix-ups, if the original author
393
+ agrees with the suggested changes, it is OK to squash them to
394
+ appropriate patches in the next round (when the suggested change
395
+ is small enough, the author should not even bother with
396
+ "Helped-by"). It is also OK to drop them from the next round
397
+ when the original author does not agree with the suggestion, but
398
+ the author is expected to say why somewhere in the discussion.
399
+
400
401
Appendix
402
--------