docs: Add docs/commit_messages.md
Initially transcribed loosely with changes from pigweed
Change-Id: I0ae35c1780c59354649c5dfebc492403f1b9bbac
Reviewed-on: https://bluetooth-review.git.corp.google.com/c/bluetooth/+/1601
Reviewed-by: Ani Ramakrishnan <aniramakri@google.com>
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f4fd39f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+# Vim swap files.
+*.swp
diff --git a/docs/commmit_messages.md b/docs/commmit_messages.md
new file mode 100644
index 0000000..81f4127
--- /dev/null
+++ b/docs/commmit_messages.md
@@ -0,0 +1,117 @@
+
+
+# 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.
+
