docs/commit_messages.md

# 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
 1. **>5 modules changed** - Omit the module names entirely
 1. **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](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-footers.html)
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.