From owner-dev-commits-doc-all@freebsd.org Sat Feb 20 18:44:49 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 16BED550D12 for ; Sat, 20 Feb 2021 18:44:49 +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 4DjcnF092pz4WjR; Sat, 20 Feb 2021 18:44:49 +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 E86FA23FB7; Sat, 20 Feb 2021 18:44:48 +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 11KIimmH099490; Sat, 20 Feb 2021 18:44:48 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 11KIim0L099489; Sat, 20 Feb 2021 18:44:48 GMT (envelope-from git) Date: Sat, 20 Feb 2021 18:44:48 GMT Message-Id: <202102201844.11KIim0L099489@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Ed Maste Subject: git: 11f8235774 - main - Add commit message information to committer's guide MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: emaste X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 11f82357745ef8e529fa433e763d55776f666ceb 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: Sat, 20 Feb 2021 18:44:49 -0000 The branch main has been updated by emaste (src committer): URL: https://cgit.FreeBSD.org/doc/commit/?id=11f82357745ef8e529fa433e763d55776f666ceb commit 11f82357745ef8e529fa433e763d55776f666ceb Author: Ed Maste AuthorDate: 2021-02-20 18:41:57 +0000 Commit: Ed Maste CommitDate: 2021-02-20 18:44:21 +0000 Add commit message information to committer's guide Provide some guidance on good git commit messages. Based on an article I wrote, with further editing and feedback by imp in the temporary git docs repo. Reviewed by: debdrup, imp Approved by: debdrup Differential Revision: https://reviews.freebsd.org/D28815 --- .../en/articles/committers-guide/_index.adoc | 148 +++++++++++++++++++++ 1 file changed, 148 insertions(+) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index b4ee7b75a2..bfa1bccc68 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -1433,6 +1433,154 @@ In some cases, no subject-matter expert may be available. In those cases, a revi This section contains some suggestions and traditions for how commit logs are formatted. +=== Why are commit messages important? + +When you commit a change in Git, Subversion, or another version control system +(VCS), you're prompted to write some text describing the commit -- a commit +message. How important is this commit message? Should you spend some significant +effort writing it? Does it really matter if you write simply fixed a bug? + +Most projects have more than one developer and last for some length of time. +Commit messages are a very important method of communicating with other +developers, in the present and for the future. + +FreeBSD has hundreds of active developers and hundreds of thousands of commits +spanning decades of history. Over that time the developer community has learned +how valuable good commit messages are; sometimes these are hard-learned lessons. + +Commit messages serve at least three purposes: + +* Communicating with other developers ++ +FreeBSD commits generate email to various mailing lists. These include the +commit message along with a copy of the patch itself. Commit messages are also +viewed through commands like git log. These serve to make other developers +aware of changes that are ongoing; that other developer may want to test the +change, may have an interest in the topic and will want to review in more +detail, or may have their own projects underway that would benefit from +interaction. + +* Making Changes Discoverable ++ +In a large project with a long history it may be difficult to find changes of +interest when investigating an issue or change in behaviour. Verbose, detailed +commit messages allow searches for changes that might be relevant. For example, +`git log --since 1year --grep 'USB timeout'`. + +* Providing historical documentation ++ +Commit messages serve to document changes for future developers, perhaps years +or decades later. This future developer may even be you, the original author. +A change that seems obvious today may be decidedly not so much later on. + +The `git blame` command annotates each line of a source file with the change +(hash and subject line) that brought it in. + +Having established the importance, here are elements of a good FreeBSD commit +message: + +=== Start with a subject line + +Commit messages should start with a single-line subject that briefly summarizes +the change. The subject should, by itself, allow the reader to quickly +determine if the change is of interest or not. + +=== Keep subject lines short + +The subject line should be as short as possible while still retaining the +required information. This is to make browsing git log more efficient, and so +that git log --oneline can display the short hash and subject on a single +80-column line. A good rule of thumb is to stay below 63 characters, and aim +for about 50 or fewer if possible. + +=== Prefix the subject line with a component, if applicable + +If the change relates to a specific component the subject line may be prefixed +with that component name and a colon (:). + +✓ `foo: Add -k option to keep temporary data` + +Include the prefix in the 63-character limit suggested above, so that +`git log --oneline` avoids wrapping. + +=== Capitalize the first letter of the subject + +Capitalize the first letter of the subject itself. The prefix, if any, is not +capitalized unless necessary (e.g., `USB:` is capitalized). + +=== Do not end the subject line with punctuation + +Do not end with a period or other punctuation. In this regard the subject line +is like a newspaper headline. + +=== Separate the subject and body with a blank line + +Separate the body from the subject with a blank line. + +Some trivial commits do not require a body, and will have only a subject. + +✓ `ls: fix typo in usage text` + +=== Limit messages to 72 columns + +`git log` and `git format-patch` indent the commit message by four spaces. +Wrapping at 72 columns provides a matching margin on the right edge. Limiting +messages to 72 characters also keeps the commit message in formatted patches +below RFC 2822's suggested email line length limit of 78 characters. This limit +works well with a variety of tools that may render commit messages; line +wrapping might be inconsistent with longer line length. + +=== Use the present tense, imperative mood + +This facilitates short subject lines and provides consistency, including with +automatically generated commit messages (e.g., as generated by git revert). +This is important when reading a list of commit subjects. Think of the subject +as finishing the sentence "when applied, this change will ...". + +✓ `foo: Implement the -k (keep) option` + +✗ `foo: Implemented the -k option` + +✗ `This change implements the -k option in foo ✗ -k option added` + +=== Focus on what and why, not how + +Explain what the change accomplishes and why it is being done, rather than how. + +Do not assume that the reader is familiar with the issue. Explain the +background and motivation for the change. Include benchmark data if you have it. + +If there are limitations or incomplete aspects of the change, describe them in +the commit message. + +=== Consider whether parts of the commit message could be code comments instead + +Sometimes while writing a commit message you may find yourself writing a +sentence or two explaining some tricky or confusing aspect of the change. When +this happens consider whether it would be valuable to have that explanation as +a comment in the code itself. + +=== Write commit messages for your future self + +While writing the commit message for a change you have all of the context in +mind - what prompted the change, alternate approaches that were considered and +rejected, limitations of the change, and so on. Imagine yourself revisiting the +change a year or two in the future, and write the commit message in a way that +would provide that necessary context. + +=== Commit messages should stand alone + +You may include references to mailing list postings, benchmark result web +sites, or code review links. However, the commit message should contain all of +the relevant information in case these references are no longer available in +the future. + +Similarly, a commit may refer to a previous commit, for example in the case of +a bug fix or revert. In addition to the commit identifier (revision or hash), +include the subject line from the referenced commit (or another suitable brief +reference). With each VCS migration (from CVS to Subversion to Git) revision +identifiers from previous systems may become difficult to follow. + +=== Include appropriate metadata in a footer + As well as including an informative message with each commit, some additional information may be needed. This information consists of one or more lines containing the key word or phrase, a colon, tabs for formatting, and then the additional information.