[Concept,29/29] patman: Document review behaviours added in this series
Commit Message
From: Simon Glass <sjg@chromium.org>
Several review-related improvements have landed without corresponding
documentation:
- 'series info' is now colour-coded by patchwork state, and its '-r'
flag accepts an optional list of patch numbers to limit the review
text it prints.
- 'series gather' (and 'gather-all') print a notice when every patch
in the gathered version has reached state 'accepted', confirming
upstream landing without a separate query.
- The review apply step stashes the working tree -- including
untracked files -- before checking out the review branch and
restores it on exit, so build artefacts from the current branch
don't leak in.
- A partial or interrupted apply aborts with a clear message and
rolls back the database row, rather than letting the review run
against an incomplete series.
Add short paragraphs covering each of these in the right place
(``series info`` description, ``How the review works`` apply step,
and the ``series gather`` walk-through).
Signed-off-by: Simon Glass <sjg@chromium.org>
---
tools/patman/patman.rst | 24 +++++++++++++++++++++++-
1 file changed, 23 insertions(+), 1 deletion(-)
@@ -759,7 +759,10 @@ Here is a short overview of the available subcommands:
info
Show detailed information about a series, including each
version's link, description, patches and any stored reviews.
- Use ``-r`` to include review text.
+ The output is colour-coded by patchwork state (e.g. ``new``,
+ ``accepted``). Use ``-r`` to include review text; pass a list
+ of patch numbers (``-r 1 3``) to limit the review text to those
+ patches.
ls
Lists the series in the database. Use ``-r`` to show only
@@ -895,6 +898,10 @@ To gather tags (Reviewed-by ...) for your series from patchwork::
patman series gather
+If every patch in the gathered version has reached state ``accepted``,
+patman prints a notice that the series has been applied upstream. The
+same check runs for ``patman series gather-all``.
+
Now you can check your progress::
patman series progress
@@ -1339,6 +1346,21 @@ excluded from refinement to preserve their quoted commit messages.
A mechanical cleanup step also runs to remove backticks and fix function
quoting style (e.g. ``malloc()`` not ```malloc```).
+Apply step
+~~~~~~~~~~
+
+Before checking out the review branch, patman stashes any uncommitted
+changes -- including untracked files -- so build artefacts on the
+current branch don't leak into the review. The original branch and
+stash are restored at the end of the run, including on failure.
+
+If the apply agent finishes but the resulting branch holds fewer
+commits than the series cover letter advertises, patman aborts with a
+message of the form ``Only N of M patches applied to <branch>;
+aborting. Fix the conflicts manually and retry.`` The database row
+for the new version is rolled back so a retry starts from a clean
+state.
+
Patchwork subcommands
---------------------