| Message ID | 1445378383-16977-15-git-send-email-damien.lespiau@intel.com |
|---|---|
| State | Rejected |
| Headers | show |
> It's really necessary to start documenting what Patchwork knows about > when parsing emails. You didn't address all of my comments, so I've re-raised them below (along with some other...niggles). > This time, it's about series and new revision of series. > > v2: Add back --annotate to the git send-email > v3: Fix a few nit picks (Stephen Finucane) Forgive me, but this seem rather passive-aggressive. If that was your intention then please note that it's my job to review patches: comments in reviews are never personal and shouldn't be taken as such. If you don't agree with said comments them please discuss them with me or refrain from submitting stuff. It's not a nice environment to work in. > Signed-off-by: Damien Lespiau <damien.lespiau@intel.com> > --- > docs/index.rst | 1 + > docs/manual.rst | 143 Why does this need to be in rST? There is nothing here that suggests this is necessary? > ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 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..11e2ee9 > --- /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 ``master``, have three patches to > +submit, we can use: > + > +:: > + > + $ git send-email --to=<mailing-list> --cover-letter --annotate 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 > + > +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. > + > +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. > + > +New Versions > +------------ > + > +Sometimes, maybe even more often than hoped, one needs to resend a few > +patches or even entire series to address review comments. > + > +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 > +~~~~~~~~~ This section is still here? I don't feel comfortable dictating workflows for projects: it's too specific and there are many more comprehensive resources on the web about this topic. Unless you have an exceptionally good reason to include it then please drop this and, if you must, put this in your blog and include a link to that. > + > +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.4.3 > > _______________________________________________ > Patchwork mailing list > Patchwork@lists.ozlabs.org > https://lists.ozlabs.org/listinfo/patchwork
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..11e2ee9 --- /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 ``master``, have three patches to +submit, we can use: + +:: + + $ git send-email --to=<mailing-list> --cover-letter --annotate 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 + +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. + +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. + +New Versions +------------ + +Sometimes, maybe even more often than hoped, one needs to resend a few +patches or even entire series to address review comments. + +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 +~~~~~~~~~ + +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 | + +---------------------------------+----------------------------+
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. v2: Add back --annotate to the git send-email v3: Fix a few nit picks (Stephen Finucane) Signed-off-by: Damien Lespiau <damien.lespiau@intel.com> --- docs/index.rst | 1 + docs/manual.rst | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 docs/manual.rst