Lines Matching +full:commit +full:- +full:message
1 .. _docs-pw-style-commit-message:
4 Commit message style
6 Pigweed commit message bodies and summaries are limited to 72 characters wide to
8 commit is affecting. The commits should describe what is changed, and why. When
9 writing long commit messages, consider whether the content should go in the
12 .. code-block:: none
17 description of why the change is needed. Consider what parts of the commit
18 message are better suited for documentation or code.
20 - Added foo, to fix issue bar
21 - Improved speed of qux
22 - Refactored and extended qux's test suite
24 -----------------------------
26 -----------------------------
28 evident - for example, reducing memory usage, optimizing, or fixing a bug.
29 Otherwise, err on the side of over-explaining why, not under-explaining why.
31 When adding the "why" to a commit, also consider if that "why" content should go
34 .. admonition:: **Yes**: Reasoning in commit message
37 .. code-block:: none
49 .. code-block:: none
55 .. _docs-pw-style-commit-message-imperative:
57 ---------------
59 ---------------
61 in the commit message title. Do not use third-person singular present tense.
62 In general, the commit message title should start with a verb, and that verb
65 .. tab-set::
67 .. tab-item:: Yes
71 .. tab-item:: No
75 ---------------------------------------
76 Documentation instead of commit content
77 ---------------------------------------
78 Consider whether any of the commit message content should go in the
79 documentation or code comments and have the commit message reference it.
80 Documentation and code comments are durable and discoverable; commit messages
86 .. code-block:: none
94 .. admonition:: **No**: Important content only in commit message
97 .. code-block:: none
106 ---------------------------
108 ---------------------------
116 .. code-block:: none
118 pw_complicated_module: Pre-work for refactor
124 - Add arguments to MyImportantClass::MyFunction
125 - Update MyImportantClass to handle precondition Y
126 - Add stub functions to be used during the transition
131 .. code-block:: none
135 This change does A, B, and C. The commit message is a Big Wall Of Text
140 ------------
142 ------------
143 The subject line (first line of the commit) should take the form ``pw_<module>:
147 .. admonition:: **No**: Uses a non-standard ``[]`` to indicate module:
150 .. code-block:: none
157 .. code-block:: none
164 .. code-block:: none
172 #. **2-5 modules**: Use ``{}`` syntax shown below
173 #. **>5 modules changed** - Omit the module names entirely
174 #. **Changes mostly in one module** - If the commit mostly changes the
181 .. code-block:: none
191 .. code-block:: none
200 .. code-block:: none
206 Non-standard modules
215 .. code-block:: none
224 case-sensitive symbol.
229 .. code-block:: none
239 .. code-block:: none
243 This commit message demonstrates the subject when the subject has an
250 .. code-block:: none
254 ------
256 ------
257 We support a number of `git footers`_ in the commit message, such as ``Bug:
258 123`` in the message below:
260 .. code-block:: none
267 <https://git-scm.com/docs/git-interpret-trailers>`_. Note in particular that
268 multi-line footers are supported:
270 .. code-block::none
279 * ``Bug``: Associates this commit with a bug (issue in our `bug tracker`_). The
283 .. code-block:: none
293 .. code-block:: none
304 documentation, not in the commit message. Use the ``Test`` field to attest
307 .. code-block:: none
318 …ooters: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-…