SubmittingPatches: extend the "flow" section
Explain a full lifecycle of a patch series upfront, so that it is clear when key decisions to "accept" a series is made and how a new patch series becomes a part of a new release. Fold the "you need to monitor the progress of your topic" section into the primary "patch lifecycle" section, as that is one of the things the patch submitter is responsible for. It is not like "I sent a patch and responded to review messages, and now it is their problem". They need to see their patch through the patch life cycle. Earlier versions of this document outlined a slightly different patch flow in an idealized world, where the original submitter gathered agreements from the participants of the discussion and sent the final "we all agreed that this is the good version--please apply" patches to the maintainer. In practice, this almost never happened. Instead, describe what flow was used in practice for the past decade that worked well for us. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
May 10, 2024 at 09:55 UTC
120adc7d3c2b9b25d009d3620f00ac3c0c5e1a8d
1 file changed
+61
-42
Documentation/SubmittingPatches
+61
-42
@@ -8,53 +8,71 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]
8
available which covers many of these same guidelines.
9
10
[[patch-flow]]
11
-=== An ideal patch flow
11
+=== A typical life cycle of a patch series
12
13
-Here is an ideal patch flow for this project the current maintainer
14
-suggests to the contributors:
13
+To help us understand the reason behind various guidelines given later
14
+in the document, first let's understand how the life cycle of a
15
+typical patch series for this project goes.
16
16
-. You come up with an itch. You code it up.
17
-
18
-. Send it to the list and cc people who may need to know about
19
- the change.
17
+. You come up with an itch. You code it up. You do not need any
18
+ pre-authorization from the project to do so.
19
++
20
+Your patches will be reviewed by other contributors on the mailing
21
+list, and the reviews will be done to assess the merit of various
22
+things, like the general idea behind your patch (including "is it
23
+solving a problem worth solving in the first place?"), the reason
24
+behind the design of the solution, and the actual implementation.
25
+The guidelines given here are there to help your patches by making
26
+them easier to understand by the reviewers.
27
+
28
+. You send the patches to the list and cc people who may need to know
29
+ about the change. Your goal is *not* necessarily to convince others
30
+ that what you are building is good. Your goal is to get help in
31
+ coming up with a solution for the "itch" that is better than what
32
+ you can build alone.
33
+
21
-The people who may need to know are the ones whose code you
22
-are butchering. These people happen to be the ones who are
34
+The people who may need to know are the ones who worked on the code
35
+you are touching. These people happen to be the ones who are
36
most likely to be knowledgeable enough to help you, but
24
-they have no obligation to help you (i.e. you ask for help,
25
-don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
37
+they have no obligation to help you (i.e. you ask them for help,
38
+you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
39
help you find out who they are.
40
28
-. You get comments and suggestions for improvements. You may
29
- even get them in an "on top of your change" patch form.
30
-
31
-. Polish, refine, and re-send to the list and the people who
32
- spend their time to improve your patch. Go back to step (2).
33
-
34
-. The list forms consensus that the last round of your patch is
35
- good. Send it to the maintainer and cc the list.
36
-
37
-. A topic branch is created with the patch and is merged to `next`,
38
- and cooked further and eventually graduates to `master`.
39
-
40
-In any time between the (2)-(3) cycle, the maintainer may pick it up
41
-from the list and queue it to `seen`, in order to make it easier for
42
-people to play with it without having to pick up and apply the patch to
43
-their trees themselves.
44
-
45
-[[patch-status]]
46
-=== Know the status of your patch after submission
47
-
48
-* You can use Git itself to find out when your patch is merged in
49
- master. `git pull --rebase` will automatically skip already-applied
50
- patches, and will let you know. This works only if you rebase on top
51
- of the branch in which your patch has been merged (i.e. it will not
52
- tell you if your patch is merged in `seen` if you rebase on top of
53
- master).
41
+. You get comments and suggestions for improvements. You may even get
42
+ them in an "on top of your change" patch form. You are expected to
43
+ respond to them with "Reply-All" on the mailing list, while taking
44
+ them into account while preparing an updated set of patches.
45
+
46
+. Polish, refine, and re-send your patches to the list and to the people
47
+ who spent their time to improve your patch. Go back to step (2).
48
+
49
+. While the above iterations improve your patches, the maintainer may
50
+ pick the patches up from the list and queue them to the `seen`
51
+ branch, in order to make it easier for people to play with it
52
+ without having to pick up and apply the patches to their trees
53
+ themselves. Being in `seen` has no other meaning. Specifically, it
54
+ does not mean the patch was "accepted" in any way.
55
+
56
+. When the discussion reaches a consensus that the latest iteration of
57
+ the patches are in good enough shape, the maintainer includes the
58
+ topic in the "What's cooking" report that are sent out a few times a
59
+ week to the mailing list, marked as "Will merge to 'next'." This
60
+ decision is primarily made by the maintainer with help from those
61
+ who participated in the review discussion.
62
+
63
+. After the patches are merged to the 'next' branch, the discussion
64
+ can still continue to further improve them by adding more patches on
65
+ top, but by the time a topic gets merged to 'next', it is expected
66
+ that everybody agrees that the scope and the basic direction of the
67
+ topic are appropriate, so such an incremental updates are limited to
68
+ small corrections and polishing. After a topic cooks for some time
69
+ (like 7 calendar days) in 'next' without needing further tweaks on
70
+ top, it gets merged to the 'master' branch and wait to become part
71
+ of the next major release.
72
+
73
+In the following sections, many techniques and conventions are listed
74
+to help your patches get reviewed effectively in such a life cycle.
75
55
-* Read the Git mailing list, the maintainer regularly posts messages
56
- entitled "What's cooking in git.git" giving
57
- the status of various proposed changes.
76
77
[[choose-starting-point]]
78
=== Choose a starting point.
@@ -241,8 +259,9 @@ reasons:
259
which case, they can explain why they extend your code to cover
260
files, too).
261
244
-The goal of your log message is to convey the _why_ behind your
245
-change to help future developers.
262
+The goal of your log message is to convey the _why_ behind your change
263
+to help future developers. The reviewers will also make sure that
264
+your proposed log message will serve this purpose well.
265
266
The first line of the commit message should be a short description (50
267
characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),