Commit message style

Commit message bodies and summaries are limited to 72 characters wide to improve readability, and should be prefixed with the name of the module that the commit is affecting. The commits should describe what is changed, and why. When writing long commit messages, consider whether the content should go in the documentation or code comments instead. For example:

rust/bt-gatt: Short capitalized description
Details about the change here. Include a summary of what changed, and a clear
description of why the change is needed. Consider what parts of the commit
message are better suited for documentation or code.
 - Add foo to fix issue bar
 - Improve speed of qux
 - Refactor and extended qux's test suite

Include both “what” and “why”

It is important to include a “why” component in most commits. Sometimes, why is evident - for example, reducing memory usage, optimizing, or fixing a bug. Otherwise, err on the side of over-explaining why, not under-explaining why. When adding the “why” to a commit, also consider if that “why” content should go into the documentation or code comments.

rust/bt-common: Add debug formatting
 Print the services in a human-readable format.
 This makes debugging and handling the services much easier, and will allow
 for quick glancing.
 Though this costs performance, several bugs that went unnoticed would have
 been caught by turning this on earlier. Take the small hit by default to
 better catch issues going forward; see extended docs for details.

Present imperative

Use present imperative style instead of passive descriptive.

rust/bt-vcs: Add volume changed event

instead of

rust/bt-vcs: Adds volume changed event

Documentation instead of commit content

Consider whether any of the commit message content should go in the documentation or code comments and have the commit message reference it. Documentation and code comments are durable and discoverable; commit messages are rarely read after the change lands.

Lists instead of paragraphs

Use bulleted lists when multiple changes are in a single CL. Ideally, try to create smaller CLs so this isn't needed, but larger CLs are a practical reality.

rust/bt-pacs: Add more capablities

Add the suite of capabilities added in the new spec.
 - Foo capability
 - Bar format

Subject line

The subject line (first line of the commit) should take the form <module>: Short description. The module should not be capitalized, but the description should (unless the first word is an identifier). It should not include a trailing period.

Multiple modules

Sometimes it is necessary to change code across multiple modules.

  1. 2-5 modules: Use {} syntax shown below
  2. >5 modules changed - Omit the module names entirely
  3. Changes mostly in one module - If the commit mostly changes the code in a single module with some small changes elsewhere, only list the module receiving most of the content

For example, for 2 modules:

bt-{gatt, vcs}: Update names

Footer

We encourage a number of git footers in the commit message, such as Bug: 123 in the message below:

bt-gatt: Add foo and bar functions

Bug: 123

The footer syntax is described in the [git documentation] (https://git-scm.com/docs/git-interpret-trailers). Note in particular that multi-line footers are supported.

You are encouraged to use the following footers when appropriate:

  • Bug: Associates this commit with a bug (issue in our bug tracker).
  • Fixed or Fixes: Like Bug, but may automatically close the bug when submitted.
  • Test: The author can use this field to tell the reviewer how the change was tested. Typically, this will be some combination of writing new automated tests, running automated tests, and manual testing. Note: descriptions of manual testing procedures belong in module documentation, not in the commit message. Use the Test field to attest that tests were carried out, not to describe the procedures in detail.