{"thread":{"id":"56496","subject":"[PATCH] MyFirstContribution: Document --range-diff option when writing v2","startedAt":"2021-09-13T19:48:29Z","lastAt":"2021-09-23T13:44:49Z","messageCount":22,"participants":["Glen Choo","Eric Sunshine","Junio C Hamano","Bagas Sanjaya","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"435784","messageId":"20210913194816.51182-1-chooglen@google.com","threadId":"56496","inReplyTo":null,"subject":"[PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-13T19:48:16Z","receivedAt":"2021-09-13T19:48:29Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"In the \"Sending V2\" section, readers are directed to create v2 patches\nwithout using --range-diff. However, it is custom to include a range\ndiff against the v1 patches as a reviewer aid.\n\nUpdate the \"Sending V2\" section to include the --range-diff option. Also\ninclude some explanation for -v2 and --range-diff to help the reader\nunderstand the importance.\n\nSigned-off-by: Glen Choo \n---\n Documentation/MyFirstContribution.txt | 29 ++++++++++++++++++++-------\n 1 file changed, 22 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 015cf24631..add1c2bba9 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1033,18 +1033,33 @@ Skip ahead to <> for information on how to\n handle comments from reviewers. Continue this section when your topic branch is\n shaped the way you want it to look for your patchset v2.\n \n-When you're ready with the next iteration of your patch, the process is fairly\n-similar.\n+Let's write v2 as its own topic branch, because this will make some things more\n+convenient later on. Create the `psuh-v2` branch like so:\n \n-First, generate your v2 patches again:\n+----\n+$ git checkout -b psuh-v2 psuh\n+----\n+\n+When you're ready with the next iteration of your patch, the process is fairly\n+similar to before. Generate your patches again, but with some new flags:\n \n ----\n-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n+$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh\n ----\n \n-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,\n-to the `psuh/` directory. You may notice that they are sitting alongside the v1\n-patches; that's fine, but be careful when you are ready to send them.\n+The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a\n+range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the\n+differences between your v1 and v2 patches.\n+\n+The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n+you may notice that your v2 patches, are all named like\n+`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n+prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n+be prefaced with \"Range-diff against v1\".\n+\n+Afer you run this command, `format-patch` will output the patches to the `psuh/`\n+directory, alongside the v1 patches. That's fine, but be careful when you are\n+ready to send them.\n \n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n-- \n2.33.0.309.g3052b89438-goog\n\n"},{"id":"435786","messageId":"CAPig+cRZaonjCKt-rKcU0y-xNX1OQyftuEkuB4Rzhc5jCwVgMQ@mail.gmail.com","threadId":"56496","inReplyTo":"20210913194816.51182-1-chooglen@google.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-09-13T20:00:04Z","receivedAt":"2021-09-13T20:00:18Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 13, 2021 at 3:48 PM Glen Choo wrote:\n> In the \"Sending V2\" section, readers are directed to create v2 patches\n> without using --range-diff. However, it is custom to include a range\n> diff against the v1 patches as a reviewer aid.\n>\n> Update the \"Sending V2\" section to include the --range-diff option. Also\n> include some explanation for -v2 and --range-diff to help the reader\n> understand the importance.\n\nMakes sense. A few minor comments below...\n\n> Signed-off-by: Glen Choo \n> ---\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> @@ -1033,18 +1033,33 @@ Skip ahead to <> for information on how to\n> -When you're ready with the next iteration of your patch, the process is fairly\n> -similar.\n> +Let's write v2 as its own topic branch, because this will make some things more\n> +convenient later on. Create the `psuh-v2` branch like so:\n>\n> -First, generate your v2 patches again:\n> +----\n> +$ git checkout -b psuh-v2 psuh\n> +----\n\nThese days, we're generally promote `git switch -c psuh-v2 psuh`\nrather than `git branch -b`. However, since the document already uses\n`git branch -b` elsewhere, the use here is probably acceptable. (An\nalternative would be to make this a two-patch series in which the\nfirst patch changes `git branch -b` over to `git switch -c`.)\n\n> +When you're ready with the next iteration of your patch, the process is fairly\n> +similar to before. Generate your patches again, but with some new flags:\n>\n> ----\n> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n> +$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh\n> ----\n\nAs long as both versions have the same base, it's generally easier to\nsay merely `--range-diff=psuh` -- that is, you want a range-diff\nagainst `psuh` -- than to spell out the range explicitly. However,\nperhaps spelling out the range here has some pedagogical value, so\nmaybe this is okay as-is.\n\n> +The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a\n> +range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the\n> +differences between your v1 and v2 patches.\n\nI think we usually spell it as \"range-diff\", not \"range diff\". Also,\nit might be a good idea to give some hint as to what a range-diff is,\neven if that hint is just a link to the `git range-diff` manual page.\nMaybe:\n\n ...to include a range-diff (see linkgit:range-diff[1]) between...\n"},{"id":"435787","messageId":"CAPig+cQmRRRn+39+mTRfop4joR8kJECn6mD8BRrAa67qy7yz=Q@mail.gmail.com","threadId":"56496","inReplyTo":"CAPig+cRZaonjCKt-rKcU0y-xNX1OQyftuEkuB4Rzhc5jCwVgMQ@mail.gmail.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-09-13T20:05:47Z","receivedAt":"2021-09-13T20:06:27Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 13, 2021 at 4:00 PM Eric Sunshine wrote:\n> I think we usually spell it as \"range-diff\", not \"range diff\". Also,\n> it might be a good idea to give some hint as to what a range-diff is,\n> even if that hint is just a link to the `git range-diff` manual page.\n> Maybe:\n>\n> ...to include a range-diff (see linkgit:range-diff[1]) between...\n\nOf course, I meant:\n\n ...to include a range-diff (see linkgit:git-range-diff[1]) between...\n"},{"id":"435792","messageId":"xmqqwnnkcfz8.fsf@gitster.g","threadId":"56496","inReplyTo":"20210913194816.51182-1-chooglen@google.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-13T21:39:39Z","receivedAt":"2021-09-13T21:39:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Glen Choo writes:\n\n> +Let's write v2 as its own topic branch, because this will make some things more\n> +convenient later on. Create the `psuh-v2` branch like so:\n> \n> +----\n> +$ git checkout -b psuh-v2 psuh\n> +----\n\nWhat's missing here is on which branch this new description expects\nthe user to work on. From its name, I am assuming that psuh-v2 will\nbe modified while leaving psuh untouched, but spell your expectation\nout.\n\nThe following review is based on the assumption that the user is\nexpected to futz with psuh-v2, leaving psuh intact. If that is not\nthe case, it is a strong sign that you caused confusion on one\nreader by not spelling out your expectation.\n\nI do not think it is a good suggestion at all to use a new topic\nbranch, especially a one that forked from the tip of the original\nsubmission, and work on that branch to produce the new round. It\nwould be much better to create a topic branch or a lightweight tag\n\"psuh-v1\" that points at the old tip and keep working on the same\nbranch. But that is a separate story.\n\n> +When you're ready with the next iteration of your patch, the process is fairly\n> +similar to before. Generate your patches again, but with some new flags:\n> \n> ----\n> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n> +$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh\n> ----\n\nBefore the \"Generate your patches again\", there would have been\n\"rebase -i\" of the original commits that went into \"psuh\" (v1).\n\nBut you do not necessarily have to touch all the commits during\n\"rebase -i\" session. What happens when the first few commits did\nnot need to be touched?\n\nSince the --range-diff says psuh..psuh-v2, these early and\nunmodified commits are excluded from the range, no? That would mean\nwhat appears to be commit #1 in the range-diff on the new side would\nnot be the [PATCH 1/n] of the output, no?\n\nAnd the command line says to format master..psuh, which is\npuzzling. Shouldn't it format the updated psuh-v2 branch?\n\n> +The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a\n> +range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the\n> +differences between your v1 and v2 patches.\n\nSee above. The range-diff may fail to tell the fact that there are\na few bottommost commits that are the same by omitting them.\n\nPerhaps it would make it easier to manage if we used psuh-v1 as the\nanchoring point to represent where the tip of the last round was?\n\nWith something like:\n\n\t$ git checkout psuh\n\t$ git branch psuh-v1 ;# optional -- \"git tag\" is also OK.\n\t... work work work with \"rebase -i\" ...\n\t$ git format-patch -v2 --cover-letter -o psuh/ \\\n\t\t--range-diff master..psuh-v1 master..\n\t# ..psuh-v1 can be ..@{yesterday} or whatever reflog reference\n\nwe do not have to worry if \"rebase -i\" left the bottommost commits\nuntouched or silly things like that. \n\n> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n> +you may notice that your v2 patches, are all named like\n> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n> +be prefaced with \"Range-diff against v1\".\n> +\n> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n> +directory, alongside the v1 patches. That's fine, but be careful when you are\n> +ready to send them.\n\nIt is unclear what \"That's fine, but\" is trying to convey.\n\nI'd replace it with something like:\n\n\tYou can refer to the old v1 patches while giving the final\n\tproofreading on the v2 patches, but you now need to say \"git\n\tsend-email psuh/v2-*.patch\" to send them out (\"*.patch\" would\n\tmatch both v1 and v2 patches).\n\nThanks.\n"},{"id":"435807","messageId":"02e15e8d-6923-9f21-8eeb-592eb0c9588b@gmail.com","threadId":"56496","inReplyTo":"20210913194816.51182-1-chooglen@google.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-14T02:43:09Z","receivedAt":"2021-09-14T02:43:16Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 14/09/21 02.48, Glen Choo wrote:\n> In the \"Sending V2\" section, readers are directed to create v2 patches\n> without using --range-diff. However, it is custom to include a range\n> diff against the v1 patches as a reviewer aid.\n> \n> Update the \"Sending V2\" section to include the --range-diff option. Also\n> include some explanation for -v2 and --range-diff to help the reader\n> understand the importance.\n\nI think plain \"Changes since v1 [link]\" is sufficient if you can \ndescribe such changes well without resorting to range-diff.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"435816","messageId":"CAPig+cSHSSuE6ovPN+XVRDhNU8WD+XzuH0gLzupNZiN1QLGz9A@mail.gmail.com","threadId":"56496","inReplyTo":"02e15e8d-6923-9f21-8eeb-592eb0c9588b@gmail.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-09-14T03:46:04Z","receivedAt":"2021-09-14T03:46:20Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 13, 2021 at 10:43 PM Bagas Sanjaya wrote:\n> On 14/09/21 02.48, Glen Choo wrote:\n> > In the \"Sending V2\" section, readers are directed to create v2 patches\n> > without using --range-diff. However, it is custom to include a range\n> > diff against the v1 patches as a reviewer aid.\n> >\n> > Update the \"Sending V2\" section to include the --range-diff option. Also\n> > include some explanation for -v2 and --range-diff to help the reader\n> > understand the importance.\n>\n> I think plain \"Changes since v1 [link]\" is sufficient if you can\n> describe such changes well without resorting to range-diff.\n\nNot so. Anyone who does any serious amount of review on this project\nfinds it tremendously helpful to have both a prose description of the\nchanges (\"Changes since v1...\" plus a link to the previous submission)\nand a mechanical range-diff or interdiff. A range-diff (or interdiff)\nis especially important to provide reviewers with context which they\nmight have forgotten since the previous version of a patch series was\nposted, which can matter since it's so easy to forget specifics even\nabout one's own review if enough time has passed or if reviewing a\nlarge number of unrelated submissions. A range-diff or interdiff also\nhelps a reviewer determine at-a-glance whether or not earlier review\ncomments have been addressed without having to laboriously re-read\neach and every patch.\n"},{"id":"435817","messageId":"9551fbe4-255b-774b-d00d-40f5330f70c9@gmail.com","threadId":"56496","inReplyTo":"CAPig+cSHSSuE6ovPN+XVRDhNU8WD+XzuH0gLzupNZiN1QLGz9A@mail.gmail.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-14T03:55:16Z","receivedAt":"2021-09-14T03:55:23Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 14/09/21 10.46, Eric Sunshine wrote:\n> Not so. Anyone who does any serious amount of review on this project\n> finds it tremendously helpful to have both a prose description of the\n> changes (\"Changes since v1...\" plus a link to the previous submission)\n> and a mechanical range-diff or interdiff. A range-diff (or interdiff)\n> is especially important to provide reviewers with context which they\n> might have forgotten since the previous version of a patch series was\n> posted, which can matter since it's so easy to forget specifics even\n> about one's own review if enough time has passed or if reviewing a\n> large number of unrelated submissions. A range-diff or interdiff also\n> helps a reviewer determine at-a-glance whether or not earlier review\n> comments have been addressed without having to laboriously re-read\n> each and every patch.\n> \n\nSo will range-diff be mandatory or optional?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"435889","messageId":"YUDaIc19rhendwc9@chooglen-macbookpro.roam.corp.google.com","threadId":"56496","inReplyTo":"xmqqwnnkcfz8.fsf@gitster.g","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-14T17:21:37Z","receivedAt":"2021-09-14T17:21:42Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"On Mon, Sep 13, 2021 at 02:39:39PM -0700, Junio C Hamano wrote:\n> What's missing here is on which branch this new description expects\n> the user to work on. From its name, I am assuming that psuh-v2 will\n> be modified while leaving psuh untouched, but spell your expectation\n> out.\n> \n> The following review is based on the assumption that the user is\n> expected to futz with psuh-v2, leaving psuh intact. If that is not\n> the case, it is a strong sign that you caused confusion on one\n> reader by not spelling out your expectation.\n\nThat's fair, I was suggesting a specific workflow and should have been more\nexplicit.\n\n> I do not think it is a good suggestion at all to use a new topic\n> branch, especially a one that forked from the tip of the original\n> submission, and work on that branch to produce the new round. It\n> would be much better to create a topic branch or a lightweight tag\n> \"psuh-v1\" that points at the old tip and keep working on the same\n> branch. But that is a separate story.\n\nGiven that this is a \"my first contribution\" guide, I think it would be\nbeneficial to be at least mildly opinionated on the workflow. Since the\nspecifics of range-diff would depend on the workflow we choose to promote, it\nwould be nice to make it as helpful as possible the first time around.\n\nThat is to say, I'd really appreciate your thoughts on your recommended workflow\nand I'd like to structure my additions around your recommendation :) What I've\ndocumented is just my own workflow, but I'm sure you have more insight into\nthis area.\n\n> But you do not necessarily have to touch all the commits during\n> \"rebase -i\" session. What happens when the first few commits did\n> not need to be touched?\n> \n> Since the --range-diff says psuh..psuh-v2, these early and\n> unmodified commits are excluded from the range, no? That would mean\n> what appears to be commit #1 in the range-diff on the new side would\n> not be the [PATCH 1/n] of the output, no?\n\nYes, good catch. This was an oversight on my part.\n\n> Perhaps it would make it easier to manage if we used psuh-v1 as the\n> anchoring point to represent where the tip of the last round was?\n> \n> With something like:\n> \n> \t$ git checkout psuh\n> \t$ git branch psuh-v1 ;# optional -- \"git tag\" is also OK.\n> \t... work work work with \"rebase -i\" ...\n> \t$ git format-patch -v2 --cover-letter -o psuh/ \\\n> \t\t--range-diff master..psuh-v1 master..\n\nHaving an explicit psuh-v1 is a good idea.\n\n> \t# ..psuh-v1 can be ..@{yesterday} or whatever reflog reference\n\nIf we make it clear that psuh-v1 is just the tip of the last round, perhaps the\nreaders who would do this can already infer this from context, and we can omit\nthe comment for brevity?\n\n> > +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n> > +directory, alongside the v1 patches. That's fine, but be careful when you are\n> > +ready to send them.\n> \n> It is unclear what \"That's fine, but\" is trying to convey.\n\nVery valid.\n\n> I'd replace it with something like:\n> \n> \tYou can refer to the old v1 patches while giving the final\n> \tproofreading on the v2 patches, but you now need to say \"git\n> \tsend-email psuh/v2-*.patch\" to send them out (\"*.patch\" would\n> \tmatch both v1 and v2 patches).\n\nHere, I have to confess that I'm not sure why the guide reuses the psuh/\ndirectory. When I was first going through this, having v1 and v2 patches in the\nsame directory seemed like a risky default because of the inherent risk of\nsending both v1 and v2 together.\n\nI believe the unspoken intent is that having v1 patches in the same directory as\nv2 patches makes it easy to refer to both versions, and in turn, this promotes\nbetter quality discussion between v1 and v2. There might be other strong reasons\nto reuse the directory, but these are not obvious to me from reading this guide\nalone. It would be helpful to make these reasons explicit to the reader.\n"},{"id":"435923","messageId":"xmqq7dfizvjt.fsf@gitster.g","threadId":"56496","inReplyTo":"YUDaIc19rhendwc9@chooglen-macbookpro.roam.corp.google.com","subject":"Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-14T21:39:18Z","receivedAt":"2021-09-14T21:39:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Glen Choo writes:\n\n>> \t$ git format-patch -v2 --cover-letter -o psuh/ \\\n>> \t\t--range-diff master..psuh-v1 master..\n>\n> Having an explicit psuh-v1 is a good idea.\n\nI think what's good idea is not explicit psuh-v1 but taking the\nrange from the upstream (i.e. \"master\"), not \"psuh\" (which assumes\nthat symmetric difference will cover everything, which may not\nnecessarily be the case).\n\n>> \t# ..psuh-v1 can be ..@{yesterday} or whatever reflog reference\n>\n> If we make it clear that psuh-v1 is just the tip of the last round, perhaps the\n> readers who would do this can already infer this from context, and we can omit\n> the comment for brevity?\n\nOh absolutely. These #comments were meant for your consumption and\nnot as a suggestion to be placed in the final text given to the end\nusers.\n\n> I believe the unspoken intent is that having v1 patches in the same directory as\n> v2 patches makes it easy to refer to both versions, and in turn, this promotes\n> better quality discussion between v1 and v2.\nSeparate directories may make it easier to do:\n\n diff -u psuh-v1/ pshu-v2/\n\nas\n\n cd psuh && diff -u v1* v2*\n\nwould NOT work, but comparing patch e-mails textually, especially\nafter the order of the patches or title of them got updated, won't\nbe so useful an operation anyway.\n\nWhen you have multiple topics in flight, you want your psuh topic in\na single directory (perhaps differentiating the iterations with v$n\nprefix, or you can choose to have a subdirectory v1, v2, etc. in\nthat directory) that is different from the directory for your plul\ntopic, instead of flat collection of directories for psuh-v1,\npsuh-v2 and plul-v1 topic-iterations.\n\n"},{"id":"436512","messageId":"20210920223226.25877-1-chooglen@google.com","threadId":"56496","inReplyTo":"20210913194816.51182-1-chooglen@google.com","subject":"[PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-20T22:32:26Z","receivedAt":"2021-09-21T02:21:59Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"In the \"Sending v2\" section, readers are directed to create v2 patches\nwithout using --range-diff. However, it is customary to include a\nrange-diff against the v1 patches as a reviewer aid.\n\nUpdate the \"Sending v2\" section to suggest a simple workflow that uses\nthe --range-diff option. Also include some explanation for -v2 and\n--range-diff to help the reader understand the importance.\n\nSigned-off-by: Glen Choo \n---\nThanks for the helpful comments on v1! v2 aims to clear up other\nambiguities from v1 and to propose a specific workflow for readers.\n\nChanges since v1:\n\n* recommend that readers reuse the `psuh` topic branch for v2\n* recommend that readers mark their v1 topic branch\n* add a link to the range-diff docs\n* change the v2 glob pattern to `psuh/v2-*.patch` to match the v1 example\n* explicitly call out the v2 glob pattern so that readers will be extra\n careful\n\nInterdiff against v1:\n diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n index add1c2bba9..790bf1e8b5 100644\n --- a/Documentation/MyFirstContribution.txt\n +++ b/Documentation/MyFirstContribution.txt\n @@ -1029,27 +1029,29 @@ kidding - be patient!)\n [[v2-git-send-email]]\n === Sending v2\n \n -Skip ahead to <> for information on how to\n -handle comments from reviewers. Continue this section when your topic branch is\n -shaped the way you want it to look for your patchset v2.\n +This section will focus on how to send a v2 of your patchset. To learn what\n +should go into v2, skip ahead to <> for\n +information on how to handle comments from reviewers.\n \n -Let's write v2 as its own topic branch, because this will make some things more\n -convenient later on. Create the `psuh-v2` branch like so:\n +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n +mark the tip of our v1 branch for easy reference:\n \n ----\n -$ git checkout -b psuh-v2 psuh\n +$ git checkout psuh\n +$ git branch psuh-v1\n ----\n \n -When you're ready with the next iteration of your patch, the process is fairly\n -similar to before. Generate your patches again, but with some new flags:\n +Make your changes with `git rebase -i`. Once you're ready with the next\n +iteration of your patch, the process is fairly similar to before. Generate your\n +patches again, but with some new flags:\n \n ----\n -$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh\n +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n ----\n \n -The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a\n -range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the\n -differences between your v1 and v2 patches.\n +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n +helps tell reviewers about the differences between your v1 and v2 patches.\n \n The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n you may notice that your v2 patches, are all named like\n @@ -1058,8 +1060,10 @@ prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n be prefaced with \"Range-diff against v1\".\n \n Afer you run this command, `format-patch` will output the patches to the `psuh/`\n -directory, alongside the v1 patches. That's fine, but be careful when you are\n -ready to send them.\n +directory, alongside the v1 patches. Using a single directory makes it easy to\n +refer to the old v1 patches while proofreading the v2 patches, but you will need\n +to be careful to send out only the v2 patches. We will use a pattern like\n +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n \n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n @@ -1097,7 +1101,7 @@ to the command:\n ----\n $ git send-email --to=target@example.com\n \t\t --in-reply-to=\"\"\n -\t\t psuh/v2*\n +\t\t psuh/v2-*.patch\n ----\n \n [[single-patch]]\n\n Documentation/MyFirstContribution.txt | 41 ++++++++++++++++++++-------\n 1 file changed, 30 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 015cf24631..790bf1e8b5 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1029,22 +1029,41 @@ kidding - be patient!)\n [[v2-git-send-email]]\n === Sending v2\n \n-Skip ahead to <> for information on how to\n-handle comments from reviewers. Continue this section when your topic branch is\n-shaped the way you want it to look for your patchset v2.\n+This section will focus on how to send a v2 of your patchset. To learn what\n+should go into v2, skip ahead to <> for\n+information on how to handle comments from reviewers.\n+\n+We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n+mark the tip of our v1 branch for easy reference:\n \n-When you're ready with the next iteration of your patch, the process is fairly\n-similar.\n+----\n+$ git checkout psuh\n+$ git branch psuh-v1\n+----\n \n-First, generate your v2 patches again:\n+Make your changes with `git rebase -i`. Once you're ready with the next\n+iteration of your patch, the process is fairly similar to before. Generate your\n+patches again, but with some new flags:\n \n ----\n-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n+$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n ----\n \n-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,\n-to the `psuh/` directory. You may notice that they are sitting alongside the v1\n-patches; that's fine, but be careful when you are ready to send them.\n+The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n+range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n+helps tell reviewers about the differences between your v1 and v2 patches.\n+\n+The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n+you may notice that your v2 patches, are all named like\n+`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n+prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n+be prefaced with \"Range-diff against v1\".\n+\n+Afer you run this command, `format-patch` will output the patches to the `psuh/`\n+directory, alongside the v1 patches. Using a single directory makes it easy to\n+refer to the old v1 patches while proofreading the v2 patches, but you will need\n+to be careful to send out only the v2 patches. We will use a pattern like\n+\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n \n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n@@ -1082,7 +1101,7 @@ to the command:\n ----\n $ git send-email --to=target@example.com\n \t\t --in-reply-to=\"\"\n-\t\t psuh/v2*\n+\t\t psuh/v2-*.patch\n ----\n \n [[single-patch]]\n-- \n2.33.0.464.g1972c5931b-goog\n\n"},{"id":"436567","messageId":"CAPig+cR8ZRGVrNsf6nbBsjuLt768fr=SB+bY_bD+tQpkzrL7FA@mail.gmail.com","threadId":"56496","inReplyTo":"20210920223226.25877-1-chooglen@google.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-09-21T04:59:01Z","receivedAt":"2021-09-21T04:59:14Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 20, 2021 at 10:22 PM Glen Choo wrote:\n> In the \"Sending v2\" section, readers are directed to create v2 patches\n> without using --range-diff. However, it is customary to include a\n> range-diff against the v1 patches as a reviewer aid.\n>\n> Update the \"Sending v2\" section to suggest a simple workflow that uses\n> the --range-diff option. Also include some explanation for -v2 and\n> --range-diff to help the reader understand the importance.\n>\n> Signed-off-by: Glen Choo \n> ---\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> @@ -1029,22 +1029,41 @@ kidding - be patient!)\n> +Make your changes with `git rebase -i`. Once you're ready with the next\n> +iteration of your patch, the process is fairly similar to before. Generate your\n> +patches again, but with some new flags:\n\nI wonder if \"Make your changes with `git rebase -i`\" is a bit too\nterse for newcomers to understand. Perhaps a bit more verbose:\n\n Refine your patch series by using `git rebase -i` to adjust\n commits based upon reviewer comments. Once the patch series is\n ready for submission, generate your patches again, but with some\n new flags:\n\n> ----\n> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n> ----\n>\n> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n> +helps tell reviewers about the differences between your v1 and v2 patches.\n\nThis leaves dangling the question of where the range-diff is placed. Maybe say:\n\n ... tells `format-patch` to include a range-diff between ... in\n the cover letter.\n\n> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n> +you may notice that your v2 patches, are all named like\n> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n> +be prefaced with \"Range-diff against v1\".\n\ns/V2/v2/\n\n> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n> +directory, alongside the v1 patches. Using a single directory makes it easy to\n> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n> +to be careful to send out only the v2 patches. We will use a pattern like\n> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n\nTo avoid any sort of confusion, perhaps:\n\n ... \"psuh/v2-*.patch\" (not \"psuh/*.patch\" which would match v1 and\n v2 patches)\n"},{"id":"436571","messageId":"00f94ddf-7019-a5e0-8fd5-a88a4b1cc5c3@gmail.com","threadId":"56496","inReplyTo":"20210920223226.25877-1-chooglen@google.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-21T05:33:59Z","receivedAt":"2021-09-21T05:34:05Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 21/09/21 05.32, Glen Choo wrote:\n> -Skip ahead to <> for information on how to\n> -handle comments from reviewers. Continue this section when your topic branch is\n> -shaped the way you want it to look for your patchset v2.\n> +This section will focus on how to send a v2 of your patchset. To learn what\n> +should go into v2, skip ahead to <> for\n> +information on how to handle comments from reviewers.\n> +\n> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n> +mark the tip of our v1 branch for easy reference:\n> \n> -When you're ready with the next iteration of your patch, the process is fairly\n> -similar.\n> +----\n> +$ git checkout psuh\n> +$ git branch psuh-v1\n> +----\n> \n\nAlternatively we can branch off psuh-v2 from the original psuh:\n----\n$ git checkout psuh\n$ git checkout -b psuh-v2\n----\n\nThe original psuh thus become v1. To easily identify it, we can run:\n----\n$ git checkout psuh\n$ git branch -M psuh-v1\n----\n\n> -First, generate your v2 patches again:\n> +Make your changes with `git rebase -i`. Once you're ready with the next\n> +iteration of your patch, the process is fairly similar to before. Generate your\n> +patches again, but with some new flags:\n> \n\nFor completeness, we can say \"Make your changes with `git rebase -i`. \nActions that you have to select in the todo editor of rebase depend on \nreviewers' comments. For example, if they asked to squash a commit into \nprevious one, say `pick` on the latter and `squash` on the former.\"\n\n> ----\n> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n> ----\n> \n> -This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,\n> -to the `psuh/` directory. You may notice that they are sitting alongside the v1\n> -patches; that's fine, but be careful when you are ready to send them.\n> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n> +helps tell reviewers about the differences between your v1 and v2 patches.\n> +\n> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n> +you may notice that your v2 patches, are all named like\n> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n> +be prefaced with \"Range-diff against v1\".\n> +\n\nMore accurately, `-v 2` marks the patchset as second iteration of it.\n\n> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n> +directory, alongside the v1 patches. Using a single directory makes it easy to\n> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n> +to be careful to send out only the v2 patches. We will use a pattern like\n> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n> \n> Edit your cover letter again. Now is a good time to mention what's different\n> between your last version and now, if it's something significant. You do not\n> @@ -1082,7 +1101,7 @@ to the command:\n> ----\n> $ git send-email --to=target@example.com\n> \t\t --in-reply-to=\"\"\n> -\t\t psuh/v2*\n> +\t\t psuh/v2-*.patch\n> ----\n> \n> [[single-patch]]\n> \n\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"436646","messageId":"kl6l4kadn8dg.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"56496","inReplyTo":"CAPig+cR8ZRGVrNsf6nbBsjuLt768fr=SB+bY_bD+tQpkzrL7FA@mail.gmail.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-21T17:31:07Z","receivedAt":"2021-09-21T17:31:34Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Eric Sunshine writes:\n\n>> +Make your changes with `git rebase -i`. Once you're ready with the next\n>> +iteration of your patch, the process is fairly similar to before. Generate your\n>> +patches again, but with some new flags:\n>\n> I wonder if \"Make your changes with `git rebase -i`\" is a bit too\n> terse for newcomers to understand. Perhaps a bit more verbose:\n>\n> Refine your patch series by using `git rebase -i` to adjust\n> commits based upon reviewer comments. Once the patch series is\n> ready for submission, generate your patches again, but with some\n> new flags:\n>\nI like your wording :) It seems \"obvious\" that one should incorporate\nreviewer comments, but your phrasing makes it that much clearer.\n\n>> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n>> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n>> +helps tell reviewers about the differences between your v1 and v2 patches.\n>\n> This leaves dangling the question of where the range-diff is placed. Maybe say:\n>\n> ... tells `format-patch` to include a range-diff between ... in\n> the cover letter.\n>\nSounds good.\n\n>> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n>> +you may notice that your v2 patches, are all named like\n>> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n>> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n>> +be prefaced with \"Range-diff against v1\".\n>\n> s/V2/v2/\nThanks!\n\n>> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n>> +directory, alongside the v1 patches. Using a single directory makes it easy to\n>> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n>> +to be careful to send out only the v2 patches. We will use a pattern like\n>> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n>\n> To avoid any sort of confusion, perhaps:\n>\n> ... \"psuh/v2-*.patch\" (not \"psuh/*.patch\" which would match v1 and\n> v2 patches)\nAgree that making this explicit is a good idea.\n"},{"id":"436647","messageId":"kl6l1r5hn898.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"56496","inReplyTo":"CAPig+cR8ZRGVrNsf6nbBsjuLt768fr=SB+bY_bD+tQpkzrL7FA@mail.gmail.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-21T17:33:39Z","receivedAt":"2021-09-21T17:33:46Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Eric Sunshine writes:\n\n>> +Make your changes with `git rebase -i`. Once you're ready with the next\n>> +iteration of your patch, the process is fairly similar to before. Generate your\n>> +patches again, but with some new flags:\n>\n> I wonder if \"Make your changes with `git rebase -i`\" is a bit too\n> terse for newcomers to understand. Perhaps a bit more verbose:\n>\n> Refine your patch series by using `git rebase -i` to adjust\n> commits based upon reviewer comments. Once the patch series is\n> ready for submission, generate your patches again, but with some\n> new flags:\n>\nI like your wording :) It seems \"obvious\" that one should incorporate\nreviewer comments, but your phrasing makes it that much clearer.\n\n>> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n>> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n>> +helps tell reviewers about the differences between your v1 and v2 patches.\n>\n> This leaves dangling the question of where the range-diff is placed. Maybe say:\n>\n> ... tells `format-patch` to include a range-diff between ... in\n> the cover letter.\n>\nSounds good.\n\n>> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n>> +you may notice that your v2 patches, are all named like\n>> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n>> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n>> +be prefaced with \"Range-diff against v1\".\n>\n> s/V2/v2/\nThanks!\n\n>> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n>> +directory, alongside the v1 patches. Using a single directory makes it easy to\n>> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n>> +to be careful to send out only the v2 patches. We will use a pattern like\n>> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n>\n> To avoid any sort of confusion, perhaps:\n>\n> ... \"psuh/v2-*.patch\" (not \"psuh/*.patch\" which would match v1 and\n> v2 patches)\nAgree that making this explicit is a good idea.\n"},{"id":"436648","messageId":"kl6lzgs5ltng.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"56496","inReplyTo":"CAPig+cR8ZRGVrNsf6nbBsjuLt768fr=SB+bY_bD+tQpkzrL7FA@mail.gmail.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-21T17:34:27Z","receivedAt":"2021-09-21T17:34:31Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Eric Sunshine writes:\n\n>> +Make your changes with `git rebase -i`. Once you're ready with the next\n>> +iteration of your patch, the process is fairly similar to before. Generate your\n>> +patches again, but with some new flags:\n>\n> I wonder if \"Make your changes with `git rebase -i`\" is a bit too\n> terse for newcomers to understand. Perhaps a bit more verbose:\n>\n> Refine your patch series by using `git rebase -i` to adjust\n> commits based upon reviewer comments. Once the patch series is\n> ready for submission, generate your patches again, but with some\n> new flags:\n>\nI like your wording :) It seems \"obvious\" that one should incorporate\nreviewer comments, but your phrasing makes it that much clearer.\n\n>> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n>> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n>> +helps tell reviewers about the differences between your v1 and v2 patches.\n>\n> This leaves dangling the question of where the range-diff is placed. Maybe say:\n>\n> ... tells `format-patch` to include a range-diff between ... in\n> the cover letter.\n>\nSounds good.\n\n>> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n>> +you may notice that your v2 patches, are all named like\n>> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n>> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n>> +be prefaced with \"Range-diff against v1\".\n>\n> s/V2/v2/\nThanks!\n\n>> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n>> +directory, alongside the v1 patches. Using a single directory makes it easy to\n>> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n>> +to be careful to send out only the v2 patches. We will use a pattern like\n>> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n>\n> To avoid any sort of confusion, perhaps:\n>\n> ... \"psuh/v2-*.patch\" (not \"psuh/*.patch\" which would match v1 and\n> v2 patches)\nAgree that making this explicit is a good idea.\n"},{"id":"436650","messageId":"kl6ltuidlsjm.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"56496","inReplyTo":"00f94ddf-7019-a5e0-8fd5-a88a4b1cc5c3@gmail.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-21T17:58:21Z","receivedAt":"2021-09-21T17:58:25Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Bagas Sanjaya writes:\n\n>> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n>> +mark the tip of our v1 branch for easy reference:\n>> \n>> -When you're ready with the next iteration of your patch, the process is fairly\n>> -similar.\n>> +----\n>> +$ git checkout psuh\n>> +$ git branch psuh-v1\n>> +----\n>> \n>\n> Alternatively we can branch off psuh-v2 from the original psuh:\n> ----\n> $ git checkout psuh\n> $ git checkout -b psuh-v2\n> ----\n>\n> The original psuh thus become v1. To easily identify it, we can run:\n> ----\n> $ git checkout psuh\n> $ git branch -M psuh-v1\n> ----\n>\nI proposed to reuse the topic branch at the suggestion of Junio.\n\n I do not think it is a good suggestion at all to use a new topic\n branch, especially a one that forked from the tip of the original\n submission, and work on that branch to produce the new round. It\n would be much better to create a topic branch or a lightweight tag\n \"psuh-v1\" that points at the old tip and keep working on the same\n branch. But that is a separate story.\n\nYour suggested workflow is acutally fairly similar to the one I actually\nuse. To keep this doc clear though, I think that we should probably\npropose just one workflow.\n\n> For completeness, we can say \"Make your changes with `git rebase -i`. \n> Actions that you have to select in the todo editor of rebase depend on \n> reviewers' comments. For example, if they asked to squash a commit into \n> previous one, say `pick` on the latter and `squash` on the former.\"\n>\nI hesitate to add a \"rebase -i\" tutorial because this document doesn't\ncontain similar tutorials/explanations for any 'regular' Git workflow\ncommands; the explanations are generally focused on mailing\nlist-specific commands like \"send-email\" and \"format-patch\".\n\nIt seems unlikely to me that an aspiring contributor to Git would be\nunfamiliar with \"rebase -i\". It's not the most simple command, but it is\ncommon. In fact, because it is not so simple, it seems unlikely that we\nwould do it justice in this document. For those who need it, additional\nreading on \"rebase -i\" can be left as an exercise to the reader.\n\n>> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n>\n> More accurately, `-v 2` marks the patchset as second iteration of it.\n>\nGood point. I was stuggling with how to word this paragraph. I'll work\nthat wording into this line.\n"},{"id":"436724","messageId":"77a8b8d9-4e13-8c5b-c313-512fc7c2c953@iee.email","threadId":"56496","inReplyTo":"20210920223226.25877-1-chooglen@google.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-09-22T12:18:44Z","receivedAt":"2021-09-22T12:18:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 20/09/2021 23:32, Glen Choo wrote:\n> In the \"Sending v2\" section, readers are directed to create v2 patches\n> without using --range-diff. However, it is customary to include a\n> range-diff against the v1 patches as a reviewer aid.\n>\n> Update the \"Sending v2\" section to suggest a simple workflow that uses\n> the --range-diff option. Also include some explanation for -v2 and\n> --range-diff to help the reader understand the importance.\n>\n> Signed-off-by: Glen Choo \n> ---\n> Thanks for the helpful comments on v1! v2 aims to clear up other\n> ambiguities from v1 and to propose a specific workflow for readers.\n>\n> Changes since v1:\n>\n> * recommend that readers reuse the `psuh` topic branch for v2\n> * recommend that readers mark their v1 topic branch\n> * add a link to the range-diff docs\n> * change the v2 glob pattern to `psuh/v2-*.patch` to match the v1 example\n> * explicitly call out the v2 glob pattern so that readers will be extra\n> careful\n>\n> Interdiff against v1:\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> index add1c2bba9..790bf1e8b5 100644\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -1029,27 +1029,29 @@ kidding - be patient!)\n> [[v2-git-send-email]]\n> === Sending v2\n> \n> -Skip ahead to <> for information on how to\n> -handle comments from reviewers. Continue this section when your topic branch is\n> -shaped the way you want it to look for your patchset v2.\n> +This section will focus on how to send a v2 of your patchset. To learn what\n> +should go into v2, skip ahead to <> for\n> +information on how to handle comments from reviewers.\n> \n> -Let's write v2 as its own topic branch, because this will make some things more\n> -convenient later on. Create the `psuh-v2` branch like so:\n> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n> +mark the tip of our v1 branch for easy reference:\n> \n> ----\n> -$ git checkout -b psuh-v2 psuh\n> +$ git checkout psuh\n> +$ git branch psuh-v1\n> ----\n> \n> -When you're ready with the next iteration of your patch, the process is fairly\n> -similar to before. Generate your patches again, but with some new flags:\n> +Make your changes with `git rebase -i`. Once you're ready with the next\n> +iteration of your patch, the process is fairly similar to before. Generate your\n> +patches again, but with some new flags:\n> \n> ----\n> -$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh\n> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n> ----\n> \n> -The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a\n> -range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the\n> -differences between your v1 and v2 patches.\n> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n> +helps tell reviewers about the differences between your v1 and v2 patches.\n> \n> The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n> you may notice that your v2 patches, are all named like\n> @@ -1058,8 +1060,10 @@ prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n> be prefaced with \"Range-diff against v1\".\n> \n> Afer you run this command, `format-patch` will output the patches to the `psuh/`\n> -directory, alongside the v1 patches. That's fine, but be careful when you are\n> -ready to send them.\n> +directory, alongside the v1 patches. Using a single directory makes it easy to\n> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n> +to be careful to send out only the v2 patches. We will use a pattern like\n> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n> \n> Edit your cover letter again. Now is a good time to mention what's different\n> between your last version and now, if it's something significant. You do not\n> @@ -1097,7 +1101,7 @@ to the command:\n> ----\n> $ git send-email --to=target@example.com\n> \t\t --in-reply-to=\"\"\n> -\t\t psuh/v2*\n> +\t\t psuh/v2-*.patch\n> ----\n> \n> [[single-patch]]\n>\n> Documentation/MyFirstContribution.txt | 41 ++++++++++++++++++++-------\n> 1 file changed, 30 insertions(+), 11 deletions(-)\n>\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> index 015cf24631..790bf1e8b5 100644\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -1029,22 +1029,41 @@ kidding - be patient!)\n> [[v2-git-send-email]]\n> === Sending v2\n> \n> -Skip ahead to <> for information on how to\n> -handle comments from reviewers. Continue this section when your topic branch is\n> -shaped the way you want it to look for your patchset v2.\n> +This section will focus on how to send a v2 of your patchset. To learn what\n> +should go into v2, skip ahead to <> for\n> +information on how to handle comments from reviewers.\n> +\n> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n> +mark the tip of our v1 branch for easy reference:\n> \n> -When you're ready with the next iteration of your patch, the process is fairly\n> -similar.\n> +----\n> +$ git checkout psuh\n> +$ git branch psuh-v1\n> +----\n> \n> -First, generate your v2 patches again:\n> +Make your changes with `git rebase -i`. Once you're ready with the next\n> +iteration of your patch, the process is fairly similar to before. Generate your\n> +patches again, but with some new flags:\n> \n> ----\n> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n> ----\n> \n> -This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,\n> -to the `psuh/` directory. You may notice that they are sitting alongside the v1\n> -patches; that's fine, but be careful when you are ready to send them.\n> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n> +helps tell reviewers about the differences between your v1 and v2 patches.\n> +\n> +The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n> +you may notice that your v2 patches, are all named like\n> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n> +prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n> +be prefaced with \"Range-diff against v1\".\n> +\n> +Afer you run this command, `format-patch` will output the patches to the `psuh/`\n> +directory, alongside the v1 patches. Using a single directory makes it easy to\n> +refer to the old v1 patches while proofreading the v2 patches, but you will need\n> +to be careful to send out only the v2 patches. We will use a pattern like\n> +\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n\nDo we need a line to cover/suggest how the V2 to V3 follow up to further\nreview commands are tweaked.\n\nThis sort of follows from the discussion about keeping the branch `psuh`\nas the working branch, and the `-v1`, -`v2`, `-v3` as the record of\nformer submissions. The range-diff is then tweaked to be `--range-diff\nmaster..psuh-v` where N is the last proper submission (just in case\none version was a not-submitted dud).\n\n(Hmm. Writing that was useful to help clear my thoughts as well ;-)\n\nThanks for working on this.\n-- \nPhilip\n> \n> Edit your cover letter again. Now is a good time to mention what's different\n> between your last version and now, if it's something significant. You do not\n> @@ -1082,7 +1101,7 @@ to the command:\n> ----\n> $ git send-email --to=target@example.com\n> \t\t --in-reply-to=\"\"\n> -\t\t psuh/v2*\n> +\t\t psuh/v2-*.patch\n> ----\n> \n> [[single-patch]]\n\n"},{"id":"436739","messageId":"kl6lmto4345t.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"56496","inReplyTo":"77a8b8d9-4e13-8c5b-c313-512fc7c2c953@iee.email","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-22T17:34:38Z","receivedAt":"2021-09-22T17:34:41Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Philip Oakley writes:\n\n> Do we need a line to cover/suggest how the V2 to V3 follow up to further\n> review commands are tweaked.\n>\n> This sort of follows from the discussion about keeping the branch `psuh`\n> as the working branch, and the `-v1`, -`v2`, `-v3` as the record of\n> former submissions. The range-diff is then tweaked to be `--range-diff\n> master..psuh-v` where N is the last proper submission (just in case\n> one version was a not-submitted dud).\n\nWhile writing, it seemed pretty obvious to me that v2 -> v3 would just\nentail adding 1 to every numeral. Of course I'm biased though, so I'm\nhappy to add a line if you think this isn't that obvious.\n"},{"id":"436750","messageId":"xmqqr1dg786f.fsf@gitster.g","threadId":"56496","inReplyTo":"00f94ddf-7019-a5e0-8fd5-a88a4b1cc5c3@gmail.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-22T18:54:16Z","receivedAt":"2021-09-22T18:54:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n>> +----\n>> +$ git checkout psuh\n>> +$ git branch psuh-v1\n>> +----\n>> \n>\n> Alternatively we can branch off psuh-v2 from the original psuh:\n> ----\n> $ git checkout psuh\n> $ git checkout -b psuh-v2\n> ----\n\nIt would lose the continuity in \"git reflog @{now}\" while continuing\nto work on the psuh feature. So it may be an \"alternative\", but I\ndo not think why anybody wants to recommend ti as an alternative\nwhen \"tag the end of the v1 iteration and keep using the same\" was\nalready given. If the original said \"stop working on psuh and start\na new branch called psuh-v2\", and then \"no, mark the notable point\nand keep using the same\" is offered as an alternative, it might be\nworth sending a message about, though.\n"},{"id":"436775","messageId":"20210922202218.7986-1-chooglen@google.com","threadId":"56496","inReplyTo":"20210920223226.25877-1-chooglen@google.com","subject":"[PATCH v3] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-09-22T20:22:18Z","receivedAt":"2021-09-22T20:22:32Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"In the \"Sending v2\" section, readers are directed to create v2 patches\nwithout using --range-diff. However, it is customary to include a\nrange-diff against the v1 patches as a reviewer aid.\n\nUpdate the \"Sending v2\" section to suggest a simple workflow that uses\nthe --range-diff option. Also include some explanation for -v2 and\n--range-diff to help the reader understand the importance.\n\nSigned-off-by: Glen Choo \n---\nThis tightens up some of the language from v2, but is otherwise largely\nsimilar. As always, thanks for the input!\n\nChanges since v2:\n* clarify that the range-diff is inserted into the cover letter\n* describe -v2 as creating version \"2\" instead of \"v2\"\n* fix typo in email prefix (s/V2/v2)\n* explicitly compare the v2 glob pattern with the v1 glob pattern\n\nInterdiff against v2:\n diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n index 790bf1e8b5..b20bc8e914 100644\n --- a/Documentation/MyFirstContribution.txt\n +++ b/Documentation/MyFirstContribution.txt\n @@ -1041,8 +1041,8 @@ $ git checkout psuh\n $ git branch psuh-v1\n ----\n \n -Make your changes with `git rebase -i`. Once you're ready with the next\n -iteration of your patch, the process is fairly similar to before. Generate your\n +Refine your patch series by using `git rebase -i` to adjust commits based upon\n +reviewer comments. Once the patch series is ready for submission, generate your\n patches again, but with some new flags:\n \n ----\n @@ -1050,20 +1050,21 @@ $ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 mast\n ----\n \n The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n -range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This\n -helps tell reviewers about the differences between your v1 and v2 patches.\n +range-diff between `psuh-v1` and `psuh` in the cover letter (see\n +linkgit:git-range-diff[1]). This helps tell reviewers about the differences\n +between your v1 and v2 patches.\n \n -The `-v2` parameter tells `format-patch` to output \"v2\" patches. For instance,\n -you may notice that your v2 patches, are all named like\n -`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by\n -prefixing them with \"[PATCH V2]\" instead of \"[PATCH]\", and your range-diff will\n -be prefaced with \"Range-diff against v1\".\n +The `-v2` parameter tells `format-patch` to output your patches\n +as version \"2\". For instance, you may notice that your v2 patches are\n +all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format\n +your patches by prefixing them with \"[PATCH v2]\" instead of \"[PATCH]\",\n +and your range-diff will be prefaced with \"Range-diff against v1\".\n \n Afer you run this command, `format-patch` will output the patches to the `psuh/`\n directory, alongside the v1 patches. Using a single directory makes it easy to\n refer to the old v1 patches while proofreading the v2 patches, but you will need\n to be careful to send out only the v2 patches. We will use a pattern like\n -\"psuh/v2-*.patch\" (\"psuh/*.patch\" would match v1 and v2 patches).\n +\"psuh/v2-*.patch\" (not \"psuh/*.patch\", which would match v1 and v2 patches).\n \n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n\n Documentation/MyFirstContribution.txt | 42 ++++++++++++++++++++-------\n 1 file changed, 31 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 015cf24631..b20bc8e914 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1029,22 +1029,42 @@ kidding - be patient!)\n [[v2-git-send-email]]\n === Sending v2\n \n-Skip ahead to <> for information on how to\n-handle comments from reviewers. Continue this section when your topic branch is\n-shaped the way you want it to look for your patchset v2.\n+This section will focus on how to send a v2 of your patchset. To learn what\n+should go into v2, skip ahead to <> for\n+information on how to handle comments from reviewers.\n+\n+We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n+mark the tip of our v1 branch for easy reference:\n \n-When you're ready with the next iteration of your patch, the process is fairly\n-similar.\n+----\n+$ git checkout psuh\n+$ git branch psuh-v1\n+----\n \n-First, generate your v2 patches again:\n+Refine your patch series by using `git rebase -i` to adjust commits based upon\n+reviewer comments. Once the patch series is ready for submission, generate your\n+patches again, but with some new flags:\n \n ----\n-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh\n+$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..\n ----\n \n-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,\n-to the `psuh/` directory. You may notice that they are sitting alongside the v1\n-patches; that's fine, but be careful when you are ready to send them.\n+The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n+range-diff between `psuh-v1` and `psuh` in the cover letter (see\n+linkgit:git-range-diff[1]). This helps tell reviewers about the differences\n+between your v1 and v2 patches.\n+\n+The `-v2` parameter tells `format-patch` to output your patches\n+as version \"2\". For instance, you may notice that your v2 patches are\n+all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format\n+your patches by prefixing them with \"[PATCH v2]\" instead of \"[PATCH]\",\n+and your range-diff will be prefaced with \"Range-diff against v1\".\n+\n+Afer you run this command, `format-patch` will output the patches to the `psuh/`\n+directory, alongside the v1 patches. Using a single directory makes it easy to\n+refer to the old v1 patches while proofreading the v2 patches, but you will need\n+to be careful to send out only the v2 patches. We will use a pattern like\n+\"psuh/v2-*.patch\" (not \"psuh/*.patch\", which would match v1 and v2 patches).\n \n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n@@ -1082,7 +1102,7 @@ to the command:\n ----\n $ git send-email --to=target@example.com\n \t\t --in-reply-to=\"\"\n-\t\t psuh/v2*\n+\t\t psuh/v2-*.patch\n ----\n \n [[single-patch]]\n-- \n2.33.0.464.g1972c5931b-goog\n\n"},{"id":"436830","messageId":"7357be42-57d4-0ecd-5635-b42c5b5c4d59@gmail.com","threadId":"56496","inReplyTo":"77a8b8d9-4e13-8c5b-c313-512fc7c2c953@iee.email","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-23T05:46:25Z","receivedAt":"2021-09-23T05:46:30Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 22/09/21 19.18, Philip Oakley wrote:\n> Do we need a line to cover/suggest how the V2 to V3 follow up to further\n> review commands are tweaked.\n> \n> This sort of follows from the discussion about keeping the branch `psuh`\n> as the working branch, and the `-v1`, -`v2`, `-v3` as the record of\n> former submissions. The range-diff is then tweaked to be `--range-diff\n> master..psuh-v` where N is the last proper submission (just in case\n> one version was a not-submitted dud).\n\nYes, the process is similar to v2.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"436853","messageId":"709d79f6-3396-368d-3194-1b6d668c2043@iee.email","threadId":"56496","inReplyTo":"kl6lmto4345t.fsf@chooglen-macbookpro.roam.corp.google.com","subject":"Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-09-23T13:44:47Z","receivedAt":"2021-09-23T13:44:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 22/09/2021 18:34, Glen Choo wrote:\n> Philip Oakley writes:\n>\n>> Do we need a line to cover/suggest how the V2 to V3 follow up to further\n>> review commands are tweaked.\n>>\n>> This sort of follows from the discussion about keeping the branch `psuh`\n>> as the working branch, and the `-v1`, -`v2`, `-v3` as the record of\n>> former submissions. The range-diff is then tweaked to be `--range-diff\n>> master..psuh-v` where N is the last proper submission (just in case\n>> one version was a not-submitted dud).\n> While writing, it seemed pretty obvious to me that v2 -> v3 would just\n> entail adding 1 to every numeral. Of course I'm biased though, so I'm\n> happy to add a line if you think this isn't that obvious.\nI'd been coming from thinking of the `range-diff` command where a second\nrange would be required, with a flipping of the grandfather - father -\nson version references, part triggered by the (false) expectation that\nthe `master..` would also need tweaked.\n\nIt's is hard in ref manuals to decide the point at which one need to\neither give guidance, or point out common conceptual errors.\n\nAlso, separately, it may be worth commenting (or just mentioning) about\nwhether to keep the fork-point (or --keep-base) or not, depending on the\ncomplexity of the patch series and how it may clash with other series\n(making it harder for the maintainer if the `rerere` database would need\nto keep changing)....\n\nAll in all. I think we (I) are good with your wording.\n\nPhilip\n"}]}