[PATCH 15/15] docs: Add a user-oriented explanation of series parsing
Finucane, Stephen
stephen.finucane at intel.com
Sat Oct 10 10:21:22 AEDT 2015
> It's really necessary to start documenting what Patchwork knows about
> when parsing emails.
>
> This time, it's about series and new revision of series.
>
> Signed-off-by: Damien Lespiau <damien.lespiau at intel.com>
Reviewing with my literature hat on...
> ---
> docs/index.rst | 1 +
> docs/manual.rst | 143
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 144 insertions(+)
> create mode 100644 docs/manual.rst
>
> diff --git a/docs/index.rst b/docs/index.rst
> index a38bf36..7322a9a 100644
> --- a/docs/index.rst
> +++ b/docs/index.rst
> @@ -13,5 +13,6 @@ Contents:
>
> intro
> installation
> + manual
> development
>
> diff --git a/docs/manual.rst b/docs/manual.rst
> new file mode 100644
> index 0000000..f29f5a8
> --- /dev/null
> +++ b/docs/manual.rst
> @@ -0,0 +1,143 @@
> +User Manual
> +===========
> +
> +Initial Submission
> +------------------
> +
> +Patches are normally submitted with ``git send-email`` to a mailing
> +list. For instance, if we branched from ``origin/master``, have 3
> +patches to submit, we can use:
s/3/three/
> +
> +::
> +
> + $ git send-email --to=<mailing-list> --cover-letter origin/master
> +
> +This command will produce the following email thread (providing you have
> +the ``chainreplyto`` configuration option set to ``false``):
> +
> +::
> +
> + + [PATCH 0/3] Cover Letter Subject
> + +--> [PATCH 1/3] Patch 1
> + +--> [PATCH 2/3] Patch 2
> + +--> [PATCH 3/3] Patch 3
<coding hat>What happens if people use deep nesting? Is this supported?</coding hat> If so, best document it to make that clear.
> +
> +Patchwork receives those mails and construct Series and Patches objects
> +to present a high level view of the mailing-list activity and a way to
> +track what happens to that submission.
> +
> +It's a good idea to include a cover-letter to introduce the work.
> +Patchwork will also pick up that cover letter and name the series with
> +the subject of that email.
We don't prescribe the rules for mailing lists so we can't say what's "a good idea": it's conceivable that some mailing lists out there don't recommend cover letters or use something that isn't Git and doesn't support cover letters. Could you reword this to say, for example:
Patchwork works best when a cover letter is included to
> +
> +When sending only one patch, it's a bit much to send a cover-letter
> +along with it as the commit message should provide enough context. In
> +that case, Patchwork will use the subject of the patch as the series
> +title.
A bit much is colloquial, you should rephrase this slightly. Example:
When sending a single patch it is not necessary to include a cover
letter. In this case...
Also I've never encountered "cover-letter" before: it's "cover letter" in my experience and Google backs this hypothesis up. Hence:
s/cover-letter/cover letter/g
> +
> +New Versions
> +------------
> +
> +Sometimes, maybe even more often than hoped, one needs to resend a few
> +patches or even entire series to address review comments.
Ha! :) Let's go slightly more PC here
It may be necessary to resubmit one or more patches for a series to...
>
> +Patchwork supports:
> +
> + - Re-sending a single patch as a reply to the reviewer email. This is
> + usually only used when a few patches have to be resent.
> +
> + - Re-sending a full series as a new thread.
> +
> +A Series object in patchwork tracks all the changes on top of the
> +initial submission.
> +
> +New Patch
> +~~~~~~~~~
Drop this whole section. There are countless guides on the internet on how to do this and there is no advantage to these.
For information on resubmitting patches, please refer to your projects contribution guidelines. Alternatively, refer to xxx
Where xxx is a good resource (Linux CONTRIBUTING doc?)
Side note: I've never encountered the '--reroll-count' parameter before. Most (nay, all) the projects I've worked on suggest amending the prefix with a v2 flag like so:
--prefix='PATCH v2' # or 'RFC v2'
This just reinforces the idea that people use their projects guidelines as a primary resource.
> +
> +To send a v2 of a patch part of a bigger series, one would do something
> +similar to:
> +
> +::
> +
> + $ git send-email --to=<mailing-list> --cc=<reviewer> \
> + --in-reply-to=<reviewer-mail-message-id> \
> + --reroll-count 2 -1 HEAD~2
> +
> +And, continuing the previous example, this would result in the following
> +email thread:
> +
> +::
> +
> + + [PATCH 0/3] Cover Letter Subject
> + +--> [PATCH 1/3] Patch 1
> + +--> [PATCH 2/3] Patch 2
> + | +--> Re: [PATCH 2/3] Patch 2 (reviewer comments)
> + | +--> [PATCH v2 2/3] Patch 2 (v2 of patch 2/3)
> + +--> [PATCH 3/3] Patch 3
> +
> +Patch work will create a new *revision* of the series, updating patch
> +#2 to the new version of that patch.
> +
> +New Series
> +~~~~~~~~~~
> +
> +When something is really wrong or when, to address the review, most
> +patches of a series need to be revised, re-sending individual emails can
> +be both annoying for the patch author but also hard to follow from the
> +reviewer side. It's then better to re-send a full new thread and forget
> +the previous one.
> +
> +Patchwork will get that and create a new revision of the initial series
> +with all patches updated to the latest and greatest.
> +
> +::
> +
> + + [PATCH 0/3] Cover Letter Subject
> + +--> [PATCH 1/3] Patch 1
> + +--> [PATCH 2/3] Patch 2
> + +--> [PATCH 3/3] Patch 3
> +
> + + [PATCH v2 0/3] Cover Letter Subject
> + +--> [PATCH v2 1/3] Patch 1 (v2 of patch 1/3)
> + +--> [PATCH v2 2/3] Patch 2 (v2 of patch 2/3)
> + +--> [PATCH v2 3/3] Patch 3 (v2 of patch 3/3)
> +
> +Patchwork uses the cover letter subject to detect that intent. So one
> +doesn't need to use the ``reroll-count`` like above, the following
> +would work as well:
> +
> +::
> +
> + + [PATCH 0/3] Cover Letter Subject
> + +--> [PATCH 1/3] Patch 1
> + +--> [PATCH 2/3] Patch 2
> + +--> [PATCH 3/3] Patch 3
> +
> + + [PATCH 0/3] Cover Letter Subject (v2)
> + +--> [PATCH 1/3] Patch 1 (v2 of patch 1/3)
> + +--> [PATCH 2/3] Patch 2 (v2 of patch 2/3)
> + +--> [PATCH 3/3] Patch 3 (v2 of patch 3/3)
> +
> +Of course, we've now entered a dangerous territory. Trying to parse some
> +human-generated text. The regular expression used accepts several ways
> +of saying that the series is a new version of a previous one. If your
> +favourite way isn't among what's supported, consider contributing (like
> +filing an issue)!
> +
> +Considering an initial series with ``Awesome feature`` as the cover
> +letter subject, Patchwork will considering series with the following
> +cover letter subjects as new revisions:
> +
> + +---------------------------------+----------------------------+
> + | Regular Expression | Cover Letter |
> + +---------------------------------+----------------------------+
> + | | - Awesome feature |
> + | | - awesome feature |
> + +---------------------------------+----------------------------+
> + | ``[, \(]*(v|take)[\) 0-9]+$')`` | - Awesome feature v2 |
> + | | - awesome feature V2 |
> + | | - Awesome feature, v3 |
> + | | - Awesome feature (v4) |
> + | | - Awesome feature (take 5) |
> + | | - Awesome feature, take 6 |
> + +---------------------------------+----------------------------+
> --
> 2.1.0
>
> _______________________________________________
> Patchwork mailing list
> Patchwork at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork
More information about the Patchwork
mailing list