patman: Add basic documentation for new features

Describe the new subcommands and how they should be used in a normal
workflow.

Note that the naming of branches is very rigid, or 'opinionated' in
marketing terms. Patman can track a single branch for each version of a
series and they must all be named the same, except for the
version-number suffix. Version 1 series have no suffix.

This description is fairly bare-bones but should be enough for some
initial testing and comments.

Signed-off-by: Simon Glass <sjg@chromium.org>

tools/patman/patman.rst

@@ -16,12 +16,13 @@ This tool is a Python script which:
 - Inserts a cover letter with change lists
 - Runs the patches through checkpatch.pl and its own checks
 - Optionally emails them out to selected people
+- Links the series automatically to Patchwork once sent
 
 It also has some Patchwork features:
 
-- shows review tags from Patchwork so you can update your local patches
-- pulls these down into a new branch on request
-- lists comments received on a series
+- Manage local series and their status on patchwork
+- Show review tags from Patchwork and allows them to be gathered into commits
+- List comments received on a series
 
 It is intended to automate patch creation and make it a less
 error-prone process. It is useful for U-Boot and Linux work so far,
@@ -659,6 +660,282 @@ so to send them:
 and it will create and send the version 2 series.
 
 
+Series Management
+-----------------
+
+Sometimes you might have several series in flight at the same time. Each of
+these receives comments and you want to create a new version of each series with
+those comments addressed.
+
+Patman provides a few subcommands which are helpful for managing series.
+
+Series and branches
+~~~~~~~~~~~~~~~~~~~
+
+'patman series' works with the concept of a series. It maintains a local
+database (.patman.db in your top-level git tree) and uses that to keep track of
+series and patches.
+
+Each series goes through muliple versions. Patman requires that the first
+version of your series is in a branch without a numeric suffix. Branch names
+like 'serial' and 'video' are OK, but 'part3' is not. This is because Patman
+uses the number at the end of the branch name to indicate the version.
+
+If your series name is 'video', then you can have a 'video' branch for version
+1 of the series, 'video2' for version 2 and 'video3' for version 3. All three
+branches are for the same series. Patman keeps track of these different
+versions. It handles the branch naming automatically, but you need to be aware
+of what it is doing.
+
+You will have an easier time if the branch names you use with 'patman series'
+are short, no more than 15 characters. This is the amount of columnar space in
+listings. You can add a longer description as the series description. If you
+are used to having very descriptive branch names, remember that patman lets you
+add metadata into commit which is automatically removed before sending.
+
+This documentation uses the term 'series' to mean all the versions of a series
+and 'series/version' to mean a particular version of a series.
+
+Updating commits
+~~~~~~~~~~~~~~~~
+
+Since Patman provides quite a bit of automation, it updates your commits in
+some cases, effectively doing a rebase of a branch in order to change the tags
+in the commits. It never makes code changes.
+
+In extremis you can use 'git reflog' to revert something that Patman did.
+
+
+Series subcommands
+~~~~~~~~~~~~~~~~~~
+
+Note that 'patman series ...' can be abbreviated as 'patman s' or 'patman ser'.
+
+Here is a short overview of the available subcommands:
+
+    add
+        Add a new series. Use this on an existing branch to tell Patman about it.
+
+    archive (ar)
+        Archive a series when you have finished upstreaming it. Archived series
+        are not shown by most commands. This creates a dated tag for each
+        version of the series, pointing to the series branch, then deletes the
+        branches. It puts the tag names in the database so that it can
+        'unarchive' to restore things how they were.
+
+    unarchive (unar)
+        Unarchive a series when you decide you need to do something more with
+        it. The branches are restored and tags deleted.
+
+    autolink (au)
+        Search patchwork for the series link for your series, so Patman can
+        track the status
+
+    autolink-all
+        Same but for all series
+
+    inc
+        Increase the series number, effectively creating a new branch with the
+        next highest version number. The new branch is created based on the
+        existing branch. So if you use 'patman series inc' on branch 'video2'
+        it will create branch 'video3' and add v3 into its database
+
+    dec
+        Decrease the series number, thus deleting the current branch and
+        removing that version from the data. If you use this comment on branch
+        'video3' Patman will delete version 3 and branch 'video3'.
+
+    get-link
+        Shows the Patchwork link for a series/version
+
+    ls
+        Lists the series in the database
+
+    mark
+        Mark a series with 'Change-Id' tags so that Patman can track patches
+        even when the subject changes. Unmarked patches just use the subject to
+        decided which is which.
+
+    unmark
+        Remove 'Change-Id' tags from a series.
+
+    open (o)
+        Open a series in Patchwork using your web browser
+
+    patches
+        Show the patches in a particular series/version
+
+    progress (p)
+        Show upstream progress for your series, or for all series
+
+    rm
+        Remove a series entirely, including all versions
+
+    rm-version (rmv)
+        Remove a particular version of a series. This is similar to 'dec'
+        except that any version can be removed, not just the latest one.
+
+    scan
+        Scan the local branch and update the database with the set of patches
+        in that branch. This throws away the old patches.
+
+    send
+        Send a series out as patches. This is similar to 'patman send' except
+        that it can send any series, not just the current branch. It also
+        waits a little for patchwork to see the cover letter, so it can find
+        out the patchwork link for the series.
+
+    set-link
+        Sets the Patchwork link for a series-version manually.
+
+    status (st)
+        Run 'patman status' on a series. This is similar to 'patman status'
+        except that it can get status on any series, not just the current
+        branch
+
+    summary
+        Shows a quick summary of series with their status and description.
+
+    sync
+        Sync the status of a series with Pathwork, so that
+        'patman series progress' can show the right information.
+
+    sync-all
+        Sync the status of all series.
+
+
+Patman series workflow
+~~~~~~~~~~~~~~~~~~~~~~
+
+Here is a run-through of how to incorporate 'patman series' into your workflow.
+
+Firstly, set up your project::
+
+    patman patchwork set-project U-Boot
+
+This just tells Patman to look on the Patchwork server for a project of that
+name. Internally Patman stores the ID and URL 'link-name' for the project, so it
+can access it.
+
+If you need to use a different patchwork server, use the `--patchwork-url`
+option or put the URL in your Patman-settings file.
+
+Now create a branch. For our example we are going to send out a series related
+to video so the branch will be called 'video'. The upstream remove is called
+'us'::
+
+    git checkout -b video us/master
+
+We now have a branch and so we can do some commits::
+
+    <edit files>
+    git add ...
+    <edit files>
+    git add -u
+    git commit ...
+    git commit ...
+
+We now have a few commits in our 'video' branch. Let's tell patman about it::
+
+    patman series add
+
+Like most commands, if no series is given (`patman series -s video add`) then
+the current branch is assumed. Since the branch is called 'video' patman knows
+that it is version one of the video series.
+
+You'll likely get a warning that there is no cover letter. Let's add some tags
+to the top commit::
+
+    Series-to: u-boot
+    Series-cc: ...
+    Cover-letter:
+    video: Improve syncing performance with cyclic
+
+Trying again::
+
+    patman series add
+
+You'll likely get a warning that the commits are unmarked. You can either let
+patman add Change-Id values itself with the `-m` flag, or tell it not to worry
+about it with `-M`. You must choose one or the other. Let's leave the commits
+unmarked::
+
+    patman series add -M
+
+Congratulations, you've now got a patman database!
+
+Now let's send out the series. We will add tags to the top commit.
+
+To send it::
+
+    patman series send
+
+You should send 'git send-email' start up and you can confirm the sending of
+each email.
+
+After that, patman waits a bit to see if it can find your new series appearing
+on Patchwork. With a bit of luck this will only take 20 seconds or so. Then your
+series is linked.
+
+To gather tags (Reviewed-by ...) for your series from patchwork::
+
+    patman series gather
+
+Now you can check your progress::
+
+    patman series progress
+
+Later on you get some comments, or perhaps you just decide to make a change on
+your own. You have several options.
+
+The first option is that you can just create a new branch::
+
+    git checkout -b video2 video
+
+then you can add this 'v2' series to Patman with::
+
+    patman series add
+
+The second option is to get patman to create the new 'video2' branch in one
+step::
+
+    patman inc
+
+The third option is to collect some tags using the 'patman status' command and
+put them in a new branch::
+
+    patman status -d video2
+
+One day the fourth option will be to ask patman to collect tags as part of the
+'patman inc' command.
+
+Again, you do your edits, perhaps adding/removing patches, rebasing on -master
+and so on. Then, send your v2::
+
+    patman series send
+
+Let's say the patches are accepted. You can use::
+
+    patch series gather
+    patch series progress
+
+to check, or::
+
+    patman series status -cC
+
+to see comments. You can now archive the series::
+
+    patman series archive
+
+At this point you have the basics. Some of the subcommands useful options, so
+be sure to check out the help.
+
+Here is a sample 'progress' view:
+
+.. image:: pics/patman.jpg
+  :width: 800
+  :alt: Patman showing the progress view
+
 General points
 --------------