SubmittingPatches: Add new section about what to base work on
Add a section 0 explaining which commit to base patches on. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ramkumar Ramachandra committed
Apr 19, 2010 at 01:24 UTC
d0c26f0f56444d93a08121bb1f3691b2bbbfb958
1 file changed
+38
-11
Documentation/SubmittingPatches
+38
-11
@@ -53,6 +53,34 @@ But the patch submission requirements are a lot more relaxed
53
here on the technical/contents front, because the core GIT is
54
thousand times smaller ;-). So here is only the relevant bits.
55
56
+(0) Decide what to base your work on.
57
+
58
+In general, always base your work on the oldest branch that your
59
+change is relevant to.
60
+
61
+ - A bugfix should be based on 'maint' in general. If the bug is not
62
+ present in 'maint', base it on 'master'. For a bug that's not yet
63
+ in 'master', find the topic that introduces the regression, and
64
+ base your work on the tip of the topic.
65
+
66
+ - A new feature should be based on 'master' in general. If the new
67
+ feature depends on a topic that is in 'pu', but not in 'master',
68
+ base your work on the tip of that topic.
69
+
70
+ - Corrections and enhancements to a topic not yet in 'master' should
71
+ be based on the tip of that topic. If the topic has not been merged
72
+ to 'next', it's alright to add a note to squash minor corrections
73
+ into the series.
74
+
75
+ - In the exceptional case that a new feature depends on several topics
76
+ not in 'master', start working on 'next' or 'pu' privately and send
77
+ out patches for discussion. Before the final merge, you may have to
78
+ wait until some of the dependent topics graduate to 'master', and
79
+ rebase your work.
80
+
81
+To find the tip of a topic branch, run "git log --first-parent
82
+master..pu" and look for the merge commit. The second parent of this
83
+commit is the tip of the topic branch.
84
85
(1) Make separate commits for logically separate changes.
86
@@ -170,17 +198,16 @@ patch, format it as "multipart/signed", not a text/plain message
198
that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
199
not a text/plain, it's something else.
200
173
-Note that your maintainer does not necessarily read everything
174
-on the git mailing list. If your patch is for discussion first,
175
-send it "To:" the mailing list, and optionally "cc:" him. If it
176
-is trivially correct or after the list reached a consensus, send
177
-it "To:" the maintainer and optionally "cc:" the list for
178
-inclusion.
179
-
180
-Also note that your maintainer does not actively involve himself in
181
-maintaining what are in contrib/ hierarchy. When you send fixes and
182
-enhancements to them, do not forget to "cc: " the person who primarily
183
-worked on that hierarchy in contrib/.
201
+Unless your patch is a very trivial and an obviously correct one,
202
+first send it with "To:" set to the mailing list, with "cc:" listing
203
+people who are involved in the area you are touching (the output from
204
+"git blame $path" and "git shortlog --no-merges $path" would help to
205
+identify them), to solicit comments and reviews. After the list
206
+reached a consensus that it is a good idea to apply the patch, re-send
207
+it with "To:" set to the maintainer and optionally "cc:" the list for
208
+inclusion. Do not forget to add trailers such as "Acked-by:",
209
+"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
210
+necessary.
211
212
213
(4) Sign your work