blob: 07f3300c6cda48407a115577031a9382809c2870 [file] [log] [blame]
Stable maintainer tools
===============================
This set of tools is useful for people who maintain -stable like trees either
with collaboration with the community, or privately inside their company.
The focus of this tool is sharing the knowledge and work done by multiple
-stable tree maintainers without creating overhead for each maintainer.
Configuration is simple, and consists of 3 environment variables. For example,
in my case they are:
export STABLE_MAJ_VER="3" # The major version of the tree I'm maintaining
export STABLE_MIN_VER="18" # The minor version of the tree I'm maintaining
export OTHER_STABLE_TREES="stable/linux-3.10.y stable/linux-3.14.y stable/linux-4.1.y stable/linux-4.2.y" # Other -stable trees that live within the same repository.
Commands:
1) stable commit-in-tree <commit sha1>
This is useful to find if a given commit exists in the local branch. While in
the trivial case it would be enough to just check whether the sha1 exists in
the current branch, but in reality this is slightly more complicated.
Consider the case we're looking at a mainline commit and see "Fixes: <sha1>
("description"), there's a possiblity that we've pulled in the commit pointed
by the "fixes" tag earlier, which means that it'll have a different sha1 in
our branch, in which case we won't see it if we follow the trivial path.
Instead, we'll look up the commit's subject and search by that.
There is still a problem here: since we can't look only in subject lines,
grepping for a subject line might instead point to a different commit that
only contains the subject line of the commit we're looking for in it's own
commit message. In that case, we must do a more expensive search and evaluate
all commits containing the given subject line.
2) stable find-alts <commit sha1>
Provides a list of commits with the same subject line in other stable branches.
An example use case is to compare backport of a patch with the way other
maintainers have done it.
3) stable make-pretty <commit sha1> [message]
Formats a commit message with the standard stable formatting. The script grabs
the commit message from the upstream commit and adds a "Upstream version ..."
tag.
The user can optionally pass a message to be used rather than using the
upstream commit's message.
4) stable show-missing <commit range>
Show all commits that exist in the provided range but don't exist in the local
branch. Script is using the comparison described in commit-in-tree.
This is useful to audit the differences between a newly build tree vs
a different one to verify that all required commits were picked in.