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
next 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).