blob: f0f14af65d4e7a2c85abf43df36f84fadc07163a [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.
export STABLE_BASE="v3.18" # The point where mainline ends and -stable starts
for the current branch. Useful to speed up lookups.
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.
4) stable show-missing-stable <commit range>
Similar to show-missing, but only shows commits that are also marked for
stable inclusion.
This is useful to run with a mainline commit range to audit that all
relevant commits marked for stable are in the local branch.
5) stable yank <commit sha1>
Remove a commit out of the current branch. The user will need to fix merge
conflicts if such exist after removing that commit.
6) stable steal-commits <commit range> [branch]
Goes through every commit in range and:
- If it has a fixes tag, checks if the patch to be fixed is in the branch.
- If it has a version tag, checks whether it applies to our current version.
If either the commit to be fixed isn't in the branch or the version is newer
than us, we skip the commit. Otherwise, it would try to cherry-pick and
format the commit message to match the -stable standard. If cherry-picking
has created conflicts the script would spawn a shell for the user to fix
the conflicts and commit the changes, resuming by exiting the shell.
This is useful as an automatic first pass to copy commits from another stable
branch, the result should later be audited for correctness - the main purpose
is to get the trivial things out of the way.
7) stable audit-range <commit range>
Provides a human readable output comparing the commit range with the current
branch. This is a simple way to find out about commits not in current branch
and:
- Tagged for stable and which other stable branches they are present in.
- Not tagged for stable, but are present in other stable branches.
8) stable deps <commit sha1> [Max deps to show]
Build a list of dependencies to apply the provided commit cleanly.
This is useful when looking into whether a commit should be backported to the
current branch, and if so, which commits does it depend on.
Once the dependency list is provided, it should be easy to decide whether the
commits should be pulled in as well, or whether the commit should be backported
by small changes to the commit itself (or both).
9) stable insert <before sha1> <commit sha1>
Inserts the commit before the "before" commit. Useful to insert in forgotted
dependencies.