Page MenuHomeFreeBSD
Files F110105770

D28815.diff
No OneTemporary
Actions

D28815.diff
View Options

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.

File Metadata

Mime Type
text/plain
Expires
Fri, Feb 14, 4:53 PM (20 h, 52 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
16645215
Default Alt Text
D28815.diff (7 KB)

Event Timeline