[RFC PATCH 2/2] SubmittingPatches: Complete rewrite of section 0

[RFC PATCH 2/2] SubmittingPatches: Complete rewrite of section 0

[Ramkumar Ramachandra]

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 <artagnon@gmail.com>
---
 Documentation/SubmittingPatches |   55 ++++++++++++++++++--------------------
 1 files changed, 26 insertions(+), 29 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a90155c..0b62b62 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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.
 
-- 
1.7.0.4

Re: [RFC PATCH 2/2] SubmittingPatches: Complete rewrite of section 0

[Jonathan Nieder]

Ramkumar Ramachandra wrote:

> This rewrite makes section 0 less verbose and more readable. It is
> intended to be squashed into the previous commit.

Nice.

> +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

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0b62b62..8db22ef 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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.