git: ad41defcd5 - main - Update vendor import with suggestions

[Warner Losh]

The branch main has been updated by imp:

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

commit ad41defcd5766604e33e6f3b847c4d0e1c307839
Author:     Warner Losh <imp at FreeBSD.org>
AuthorDate: 2021-03-17 17:15:57 +0000
Commit:     Warner Losh <imp at FreeBSD.org>
CommitDate: 2021-03-17 17:23:46 +0000

    Update vendor import with suggestions
    
    Add git commit --amend with a comment about doing a final check of the commit
    message before the push. Update with some more specific guidance on a good
    commit message. Add link to commit message section. Minor tweaks I noticed
    while doing this as well for having one setence one line.
    
    Submitted by cy@
---
 .../en/articles/committers-guide/_index.adoc       | 33 +++++++++++-----------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index d4a39d8d06..b75ddf2274 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -719,7 +719,7 @@ use `git pull --rebase` and try to push again.
 % for h in $HASH_LIST; do git cherry-pick -x $h; done
 % git rebase -i stable/X
 # mark each of the commits after the first as 'squash'
-# edit the commit message to be sane
+# edit the commit message to be sane, if necessary
 % git push freebsd HEAD:stable/X
 ....
 
@@ -1100,10 +1100,8 @@ The cherry-pick can now be completed:
 % git cherry-pick --continue
 ....
 
-Since there was a merge conflict, Git invokes the editor to
-adjust the commit message.  Trim the metadata fields from the
-commit log from the original commit to head and save the
-updated log message.
+Since there was a merge conflict, Git invokes the editor to adjust the commit message.
+Trim the metadata fields from the commit log from the original commit to head and save the updated log message.
 
 The contents of the MFC commit can be examined via `git show`:
 
@@ -1228,11 +1226,10 @@ Note: I run the `git diff` and `git status` commands to make sure nothing weird
 was present. Also I used `-m` to illustrate, but you should compose a proper
 message in an editor (using a commit message template).
 
-It is also important to create an annotated tag, otherwise the push
-will be rejected. Only annotated tags are allowed to be pushed. The
-annotated tag gives you a chance to enter a commit message. Enter
-the version you are importing, along with any salient new features
-or fixes in that version.
+It is also important to create an annotated tag, otherwise the push will be rejected.
+Only annotated tags are allowed to be pushed.
+The annotated tag gives you a chance to enter a commit message.
+Enter the version you are importing, along with any salient new features or fixes in that version.
 
 ==== Updating the FreeBSD Copy
 At this point you can push the import to vendor into our repo.
@@ -1338,9 +1335,9 @@ At this point, you should have a pristine copy of glorbnitz ready to commit.
 ....
 % git commit -m"Import GlorbNitz frobnosticator revision 3.1415"
 ....
-As above, I used `-m` for simplicity, but you should likely create a
-commit message that explains what a Glorb is and why you'd use a Nitz
-to get it. Not everybody will know.
+As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it.
+Not everybody will know.
+But for your actual commmit, you should follow the <<commit-log-message,commit log message>> section instead of emulate the brief style here.
 
 ==== Now import it into our repository
 Now you need to import the branch into our repository.
@@ -1372,6 +1369,7 @@ By 'good' we mean:
 . None of the wrong files are present
 . The vendor branch points at something sensible
 . The tag looks good, and is annotated.
+. The commit message for the tag has a quick summary of what's new since the last tag
 
 ==== Time to finally merge it into the base tree
 [source,shell]
@@ -1379,17 +1377,20 @@ By 'good' we mean:
 % cd ../src
 % git subtree add -P contrib/glorbnitz vendor/glorbnitz
 # Make sure the commit is good with "git show"
+% git commit --amend   # one last sanity check on commit message
 % git push freebsd
 ....
 Here 'good' means:
 
 . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.
-. No other changes are in the tree
-. The commit messages look good.
+. No other changes are in the tree.
+. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD main line and any caveats.
+. UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.
 
 [NOTE]
 ====
-This hasn't connected `glorbnitz` to the build yet. How so do that is specific to the software being imported.
+This hasn't connected `glorbnitz` to the build yet.
+How so do that is specific to the software being imported and is beyond the scope of this tutorial.
 ====
 
 === FreeBSD Src Committer Transition Guide