diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -1433,6 +1433,154 @@ 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.