All of lore.kernel.org
 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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.