README - pub/scm/linux/kernel/git/sashal/stable-tools - Git at Google

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