diff options
| -rw-r--r-- | doc/develop/pics/patman.jpg | bin | 0 -> 97131 bytes | |||
| -rw-r--r-- | tools/patman/patman.rst | 283 |
2 files changed, 280 insertions, 3 deletions
diff --git a/doc/develop/pics/patman.jpg b/doc/develop/pics/patman.jpg Binary files differnew file mode 100644 index 00000000000..2dcf598e088 --- /dev/null +++ b/doc/develop/pics/patman.jpg diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst index 63b95a6b161..549e203c254 100644 --- a/tools/patman/patman.rst +++ b/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 -------------- |
