| # 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. | |