|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.
|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 ..."
|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
|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
| - 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>
|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).