os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

MFC: update advice on MFC practices

Browse source 
Highlight MFC to a branch needing approval
Rearrange a couple sections to improve document structure.
Change some enumeration lists to bulleted lists since I think that looks nicer.
This commit is contained in:
Warner Losh 2021-03-18 14:30:53 -06:00
parent b4977a4f42
commit 0181ba1611
1 changed files with 38 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
documentation/content/en/articles/committers-guide/_index.adoc
View file

@ -712,6 +712,24 @@ up and do a `git cherry-pick --continue`.
Once the cherry-pick is finished, push with `git push`. If you get an error due to losing the commit race, Once the cherry-pick is finished, push with `git push`. If you get an error due to losing the commit race,
use `git pull --rebase` and try to push again. use `git pull --rebase` and try to push again.
==== MFC to RELENG branch
MFCs to branches that require approval require a bit more care.
The process is the same for either a typical merge or an exceptional direct commit.
* Merge or direct commit to the appropriate `stable/X` branch first before merging to the `releng/X.Y` branch.
* Use the hash that's in the `stable/X` branch for the MFC to `releng/X.Y` branch.
* Leave both "cherry picked from" lines in the commit message.
* Be sure to add the `Approved by:` line when you are in the editor.
[source,shell]
....
% git checkout releng/13.0
% git cherry-pick -x $HASH --edit
....
If you forget to to add the `Approved by:` line, you can do a `git commit --amend` to edit the commit message before you push the change.
==== Multiple commit MFC ==== Multiple commit MFC
[source,shell] [source,shell]
@ -785,18 +803,15 @@ using 'git rebase -i' is better.
When committing source commits to stable and releng branches, we have When committing source commits to stable and releng branches, we have
the following goals: the following goals:
1. Clearly mark direct commits distinct from commits that land a * Clearly mark direct commits distinct from commits that land a change from another branch.
change from another branch * Avoid introducing known breakage into stable and releng branches.
2. Avoid introducing known breakage into stable and releng branches * Allow developers to determine which changes have or have not been landed from one branch to another.
3. Allow developers to determine which changes have or have not been
landed from one branch to another
With subversion, we used the following practices to achieve these goals: With subversion, we used the following practices to achieve these goals:
1. Using 'MFC' and 'MFS' tags to mark commits that merged changes from * Using 'MFC' and 'MFS' tags to mark commits that merged changes from another branch.
another branch * Squashing fixup commits into the main commit when merging a change.
2. Squashing fixup commits into the main commit when merging a change * Recording mergeinfo so that `svn mergeinfo --show-revs` worked.
3. Recording mergeinfo so that `svn mergeinfo --show-revs` worked
With Git, we will need to use different strategies to achieve the same With Git, we will need to use different strategies to achieve the same
goals. This document aims to define best practices when merging goals. This document aims to define best practices when merging
@ -812,31 +827,7 @@ replicated or "landed" to a stable branch, or a commit from a stable
branch that is replicated to a releng branch with some varation of branch that is replicated to a releng branch with some varation of
`git cherry-pick`. `git cherry-pick`.
==== Commit message standards ==== Finding Eligible Hashes to MFC
===== Marking MFCs
There are two main options for marking MFCs as distinct from direct
commits:
1. One option that matches our existing practice (the wisdom of which
I'm not commenting on) would mark MFCs like this in the commit
message: `MFC: 12def6789a3a,ac32ee4a5c2e`
where the first 12 digits of the hash is used to mark the commit message.
This "abbreviated hash" can be retrieved by: `git show --format=%p --no-patch $full_hash`
This preserves the information, but isn't 'git standard'. It also
requires committers to manually edit commit messages to include
this information when merging.
2. Use the `-x` flag with `git cherry-pick`. This adds a line to the
commit message that includes the hash of the original commit when
merging. Since it is added by Git directly, committers do not have
to manually edit the commit log when merging.
We feel that the second option is simpler going forward.
===== Finding Eligible Hashes to MFC
Git provides some built-in support for this via the `git cherry` and Git provides some built-in support for this via the `git cherry` and
`git log --cherry` commands. These commands compare the raw diffs of `git log --cherry` commands. These commands compare the raw diffs of
@ -867,6 +858,19 @@ There are a few options for resolving this:
commit, but collecting the `-x` annotations at the end of the commit, but collecting the `-x` annotations at the end of the
landed commit log. landed commit log.
==== Commit message standards
===== Marking MFCs
There are two main options for marking MFCs as distinct from direct
commits:
* Use the `-x` flag with `git cherry-pick`. This adds a line to the
commit message that includes the hash of the original commit when
merging. Since it is added by Git directly, committers do not have
to manually edit the commit log when merging.
When merging multiple commits, keep all the "cherry picked from" lines.
===== Trim Metadata? ===== Trim Metadata?
One area that was not clearly documented with subversion (or even CVS) One area that was not clearly documented with subversion (or even CVS)