Skip to content

Commit b7c08af

Browse files
committed
📚 Design: Add example format for a commit message
1 parent 89a57cc commit b7c08af

File tree

2 files changed

+21
-1
lines changed

2 files changed

+21
-1
lines changed

‎docs/design.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ Good development standards make for better code.
7676

7777
### Commit messages
7878

79-
> A well-cared for log is a beautiful and useful thing
79+
> A well-cared for (commit) log is a beautiful and useful thing
8080
8181
This quote comes from the following article, which should be considered a mandatory read for anyone maintaining a package:
8282

@@ -92,6 +92,25 @@ The summary, slightly adapted by personal preferences (indicated in boldface):
9292
* [Use the body to explain what and why vs. how](https://cbea.ms/git-commit/#why-not-how).
9393

9494
In addition, try to make [atomic commits](https://www.freshconsulting.com/insights/blog/atomic-commits/) when possible.
95+
We've also taken inspiration from the [MyST parser contribution guide](https://github.com/executablebooks/MyST-Parser?tab=contributing-ov-file#commit-messages).[^1]
96+
97+
[^1]: Shoutout to my boi [Chris Sewell](https://github.com/chrisjsewell). The man, the legend. The quintessential British b***ard.
98+
99+
Here is an example of the desired format for a commit message:
100+
101+
```
102+
<EMOJI> <SCOPE>: Summarize changes in 72 characters or less
103+
104+
More detailed explanatory text, if necessary. Explain the problem that this
105+
commit is solving. Focus on why you are making this change and why you chose
106+
your approach as opposed to what you are changing (the code explains that).
107+
Are there side effects or other unintuitive consequences of this change?
108+
Here's the place to explain the context of your commit to someone else reading
109+
your message in the future (most likely you).
110+
111+
PS: There is no need to mention you also added unit tests when adding a new
112+
feature. The code diff already makes this clear.
113+
```
95114

96115
#### Specifying the type of change
97116

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ theme:
44
markdown_extensions:
55
- admonition
66
- pymdownx.details
7+
- footnotes

0 commit comments

Comments
 (0)