{"thread":{"id":"23518","subject":"[RFC PATCH 2/2] SubmittingPatches: Complete rewrite of section 0","startedAt":"2010-04-18T19:54:55Z","lastAt":"2010-04-19T00:21:13Z","messageCount":2,"participants":["Ramkumar Ramachandra","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"139842","messageId":"1271620467-sup-7590@kytes","threadId":"23518","inReplyTo":null,"subject":"[RFC PATCH 2/2] SubmittingPatches: Complete rewrite of section 0","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-04-18T19:54:55Z","receivedAt":"2010-04-18T19:54:55Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"This rewrite makes section 0 less verbose and more readable. It is\nintended to be squashed into the previous commit.\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n---\n Documentation/SubmittingPatches |   55 ++++++++++++++++++--------------------\n 1 files changed, 26 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex a90155c..0b62b62 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -55,35 +55,32 @@ thousand times smaller ;-).  So here is only the relevant bits.\n \n (0) Decide what to base your work on.\n \n-The general principle is always to base your work on the oldest branch\n-that your change is relevant to.\n-\n- - A fix for a bug that has been with git from older releases should be\n-   included in both the upcoming feature release and the current\n-   maintenance release.  Try to base your work on the 'maint' branch.  A\n-   work to kill a bug that is in 'master' but not in 'maint' should be\n-   based on 'master'.\n-\n- - A fix for a bug that is not yet in 'master' is the best bug to kill.\n-   If you can find the topic that introduces the regression, base your\n-   work on the tip of the topic.  \"log --first-parent master..pu\" would be\n-   a good way to find the tips of topic branches.\n-\n- - A new feature should be based on the 'master' branch in general.\n-\n- - If your new feature depends on some other topics that are not in\n-   'master' yet, and if it relies only on one topic, base your work on the\n-   tip of that topic.  If it depends on too many topics that are not in\n-   'master', you can privately start working on 'next' or even 'pu' and\n-   send out your patches for discussion, but it is possible that your\n-   maintainer may ask you to wait and rebase your changes on 'master'\n-   after some of the larger topics your topic depends on graduate to\n-   'master'.\n-\n- - Base corrections and enhancements on a topic that are not in 'master'\n-   yet but already merged to 'next' on the tip of the topic.  If the topic\n-   has not been merged to 'next', it is Ok to add a note that the patch is\n-   a trivial fix and can be squashed into the series.\n+In general, always base your work on the oldest branch that your\n+change is relevant to.\n+\n+ - A bugfix should be based on 'maint' in general. If the bug is not\n+   present in 'maint', base it on 'master'. For a bug that's not yet\n+   in 'master', find the topic that introduces the regression, and\n+   base your work on the tip of the topic.\n+\n+ - A new feature should be based on 'master' in general. If the new\n+   feature depends on a topic that is in 'pu', but not in 'master',\n+   base your work on the tip of that topic.\n+\n+ - Corrections and enhancements to a topic not yet in 'master' should\n+   be based on the tip of that topic. If the topic has not been merged\n+   to 'next', it's alright to add a note to squash minor corrections\n+   into the series.\n+\n+ - In the exceptional case that a new feature depends on several topics\n+   not in 'master', start working on 'next' or 'pu' privately and send\n+   out patches for discussion. Before the final merge, you may have to\n+   wait until some of the dependent topics graduate to 'master', and\n+   rebase your work.\n+\n+To find the tip of a topic branch, run \"git log --first-parent\n+master..pu\" and look for the merge commit. The grandparent of this\n+commit is the tip of the topic branch.\n \n (1) Make separate commits for logically separate changes.\n \n-- \n1.7.0.4\n"},{"id":"139859","messageId":"20100419002113.GA14202@progeny.tock","threadId":"23518","inReplyTo":"1271620467-sup-7590@kytes","subject":"Re: [RFC PATCH 2/2] SubmittingPatches: Complete rewrite of section 0","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-04-19T00:21:13Z","receivedAt":"2010-04-19T00:21:13Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> This rewrite makes section 0 less verbose and more readable. It is\n> intended to be squashed into the previous commit.\n\nNice.\n\n> +To find the tip of a topic branch, run \"git log --first-parent\n> +master..pu\" and look for the merge commit. The grandparent of this\n> +commit is the tip of the topic branch.\n\nThe reader is not looking for the second-generation grand-parent foo~2\nbut the second parent foo^2, using terminology from git-rev-parse.1.\n\nI guess the “second parent” term always involves this potential\nconfusion.  Luckily, the uninitiated reader can infer from the context\nthat foo~2 is not the intended commit, so there is no need to resort\nto awkward phrases like “the second first-generation parent”.\n\nJonathan\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 0b62b62..8db22ef 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -79,7 +79,7 @@ change is relevant to.\n    rebase your work.\n \n To find the tip of a topic branch, run \"git log --first-parent\n-master..pu\" and look for the merge commit. The grandparent of this\n+master..pu\" and look for the merge commit. The second parent of this\n commit is the tip of the topic branch.\n \n (1) Make separate commits for logically separate changes.\n"}]}