+# SPDX-License-Identifier: GPL-2.0+
# Copyright (c) 2011 The Chromium OS Authors.
-#
-# SPDX-License-Identifier: GPL-2.0+
-#
What is this?
=============
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 most cases of using patman for U-Boot development, patman can use the
+file 'doc/git-mailrc' in your U-Boot directory to supply the email aliases
+you need. To make this work, tell git where to find the file by typing
+this once:
-For Linux the 'scripts/get_maintainer.pl' handles figuring out where
-to send patches pretty well.
+ git config sendemail.aliasesfile doc/git-mailrc
+
+For both Linux and U-Boot 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.
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 avoid sending patches to email addresses that are picked up
+by patman but are known to bounce you can add a [bounces] section to your
+.patman file. Unlike the [alias] section these are simple key: value pairs
+that are not recursive.
+
+>>>
+
+[bounces]
+
+<<<
+
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
ignore_errors: True
process_tags: False
verbose: True
+smtp_server: /path/to/sendmail
<<<
is useful if your top commit is for setting up testing.
+How to install it
+=================
+
+The most up to date version of patman can be found in the U-Boot sources.
+However to use it on other projects it may be more convenient to install it as
+a standalone application. A distutils installer is included, this can be used
+to install patman:
+
+$ cd tools/patman && python setup.py install
+
+
How to add tags
===============
Series-prefix: prefix
Sets the subject prefix. Normally empty but it can be RFC for
- RFC patches, or RESEND if you are being ignored.
+ RFC patches, or RESEND if you are being ignored. The patch subject
+ is like [RFC PATCH] or [RESEND PATCH].
+ In the meantime, git format.subjectprefix option will be added as
+ well. If your format.subjectprefix is set to InternalProject, then
+ the patch shows like: [InternalProject][RFC/RESEND PATCH]
Series-name: name
Sets the name of the series. You don't need to have a name, and
to update the log there and then, knowing that the script will
do the rest.
+Commit-changes: n
+- This line will not appear in the cover-letter changelog
+<blank line>
+ This tag is like Series-changes, except changes in this changelog will
+ only appear in the changelog of the commit this tag is in. This is
+ useful when you want to add notes which may not make sense in the cover
+ letter. For example, you can have short changes such as "New" or
+ "Lint".
+
+Cover-changes: n
+- This line will only appear in the cover letter
+<blank line>
+ This tag is like Series-changes, except changes in this changelog will
+ only appear in the cover-letter changelog. This is useful to summarize
+ changes made with Commit-changes, or to add additional context to
+ changes.
+
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.
+ This tells patman to sort and/or uniq the change logs. Changes may be
+ multiple lines long, as long as each subsequent line of a change begins
+ with a whitespace character. For example,
+
+- This change
+ continues onto the next line
+- But this change is separate
+
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.
+Change-Id:
+ This tag is stripped out but is used to generate the Message-Id
+ of the emails that will be sent. When you keep the Change-Id the
+ same you are asserting that this is a slightly different version
+ (but logically the same patch) as other patches that have been
+ sent out with the same Change-Id.
+
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)
not later when you can't remember which patch you changed. You can always
go back and change or remove logs from commits.
+7. Some mailing lists have size limits and when we add binary contents to
+our patches it's easy to exceed the size limits. Use "--no-binary" to
+generate patches without any binary contents. You are supposed to include
+a link to a git repository in your "Commit-notes", "Series-notes" or
+"Cover-letter" for maintainers to fetch the original commit.
+
+8. Patches will have no changelog entries for revisions where they did not
+change. For clarity, if there are no changes for this patch in the most
+recent revision of the series, a note will be added. For example, a patch
+with the following tags in the commit
+
+ Series-version: 5
+ Series-changes: 2
+ - Some change
+
+ Series-changes: 4
+ - Another change
+
+would have a changelog of
+
+ (no changes since v4)
+
+ Changes in v4:
+ - Another change
+
+ Changes in v2:
+ - Some change
Other thoughts
==============
projects / u-boot.git / blobdiff