git: 0181ba1611 - main - MFC: update advice on MFC practices

[Warner Losh]

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=0181ba16117f05569d0ebd7989dd53bae1821598

commit 0181ba16117f05569d0ebd7989dd53bae1821598
Author:     Warner Losh <imp at FreeBSD.org>
AuthorDate: 2021-03-18 20:30:53 +0000
Commit:     Warner Losh <imp at FreeBSD.org>
CommitDate: 2021-03-18 20:30:53 +0000

    MFC: update advice on MFC practices
    
    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.
---
 .../en/articles/committers-guide/_index.adoc       | 72 ++++++++++++----------
 1 file changed, 38 insertions(+), 34 deletions(-)

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 264750a636..9bf60fefbf 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -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,
 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
 
 [source,shell]
@@ -785,18 +803,15 @@ using 'git rebase -i' is better.
 When committing source commits to stable and releng branches, we have
 the following goals:
 
-1. Clearly mark direct commits distinct from commits that land a
-   change from another branch
-2. Avoid introducing known breakage into stable and releng branches
-3. Allow developers to determine which changes have or have not been
-   landed from one branch to another
+* Clearly mark direct commits distinct from commits that land a change from another branch.
+* 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.
 
 With subversion, we used the following practices to achieve these goals:
 
-1. Using 'MFC' and 'MFS' tags to mark commits that merged changes from
-   another branch
-2. Squashing fixup commits into the main commit when merging a change
-3. Recording mergeinfo so that `svn mergeinfo --show-revs` worked
+* Using 'MFC' and 'MFS' tags to mark commits that merged changes from another branch.
+* Squashing fixup commits into the main commit when merging a change.
+* Recording mergeinfo so that `svn mergeinfo --show-revs` worked.
 
 With Git, we will need to use different strategies to achieve the same
 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
 `git cherry-pick`.
 
-==== Commit message standards
-===== 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
+==== Finding Eligible Hashes to MFC
 
 Git provides some built-in support for this via the `git cherry` and
 `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
    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?
 
 One area that was not clearly documented with subversion (or even CVS)