git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Glen Choo <chooglen@google.com>
To: git@vger.kernel.org
Cc: Glen Choo <chooglen@google.com>, emilyshaffer@google.com
Subject: [PATCH] MyFirstContribution: Document --range-diff option when writing v2
Date: Mon, 13 Sep 2021 12:48:16 -0700	[thread overview]
Message-ID: <20210913194816.51182-1-chooglen@google.com> (raw)

In the "Sending V2" section, readers are directed to create v2 patches
without using --range-diff. However, it is custom to include a range
diff against the v1 patches as a reviewer aid.

Update the "Sending V2" section to include the --range-diff option. Also
include some explanation for -v2 and --range-diff to help the reader
understand the importance.

Signed-off-by: Glen Choo <chooglen@google.com>
---
 Documentation/MyFirstContribution.txt | 29 ++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..add1c2bba9 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1033,18 +1033,33 @@ Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
 handle comments from reviewers. Continue this section when your topic branch is
 shaped the way you want it to look for your patchset v2.
 
-When you're ready with the next iteration of your patch, the process is fairly
-similar.
+Let's write v2 as its own topic branch, because this will make some things more
+convenient later on. Create the `psuh-v2` branch like so:
 
-First, generate your v2 patches again:
+----
+$ git checkout -b psuh-v2 psuh
+----
+
+When you're ready with the next iteration of your patch, the process is fairly
+similar to before. Generate your patches again, but with some new flags:
 
 ----
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
 ----
 
-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
-to the `psuh/` directory. You may notice that they are sitting alongside the v1
-patches; that's fine, but be careful when you are ready to send them.
+The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
+range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
+differences between your v1 and v2 patches.
+
+The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
+you may notice that your v2 patches, are all named like
+`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
+prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
+be prefaced with "Range-diff against v1".
+
+Afer you run this command, `format-patch` will output the patches to the `psuh/`
+directory, alongside the v1 patches. That's fine, but be careful when you are
+ready to send them.
 
 Edit your cover letter again. Now is a good time to mention what's different
 between your last version and now, if it's something significant. You do not
-- 
2.33.0.309.g3052b89438-goog


             reply	other threads:[~2021-09-13 19:48 UTC|newest]

Thread overview: 22+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-09-13 19:48 Glen Choo [this message]
2021-09-13 20:00 ` [PATCH] MyFirstContribution: Document --range-diff option when writing v2 Eric Sunshine
2021-09-13 20:05   ` Eric Sunshine
2021-09-13 21:39 ` Junio C Hamano
2021-09-14 17:21   ` Glen Choo
2021-09-14 21:39     ` Junio C Hamano
2021-09-14  2:43 ` Bagas Sanjaya
2021-09-14  3:46   ` Eric Sunshine
2021-09-14  3:55     ` Bagas Sanjaya
2021-09-20 22:32 ` [PATCH v2] " Glen Choo
2021-09-21  4:59   ` Eric Sunshine
2021-09-21 17:31     ` Glen Choo
2021-09-21 17:33     ` Glen Choo
2021-09-21 17:34     ` Glen Choo
2021-09-21  5:33   ` Bagas Sanjaya
2021-09-21 17:58     ` Glen Choo
2021-09-22 18:54     ` Junio C Hamano
2021-09-22 12:18   ` Philip Oakley
2021-09-22 17:34     ` Glen Choo
2021-09-23 13:44       ` Philip Oakley
2021-09-23  5:46     ` Bagas Sanjaya
2021-09-22 20:22   ` [PATCH v3] " Glen Choo

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210913194816.51182-1-chooglen@google.com \
    --to=chooglen@google.com \
    --cc=emilyshaffer@google.com \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).