diff options
Diffstat (limited to 'qemu/roms/u-boot/tools/patman/README')
| -rw-r--r-- | qemu/roms/u-boot/tools/patman/README | 468 |
1 files changed, 0 insertions, 468 deletions
diff --git a/qemu/roms/u-boot/tools/patman/README b/qemu/roms/u-boot/tools/patman/README deleted file mode 100644 index 5fb508b80..000000000 --- a/qemu/roms/u-boot/tools/patman/README +++ /dev/null @@ -1,468 +0,0 @@ -# Copyright (c) 2011 The Chromium OS Authors. -# -# SPDX-License-Identifier: GPL-2.0+ -# - -What is this? -============= - -This tool is a Python script which: -- Creates patch directly from your branch -- Cleans them up by removing unwanted tags -- Inserts a cover letter with change lists -- Runs the patches through checkpatch.pl and its own checks -- Optionally emails them out to selected people - -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, -since it uses the checkpatch.pl script. - -It is configured almost entirely by tags it finds in your commits. -This means that you can work on a number of different branches at -once, and keep the settings with each branch rather than having to -git format-patch, git send-email, etc. with the correct parameters -each time. So for example if you put: - -Series-to: fred.blogs@napier.co.nz - -in one of your commits, the series will be sent there. - -In Linux this will also call get_maintainer.pl on each of your -patches automatically. - - -How to use this tool -==================== - -This tool requires a certain way of working: - -- Maintain a number of branches, one for each patch series you are -working on -- Add tags into the commits within each branch to indicate where the -series should be sent, cover letter, version, etc. Most of these are -normally in the top commit so it is easy to change them with 'git -commit --amend' -- Each branch tracks the upstream branch, so that this script can -automatically determine the number of commits in it (optional) -- Check out a branch, and run this script to create and send out your -patches. Weeks later, change the patches and repeat, knowing that you -will get a consistent result each time. - - -How to configure it -=================== - -For most cases of using patman for U-Boot development, patman will -locate and use the file 'doc/git-mailrc' in your U-Boot directory. -This contains most of the aliases you will need. - -For Linux the 'scripts/get_maintainer.pl' handles figuring out where -to send patches pretty well. - -During the first run patman creates a config file for you by taking the default -user name and email address from the global .gitconfig file. - -To add your own, create a file ~/.patman like this: - ->>>> -# patman alias file - -[alias] -me: Simon Glass <sjg@chromium.org> - -u-boot: U-Boot Mailing List <u-boot@lists.denx.de> -wolfgang: Wolfgang Denk <wd@denx.de> -others: Mike Frysinger <vapier@gentoo.org>, Fred Bloggs <f.bloggs@napier.net> - -<<<< - -Aliases are recursive. - -The checkpatch.pl in the U-Boot tools/ subdirectory will be located and -used. Failing that you can put it into your path or ~/bin/checkpatch.pl - - -If you want to change the defaults for patman's command-line arguments, -you can add a [settings] section to your .patman file. This can be used -for any command line option by referring to the "dest" for the option in -patman.py. For reference, the useful ones (at the moment) shown below -(all with the non-default setting): - ->>> - -[settings] -ignore_errors: True -process_tags: False -verbose: True - -<<< - - -If you want to adjust settings (or aliases) that affect just a single -project you can add a section that looks like [project_settings] or -[project_alias]. If you want to use tags for your linux work, you could -do: - ->>> - -[linux_settings] -process_tags: True - -<<< - - -How to run it -============= - -First do a dry run: - -$ ./tools/patman/patman -n - -If it can't detect the upstream branch, try telling it how many patches -there are in your series: - -$ ./tools/patman/patman -n -c5 - -This will create patch files in your current directory and tell you who -it is thinking of sending them to. Take a look at the patch files. - -$ ./tools/patman/patman -n -c5 -s1 - -Similar to the above, but skip the first commit and take the next 5. This -is useful if your top commit is for setting up testing. - - -How to add tags -=============== - -To make this script useful you must add tags like the following into any -commit. Most can only appear once in the whole series. - -Series-to: email / alias - Email address / alias to send patch series to (you can add this - multiple times) - -Series-cc: email / alias, ... - Email address / alias to Cc patch series to (you can add this - multiple times) - -Series-version: n - Sets the version number of this patch series - -Series-prefix: prefix - Sets the subject prefix. Normally empty but it can be RFC for - RFC patches, or RESEND if you are being ignored. - -Series-name: name - Sets the name of the series. You don't need to have a name, and - patman does not yet use it, but it is convenient to put the branch - name here to help you keep track of multiple upstreaming efforts. - -Cover-letter: -This is the patch set title -blah blah -more blah blah -END - Sets the cover letter contents for the series. The first line - will become the subject of the cover letter - -Cover-letter-cc: email / alias - Additional email addresses / aliases to send cover letter to (you - can add this multiple times) - -Series-notes: -blah blah -blah blah -more blah blah -END - Sets some notes for the patch series, which you don't want in - the commit messages, but do want to send, The notes are joined - together and put after the cover letter. Can appear multiple - times. - -Commit-notes: -blah blah -blah blah -more blah blah -END - Similar, but for a single commit (patch). These notes will appear - immediately below the --- cut in the patch file. - - Signed-off-by: Their Name <email> - A sign-off is added automatically to your patches (this is - probably a bug). If you put this tag in your patches, it will - override the default signoff that patman automatically adds. - Multiple duplicate signoffs will be removed. - - Tested-by: Their Name <email> - Reviewed-by: Their Name <email> - Acked-by: Their Name <email> - These indicate that someone has tested/reviewed/acked your patch. - When you get this reply on the mailing list, you can add this - tag to the relevant commit and the script will include it when - you send out the next version. If 'Tested-by:' is set to - yourself, it will be removed. No one will believe you. - -Series-changes: n -- Guinea pig moved into its cage -- Other changes ending with a blank line -<blank line> - This can appear in any commit. It lists the changes for a - particular version n of that commit. The change list is - created based on this information. Each commit gets its own - change list and also the whole thing is repeated in the cover - letter (where duplicate change lines are merged). - - By adding your change lists into your commits it is easier to - keep track of what happened. When you amend a commit, remember - to update the log there and then, knowing that the script will - do the rest. - -Patch-cc: Their Name <email> - This copies a single patch to another email address. Note that the - Cc: used by git send-email is ignored by patman, but will be - interpreted by git send-email if you use it. - -Series-process-log: sort, uniq - This tells patman to sort and/or uniq the change logs. It is - assumed that each change log entry is only a single line long. - Use 'sort' to sort the entries, and 'uniq' to include only - unique entries. If omitted, no change log processing is done. - Separate each tag with a comma. - -Various other tags are silently removed, like these Chrome OS and -Gerrit tags: - -BUG=... -TEST=... -Change-Id: -Review URL: -Reviewed-on: -Commit-xxxx: (except Commit-notes) - -Exercise for the reader: Try adding some tags to one of your current -patch series and see how the patches turn out. - - -Where Patches Are Sent -====================== - -Once the patches are created, patman sends them using git send-email. The -whole series is sent to the recipients in Series-to: and Series-cc. -You can Cc individual patches to other people with the Patch-cc: tag. Tags -in the subject are also picked up to Cc patches. For example, a commit like -this: - ->>>> -commit 10212537b85ff9b6e09c82045127522c0f0db981 -Author: Mike Frysinger <vapier@gentoo.org> -Date: Mon Nov 7 23:18:44 2011 -0500 - - x86: arm: add a git mailrc file for maintainers - - This should make sending out e-mails to the right people easier. - - Patch-cc: sandbox, mikef, ag - Patch-cc: afleming -<<<< - -will create a patch which is copied to x86, arm, sandbox, mikef, ag and -afleming. - -If you have a cover letter it will get sent to the union of the Patch-cc -lists of all of the other patches. If you want to sent it to additional -people you can add a tag: - -Cover-letter-cc: <list of addresses> - -These people will get the cover letter even if they are not on the To/Cc -list for any of the patches. - - -Example Work Flow -================= - -The basic workflow is to create your commits, add some tags to the top -commit, and type 'patman' to check and send them. - -Here is an example workflow for a series of 4 patches. Let's say you have -these rather contrived patches in the following order in branch us-cmd in -your tree where 'us' means your upstreaming activity (newest to oldest as -output by git log --oneline): - - 7c7909c wip - 89234f5 Don't include standard parser if hush is used - 8d640a7 mmc: sparc: Stop using builtin_run_command() - 0c859a9 Rename run_command2() to run_command() - a74443f sandbox: Rename run_command() to builtin_run_command() - -The first patch is some test things that enable your code to be compiled, -but that you don't want to submit because there is an existing patch for it -on the list. So you can tell patman to create and check some patches -(skipping the first patch) with: - - patman -s1 -n - -If you want to do all of them including the work-in-progress one, then -(if you are tracking an upstream branch): - - patman -n - -Let's say that patman reports an error in the second patch. Then: - - git rebase -i HEAD~6 - <change 'pick' to 'edit' in 89234f5> - <use editor to make code changes> - git add -u - git rebase --continue - -Now you have an updated patch series. To check it: - - patman -s1 -n - -Let's say it is now clean and you want to send it. Now you need to set up -the destination. So amend the top commit with: - - git commit --amend - -Use your editor to add some tags, so that the whole commit message is: - - The current run_command() is really only one of the options, with - hush providing the other. It really shouldn't be called directly - in case the hush parser is bring used, so rename this function to - better explain its purpose. - - Series-to: u-boot - Series-cc: bfin, marex - Series-prefix: RFC - Cover-letter: - Unified command execution in one place - - At present two parsers have similar code to execute commands. Also - cmd_usage() is called all over the place. This series adds a single - function which processes commands called cmd_process(). - END - - Change-Id: Ica71a14c1f0ecb5650f771a32fecb8d2eb9d8a17 - - -You want this to be an RFC and Cc the whole series to the bfin alias and -to Marek. Two of the patches have tags (those are the bits at the front of -the subject that say mmc: sparc: and sandbox:), so 8d640a7 will be Cc'd to -mmc and sparc, and the last one to sandbox. - -Now to send the patches, take off the -n flag: - - patman -s1 - -The patches will be created, shown in your editor, and then sent along with -the cover letter. Note that patman's tags are automatically removed so that -people on the list don't see your secret info. - -Of course patches often attract comments and you need to make some updates. -Let's say one person sent comments and you get an Acked-by: on one patch. -Also, the patch on the list that you were waiting for has been merged, -so you can drop your wip commit. So you resync with upstream: - - git fetch origin (or whatever upstream is called) - git rebase origin/master - -and use git rebase -i to edit the commits, dropping the wip one. You add -the ack tag to one commit: - - Acked-by: Heiko Schocher <hs@denx.de> - -update the Series-cc: in the top commit: - - Series-cc: bfin, marex, Heiko Schocher <hs@denx.de> - -and remove the Series-prefix: tag since it it isn't an RFC any more. The -series is now version two, so the series info in the top commit looks like -this: - - Series-to: u-boot - Series-cc: bfin, marex, Heiko Schocher <hs@denx.de> - Series-version: 2 - Cover-letter: - ... - -Finally, you need to add a change log to the two commits you changed. You -add change logs to each individual commit where the changes happened, like -this: - - Series-changes: 2 - - Updated the command decoder to reduce code size - - Wound the torque propounder up a little more - -(note the blank line at the end of the list) - -When you run patman it will collect all the change logs from the different -commits and combine them into the cover letter, if you have one. So finally -you have a new series of commits: - - faeb973 Don't include standard parser if hush is used - 1b2f2fe mmc: sparc: Stop using builtin_run_command() - cfbe330 Rename run_command2() to run_command() - 0682677 sandbox: Rename run_command() to builtin_run_command() - -so to send them: - - patman - -and it will create and send the version 2 series. - -General points: - -1. When you change back to the us-cmd branch days or weeks later all your -information is still there, safely stored in the commits. You don't need -to remember what version you are up to, who you sent the last lot of patches -to, or anything about the change logs. - -2. If you put tags in the subject, patman will Cc the maintainers -automatically in many cases. - -3. If you want to keep the commits from each series you sent so that you can -compare change and see what you did, you can either create a new branch for -each version, or just tag the branch before you start changing it: - - git tag sent/us-cmd-rfc - ...later... - git tag sent/us-cmd-v2 - -4. If you want to modify the patches a little before sending, you can do -this in your editor, but be careful! - -5. If you want to run git send-email yourself, use the -n flag which will -print out the command line patman would have used. - -6. It is a good idea to add the change log info as you change the commit, -not later when you can't remember which patch you changed. You can always -go back and change or remove logs from commits. - - -Other thoughts -============== - -This script has been split into sensible files but still needs work. -Most of these are indicated by a TODO in the code. - -It would be nice if this could handle the In-reply-to side of things. - -The tests are incomplete, as is customary. Use the --test flag to run them, -and make sure you are in the tools/patman directory first: - - $ cd /path/to/u-boot - $ cd tools/patman - $ ./patman --test - -Error handling doesn't always produce friendly error messages - e.g. -putting an incorrect tag in a commit may provide a confusing message. - -There might be a few other features not mentioned in this README. They -might be bugs. In particular, tags are case sensitive which is probably -a bad thing. - - -Simon Glass <sjg@chromium.org> -v1, v2, 19-Oct-11 -revised v3 24-Nov-11 |