SubmittingPatches: Complete rewrite of section 0
RFC PATCH 2/2 SubmittingPatches: Complete rewrite of section 0
This rewrite makes section 0 less verbose and more readable. It is intended to be squashed into the previous commit.
Signed-off-by Ramkumar Ramachandra <[email protected]>
--- Documentation/SubmittingPatches | 55 ++++++++++++++++++-------------------- 1 files changed, 26 insertions(+), 29 deletions(-)
Documentation/SubmittingPatches +26 -29
@@ -55,35 +55,32 @@ thousand times smaller ;-). So here is only the relevant bits. (0) Decide what to base your work on. -The general principle is always to base your work on the oldest branch -that your change is relevant to. - - - A fix for a bug that has been with git from older releases should be - included in both the upcoming feature release and the current - maintenance release. Try to base your work on the 'maint' branch. A - work to kill a bug that is in 'master' but not in 'maint' should be - based on 'master'. - - - A fix for a bug that is not yet in 'master' is the best bug to kill. - If you can find the topic that introduces the regression, base your - work on the tip of the topic. "log --first-parent master..pu" would be - a good way to find the tips of topic branches. - - - A new feature should be based on the 'master' branch in general. - - - If your new feature depends on some other topics that are not in - 'master' yet, and if it relies only on one topic, base your work on the - tip of that topic. If it depends on too many topics that are not in - 'master', you can privately start working on 'next' or even 'pu' and - send out your patches for discussion, but it is possible that your - maintainer may ask you to wait and rebase your changes on 'master' - after some of the larger topics your topic depends on graduate to - 'master'. - - - Base corrections and enhancements on a topic that are not in 'master' - yet but already merged to 'next' on the tip of the topic. If the topic - has not been merged to 'next', it is Ok to add a note that the patch is - a trivial fix and can be squashed into the series. +In general, always base your work on the oldest branch that your +change is relevant to. + + - A bugfix should be based on 'maint' in general. If the bug is not + present in 'maint', base it on 'master'. For a bug that's not yet + in 'master', find the topic that introduces the regression, and + base your work on the tip of the topic. + + - A new feature should be based on 'master' in general. If the new + feature depends on a topic that is in 'pu', but not in 'master', + base your work on the tip of that topic. + + - Corrections and enhancements to a topic not yet in 'master' should + be based on the tip of that topic. If the topic has not been merged + to 'next', it's alright to add a note to squash minor corrections + into the series. + + - In the exceptional case that a new feature depends on several topics + not in 'master', start working on 'next' or 'pu' privately and send + out patches for discussion. Before the final merge, you may have to + wait until some of the dependent topics graduate to 'master', and + rebase your work. + +To find the tip of a topic branch, run "git log --first-parent +master..pu" and look for the merge commit. The grandparent of this +commit is the tip of the topic branch. (1) Make separate commits for logically separate changes.
Signature · 1 line
1.7.0.4
Quoted 2 lines · Ramkumar Ramachandra
This rewrite makes section 0 less verbose and more readable. It is intended to be squashed into the previous commit.
Nice.
Review
Quoted 3 lines
(quoted diff) +3
-0+To find the tip of a topic branch, run "git log --first-parent +master..pu" and look for the merge commit. The grandparent of this +commit is the tip of the topic branch.
The reader is not looking for the second-generation grand-parent foo~2 but the second parent foo^2, using terminology from git-rev-parse.1.
I guess the “second parent” term always involves this potential confusion. Luckily, the uninitiated reader can infer from the context that foo~2 is not the intended commit, so there is no need to resort to awkward phrases like “the second first-generation parent”.
Jonathan
Documentation/SubmittingPatches +1 -1
@@ -79,7 +79,7 @@ change is relevant to. rebase your work. To find the tip of a topic branch, run "git log --first-parent -master..pu" and look for the merge commit. The grandparent of this +master..pu" and look for the merge commit. The second parent of this commit is the tip of the topic branch. (1) Make separate commits for logically separate changes.