Changeset View
Changeset View
Standalone View
Standalone View
documentation/content/en/articles/committers-guide/_index.adoc
Show First 20 Lines • Show All 1,427 Lines • ▼ Show 20 Lines | |||||
In some cases, no subject-matter expert may be available. In those cases, a review by an experienced developer is sufficient when coupled with appropriate testing. | In some cases, no subject-matter expert may be available. In those cases, a review by an experienced developer is sufficient when coupled with appropriate testing. | ||||
[[commit-log-message]] | [[commit-log-message]] | ||||
== Commit Log Messages | == Commit Log Messages | ||||
This section contains some suggestions and traditions for how commit logs are formatted. | 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. | 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. | This information consists of one or more lines containing the key word or phrase, a colon, tabs for formatting, and then the additional information. | ||||
The key words or phrases are: | The key words or phrases are: | ||||
[.informaltable] | [.informaltable] | ||||
[cols="20%,80%", frame="none"] | [cols="20%,80%", frame="none"] | ||||
▲ Show 20 Lines • Show All 1,135 Lines • Show Last 20 Lines |