mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

SubmittingPatches: extend the "flow" section

Browse Source 
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>
This commit is contained in:
Junio C Hamano
2024-05-10 09:55:26 -07:00
parent d58848fb21
commit 120adc7d3c
1 changed files with 56 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
Documentation/SubmittingPatches
View File

@ -8,53 +8,71 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]
available which covers many of these same guidelines. available which covers many of these same guidelines.
[[patch-flow]] [[patch-flow]]
=== An ideal patch flow === A typical life cycle of a patch series
Here is an ideal patch flow for this project the current maintainer To help us understand the reason behind various guidelines given later
suggests to the contributors: in the document, first let's understand how the life cycle of a
typical patch series for this project goes.
. You come up with an itch. You code it up. . You come up with an itch. You code it up. You do not need any
pre-authorization from the project to do so.
. Send it to the list and cc people who may need to know about
the change.
+ +
The people who may need to know are the ones whose code you Your patches will be reviewed by other contributors on the mailing
are butchering. These people happen to be the ones who are list, and the reviews will be done to assess the merit of various
things, like the general idea behind your patch (including "is it
solving a problem worth solving in the first place?"), the reason
behind the design of the solution, and the actual implementation.
The guidelines given here are there to help your patches by making
them easier to understand by the reviewers.
. You send the patches to the list and cc people who may need to know
about the change. Your goal is *not* necessarily to convince others
that what you are building is good. Your goal is to get help in
coming up with a solution for the "itch" that is better than what
you can build alone.
+
The people who may need to know are the ones who worked on the code
you are touching. These people happen to be the ones who are
most likely to be knowledgeable enough to help you, but most likely to be knowledgeable enough to help you, but
they have no obligation to help you (i.e. you ask for help, they have no obligation to help you (i.e. you ask them for help,
don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
help you find out who they are. help you find out who they are.
. You get comments and suggestions for improvements. You may . You get comments and suggestions for improvements. You may even get
even get them in an "on top of your change" patch form. them in an "on top of your change" patch form. You are expected to
respond to them with "Reply-All" on the mailing list, while taking
them into account while preparing an updated set of patches.
. Polish, refine, and re-send to the list and the people who . Polish, refine, and re-send your patches to the list and to the people
spend their time to improve your patch. Go back to step (2). who spent their time to improve your patch. Go back to step (2).
. The list forms consensus that the last round of your patch is . While the above iterations improve your patches, the maintainer may
good. Send it to the maintainer and cc the list. pick the patches up from the list and queue them to the `seen`
branch, in order to make it easier for people to play with it
without having to pick up and apply the patches to their trees
themselves. Being in `seen` has no other meaning. Specifically, it
does not mean the patch was "accepted" in any way.
. A topic branch is created with the patch and is merged to `next`, . When the discussion reaches a consensus that the latest iteration of
and cooked further and eventually graduates to `master`. the patches are in good enough shape, the maintainer includes the
topic in the "What's cooking" report that are sent out a few times a
week to the mailing list, marked as "Will merge to 'next'." This
decision is primarily made by the maintainer with help from those
who participated in the review discussion.
In any time between the (2)-(3) cycle, the maintainer may pick it up . After the patches are merged to the 'next' branch, the discussion
from the list and queue it to `seen`, in order to make it easier for can still continue to further improve them by adding more patches on
people to play with it without having to pick up and apply the patch to top, but by the time a topic gets merged to 'next', it is expected
their trees themselves. that everybody agrees that the scope and the basic direction of the
topic are appropriate, so such an incremental updates are limited to
small corrections and polishing. After a topic cooks for some time
(like 7 calendar days) in 'next' without needing further tweaks on
top, it gets merged to the 'master' branch and wait to become part
of the next major release.
[[patch-status]] In the following sections, many techniques and conventions are listed
=== Know the status of your patch after submission to help your patches get reviewed effectively in such a life cycle.
* You can use Git itself to find out when your patch is merged in
master. `git pull --rebase` will automatically skip already-applied
patches, and will let you know. This works only if you rebase on top
of the branch in which your patch has been merged (i.e. it will not
tell you if your patch is merged in `seen` if you rebase on top of
master).
* Read the Git mailing list, the maintainer regularly posts messages
entitled "What's cooking in git.git" giving
the status of various proposed changes.
[[choose-starting-point]] [[choose-starting-point]]
=== Choose a starting point. === Choose a starting point.
@ -241,8 +259,9 @@ reasons:
which case, they can explain why they extend your code to cover which case, they can explain why they extend your code to cover
files, too). files, too).
The goal of your log message is to convey the _why_ behind your The goal of your log message is to convey the _why_ behind your change
change to help future developers. to help future developers. The reviewers will also make sure that
your proposed log message will serve this purpose well.
The first line of the commit message should be a short description (50 The first line of the commit message should be a short description (50
characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),