Skip to content

Commit ab032e2

Browse files
committed
docs(contributing/commit-message-format): fills out "Summaries" section
1 parent b75bf65 commit ab032e2

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

docs/contributing/commit-message-format.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,35 @@ Must be one of the following:
4949

5050
### Summaries
5151

52+
Use the summary field to provide a succinct description of the change.
53+
54+
It should read as if prepended by "This commit...":
55+
56+
- "\[This commit \]**adds generation button**"
57+
- "\[This commit \]**describes how to contribute**"
58+
- "\[This commit \]**extracts `foo` from `bar`**"
59+
60+
General rules:
61+
62+
- start with a verb in the simple present tense: "changes..."
63+
- not "change..."[^1]
64+
- not "changed..."[^2]
65+
- not "changing..."[^3]
66+
- don't capitalize the first letter to better align with the type (and scope)
67+
- no punctuation at the end (i.e. ".", "!") since space is limited
68+
69+
[^1]: because
70+
71+
the first-person present tense ("\[I \]**change...**") is not "author-agnostic". The "who" is part of the commit metadata, so it doesn't need to be called out in the summary;
72+
73+
the imperative present tense ("\[It's been requested that we \]**change...**") is reserved for issues and requests. i.e. when we're told what we should do next;
74+
75+
the simple future tense ("\[This commit will \]**change...**") is not "release agnostic", implies need to reword as past tense after release
76+
77+
[^2]: because past tense "\[This commit has | I \]**changed...**" is not release agnostic, implies it would need to be in future tense until released
78+
79+
[^3]: because the present progressive tense "\[This commit is \]**changing...**" suggests "work-in-progress", which usually is only relevant during PRs
80+
5281
## Bodies
5382

5483
## Footers

0 commit comments

Comments
 (0)