From owner-dev-commits-doc-all@freebsd.org Wed Mar 17 17:24:14 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id E04C1571AB5 for ; Wed, 17 Mar 2021 17:24:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4F0xpk62JNz4lZD; Wed, 17 Mar 2021 17:24:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id C226312FA4; Wed, 17 Mar 2021 17:24:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 12HHOE3E049890; Wed, 17 Mar 2021 17:24:14 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 12HHOE6F049889; Wed, 17 Mar 2021 17:24:14 GMT (envelope-from git) Date: Wed, 17 Mar 2021 17:24:14 GMT Message-Id: <202103171724.12HHOE6F049889@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Warner Losh Subject: git: ad41defcd5 - main - Update vendor import with suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: ad41defcd5766604e33e6f3b847c4d0e1c307839 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Mar 2021 17:24:14 -0000 The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/doc/commit/?id=ad41defcd5766604e33e6f3b847c4d0e1c307839 commit ad41defcd5766604e33e6f3b847c4d0e1c307839 Author: Warner Losh AuthorDate: 2021-03-17 17:15:57 +0000 Commit: Warner Losh 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 <> 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 <>. 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