Addendum to "MaintNotes"
Add "how to maintain git" document. Foreward by Jeff King. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Nov 22, 2007 at 06:08 UTC
31e7bded608416e3116f9c691a4d4314f10640b6
1 file changed
+277
Documentation/howto/maintain-git.txt
new
+277
@@ -0,0 +1,277 @@
1
+From: Junio C Hamano <gitster@pobox.com>
2
+Date: Wed, 21 Nov 2007 16:32:55 -0800
3
+Subject: Addendum to "MaintNotes"
4
+Abstract: Imagine that git development is racing along as usual, when our friendly
5
+ neighborhood maintainer is struck down by a wayward bus. Out of the
6
+ hordes of suckers (loyal developers), you have been tricked (chosen) to
7
+ step up as the new maintainer. This howto will show you "how to" do it.
8
+
9
+The maintainer's git time is spent on three activities.
10
+
11
+ - Communication (60%)
12
+
13
+ Mailing list discussions on general design, fielding user
14
+ questions, diagnosing bug reports; reviewing, commenting on,
15
+ suggesting alternatives to, and rejecting patches.
16
+
17
+ - Integration (30%)
18
+
19
+ Applying new patches from the contributors while spotting and
20
+ correcting minor mistakes, shuffling the integration and
21
+ testing branches, pushing the results out, cutting the
22
+ releases, and making announcements.
23
+
24
+ - Own development (10%)
25
+
26
+ Scratching my own itch and sending proposed patch series out.
27
+
28
+The policy on Integration is informally mentioned in "A Note
29
+from the maintainer" message, which is periodically posted to
30
+this mailing list after each feature release is made.
31
+
32
+The policy.
33
+
34
+ - Feature releases are numbered as vX.Y.Z and are meant to
35
+ contain bugfixes and enhancements in any area, including
36
+ functionality, performance and usability, without regression.
37
+
38
+ - Maintenance releases are numbered as vX.Y.Z.W and are meant
39
+ to contain only bugfixes for the corresponding vX.Y.Z feature
40
+ release and earlier maintenance releases vX.Y.Z.V (V < W).
41
+
42
+ - 'master' branch is used to prepare for the next feature
43
+ release. In other words, at some point, the tip of 'master'
44
+ branch is tagged with vX.Y.Z.
45
+
46
+ - 'maint' branch is used to prepare for the next maintenance
47
+ release. After the feature release vX.Y.Z is made, the tip
48
+ of 'maint' branch is set to that release, and bugfixes will
49
+ accumulate on the branch, and at some point, the tip of the
50
+ branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on.
51
+
52
+ - 'next' branch is used to publish changes (both enhancements
53
+ and fixes) that (1) have worthwhile goal, (2) are in a fairly
54
+ good shape suitable for everyday use, (3) but have not yet
55
+ demonstrated to be regression free. New changes are tested
56
+ in 'next' before merged to 'master'.
57
+
58
+ - 'pu' branch is used to publish other proposed changes that do
59
+ not yet pass the criteria set for 'next'.
60
+
61
+ - The tips of 'master', 'maint' and 'next' branches will always
62
+ fast forward, to allow people to build their own
63
+ customization on top of them.
64
+
65
+ - Usually 'master' contains all of 'maint', 'next' contains all
66
+ of 'master' and 'pu' contains all of 'next'.
67
+
68
+ - The tip of 'master' is meant to be more stable than any
69
+ tagged releases, and the users are encouraged to follow it.
70
+
71
+ - The 'next' branch is where new action takes place, and the
72
+ users are encouraged to test it so that regressions and bugs
73
+ are found before new topics are merged to 'master'.
74
+
75
+
76
+A typical git day for the maintainer implements the above policy
77
+by doing the following:
78
+
79
+ - Scan mailing list and #git channel log. Respond with review
80
+ comments, suggestions etc. Kibitz. Collect potentially
81
+ usable patches from the mailing list. Patches about a single
82
+ topic go to one mailbox (I read my mail in Gnus, and type
83
+ \C-o to save/append messages in files in mbox format).
84
+
85
+ - Review the patches in the saved mailboxes. Edit proposed log
86
+ message for typofixes and clarifications, and add Acks
87
+ collected from the list. Edit patch to incorporate "Oops,
88
+ that should have been like this" fixes from the discussion.
89
+
90
+ - Classify the collected patches and handle 'master' and
91
+ 'maint' updates:
92
+
93
+ - Obviously correct fixes that pertain to the tip of 'maint'
94
+ are directly applied to 'maint'.
95
+
96
+ - Obviously correct fixes that pertain to the tip of 'master'
97
+ are directly applied to 'master'.
98
+
99
+ This step is done with "git am".
100
+
101
+ $ git checkout master ;# or "git checkout maint"
102
+ $ git am -3 -s mailbox
103
+ $ make test
104
+
105
+ - Merge downwards (maint->master):
106
+
107
+ $ git checkout master
108
+ $ git merge maint
109
+ $ make test
110
+
111
+ - Review the last issue of "What's cooking" message, review the
112
+ topics scheduled for merging upwards (topic->master and
113
+ topic->maint), and merge.
114
+
115
+ $ git checkout master ;# or "git checkout maint"
116
+ $ git merge ai/topic ;# or "git merge ai/maint-topic"
117
+ $ git log -p ORIG_HEAD.. ;# final review
118
+ $ git diff ORIG_HEAD.. ;# final review
119
+ $ make test ;# final review
120
+ $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic"
121
+
122
+ - Merge downwards (maint->master) if needed:
123
+
124
+ $ git checkout master
125
+ $ git merge maint
126
+ $ make test
127
+
128
+ - Merge downwards (master->next) if needed:
129
+
130
+ $ git checkout next
131
+ $ git merge master
132
+ $ make test
133
+
134
+ - Handle the remaining patches:
135
+
136
+ - Anything unobvious that is applicable to 'master' (in other
137
+ words, does not depend on anything that is still in 'next'
138
+ and not in 'master') is applied to a new topic branch that
139
+ is forked from the tip of 'master'. This includes both
140
+ enhancements and unobvious fixes to 'master'. A topic
141
+ branch is named as ai/topic where "ai" is typically
142
+ author's initial and "topic" is a descriptive name of the
143
+ topic (in other words, "what's the series is about").
144
+
145
+ - An unobvious fix meant for 'maint' is applied to a new
146
+ topic branch that is forked from the tip of 'maint'. The
147
+ topic is named as ai/maint-topic.
148
+
149
+ - Changes that pertain to an existing topic are applied to
150
+ the branch, but:
151
+
152
+ - obviously correct ones are applied first;
153
+
154
+ - questionable ones are discarded or applied to near the tip;
155
+
156
+ - Replacement patches to an existing topic are accepted only
157
+ for commits not in 'next'.
158
+
159
+ The above except the "replacement" are all done with:
160
+
161
+ $ git am -3 -s mailbox
162
+
163
+ while patch replacement is often done by:
164
+
165
+ $ git format-patch ai/topic~$n..ai/topic ;# export existing
166
+
167
+ then replace some parts with the new patch, and reapplying:
168
+
169
+ $ git reset --hard ai/topic~$n
170
+ $ git am -3 -s 000*.txt
171
+
172
+ The full test suite is always run for 'maint' and 'master'
173
+ after patch application; for topic branches the tests are run
174
+ as time permits.
175
+
176
+ - Update "What's cooking" message to review the updates to
177
+ existing topics, newly added topics and graduated topics.
178
+
179
+ This step is helped with Meta/UWC script (where Meta/ contains
180
+ a checkout of the 'todo' branch).
181
+
182
+ - Merge topics to 'next'. For each branch whose tip is not
183
+ merged to 'next', one of three things can happen:
184
+
185
+ - The commits are all next-worthy; merge the topic to next:
186
+
187
+ $ git checkout next
188
+ $ git merge ai/topic ;# or "git merge ai/maint-topic"
189
+ $ make test
190
+
191
+ - The new parts are of mixed quality, but earlier ones are
192
+ next-worthy; merge the early parts to next:
193
+
194
+ $ git checkout next
195
+ $ git merge ai/topic~2 ;# the tip two are dubious
196
+ $ make test
197
+
198
+ - Nothing is next-worthy; do not do anything.
199
+
200
+ - Rebase topics that do not have any commit in next yet. This
201
+ step is optional but sometimes is worth doing when an old
202
+ series that is not in next can take advantage of low-level
203
+ framework change that is merged to 'master' already.
204
+
205
+ $ git rebase master ai/topic
206
+
207
+ This step is helped with Meta/git-topic.perl script to
208
+ identify which topic is rebaseable. There also is a
209
+ pre-rebase hook to make sure that topics that are already in
210
+ 'next' are not rebased beyond the merged commit.
211
+
212
+ - Rebuild "pu" to merge the tips of topics not in 'next'.
213
+
214
+ $ git checkout pu
215
+ $ git reset --hard next
216
+ $ git merge ai/topic ;# repeat for all remaining topics
217
+ $ make test
218
+
219
+ This step is helped with Meta/PU script
220
+
221
+ - Push four integration branches to a private repository at
222
+ k.org and run "make test" on all of them.
223
+
224
+ - Push four integration branches to /pub/scm/git/git.git at
225
+ k.org. This triggers its post-update hook which:
226
+
227
+ (1) runs "git pull" in $HOME/git-doc/ repository to pull
228
+ 'master' just pushed out;
229
+
230
+ (2) runs "make doc" in $HOME/git-doc/, install the generated
231
+ documentation in staging areas, which are separate
232
+ repositories that have html and man branches checked
233
+ out.
234
+
235
+ (3) runs "git commit" in the staging areas, and run "git
236
+ push" back to /pub/scm/git/git.git/ to update the html
237
+ and man branches.
238
+
239
+ (4) installs generated documentation to /pub/software/scm/git/docs/
240
+ to be viewed from http://www.kernel.org/
241
+
242
+ - Fetch html and man branches back from k.org, and push four
243
+ integration branches and the two documentation branches to
244
+ repo.or.cz
245
+
246
+
247
+Some observations to be made.
248
+
249
+ * Each topic is tested individually, and also together with
250
+ other topics cooking in 'next'. Until it matures, none part
251
+ of it is merged to 'master'.
252
+
253
+ * A topic already in 'next' can get fixes while still in
254
+ 'next'. Such a topic will have many merges to 'next' (in
255
+ other words, "git log --first-parent next" will show many
256
+ "Merge ai/topic to next" for the same topic.
257
+
258
+ * An unobvious fix for 'maint' is cooked in 'next' and then
259
+ merged to 'master' to make extra sure it is Ok and then
260
+ merged to 'maint'.
261
+
262
+ * Even when 'next' becomes empty (in other words, all topics
263
+ prove stable and are merged to 'master' and "git diff master
264
+ next" shows empty), it has tons of merge commits that will
265
+ never be in 'master'.
266
+
267
+ * In principle, "git log --first-parent master..next" should
268
+ show nothing but merges (in practice, there are fixup commits
269
+ and reverts that are not merges).
270
+
271
+ * Commits near the tip of a topic branch that are not in 'next'
272
+ are fair game to be discarded, replaced or rewritten.
273
+ Commits already merged to 'next' will not be.
274
+
275
+ * Being in the 'next' branch is not a guarantee for a topic to
276
+ be included in the next feature release. Being in the
277
+ 'master' branch typically is.