You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
📚 Standards: move "development standards" to separate page
In hindsight, "development standards" are not really related to the design documents of
the Python `copier` template package. It might even be more sensible to add them to the
documentation of the template itself. But we leave that for when it is more complete and
polished.
Besides not being appropriate for the design section, giving the development standard
its own pages means we have to use one less header depth, which leads to more visible
header fonts and a less nested table of contents tree.
Since we now have 4 pages, it's time to add a `nav` section to the MkDocs configuration.
Copy file name to clipboardExpand all lines: docs/design.md
-147Lines changed: 0 additions & 147 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,150 +67,3 @@ The configuration is stored in `.pre-commit-config.yaml`, and only uses `hatch f
67
67
*`hatch fmt -l`
68
68
69
69
The steps are separated in first _formatting_ the code, then _linting_ it to check for issues.
70
-
71
-
## Development standards
72
-
73
-
Good development standards make for better code.
74
-
75
-
**Versioning**: We try to adhere to [SemVer](https://semver.org/).
76
-
77
-
!!!note
78
-
79
-
The stipulations below are based on experience, but are still evolving.
80
-
This text is mainly here to provide a starting point for discussion with collaborators.
81
-
<!-- TODO: Look into [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) and see if we want to use/adapt their specification. -->
82
-
83
-
### Commit messages
84
-
85
-
> A well-cared for (commit) log is a beautiful and useful thing
86
-
87
-
This quote comes from the following article, which should be considered a mandatory read for anyone maintaining a package:
The summary, slightly adapted by personal preferences (indicated in boldface):
92
-
93
-
*[Separate subject/title from body with a blank line](https://cbea.ms/git-commit/#separate).
94
-
*[Limit the subject line to 50 characters](https://cbea.ms/git-commit/#limit-50)**if possible, 72 is a hard limit**.
95
-
*[Capitalize the subject line](https://cbea.ms/git-commit/#capitalize) and [do not end it with a period](https://cbea.ms/git-commit/#end).
96
-
*[Use the imperative mood in the subject line](https://cbea.ms/git-commit/#imperative).
97
-
*[Wrap the body at](https://cbea.ms/git-commit/#wrap-72)**88 characters**.
98
-
*[Use the body to explain what and why vs. how](https://cbea.ms/git-commit/#why-not-how).
99
-
100
-
In addition, try to make [atomic commits](https://www.freshconsulting.com/insights/blog/atomic-commits/) when possible.
101
-
We've also taken inspiration from the [MyST parser contribution guide](https://github.com/executablebooks/MyST-Parser?tab=contributing-ov-file#commit-messages).[^1]
102
-
103
-
[^1]: Shoutout to my boi [Chris Sewell](https://github.com/chrisjsewell). The man, the legend. The quintessential British b***ard.
104
-
105
-
Here is an example of the desired format for a commit message:
106
-
107
-
```
108
-
<TYPE-EMOJI> <SCOPE>: Summarize changes in 72 characters or less
109
-
110
-
More detailed explanatory text, if necessary. Explain the problem that this
111
-
commit is solving. Focus on what you are changing, why you are making this
112
-
change and why you chose your approach, as opposed to how the change was made
113
-
(the code and comments should explain that). Are there side effects or other
114
-
unintuitive consequences of this change? Here's the place to explain the
115
-
context of your commit to someone else reading your message in the future
116
-
(most likely you).
117
-
118
-
PS: There is no need to mention you also added unit tests when adding a new
119
-
feature. The code diff already makes this clear.
120
-
```
121
-
122
-
Besides being an invaluable resources for future maintainers, writing a commit message forces you to explain your change.
123
-
It forces you to stop and think again.
124
-
Is this really the best approach to solving the issue?
125
-
If it's hard to explain the change, maybe it's a bad idea?
126
-
127
-
#### Specifying the type of change
128
-
129
-
Specifying the type of change in a commit can be useful for several reasons:
130
-
131
-
- Understanding the changes of a commit.
132
-
- Where to (automatically) put the commit in the changelog, if at all.
133
-
- What to include in a support branch for a previous major release.
134
-
- Encouraging atomic commits.
135
-
- What the priority should be when reviewing open PRs.
136
-
137
-
We use **exactly one leading** emoji per commit to indicate the type of change.
138
-
Some advantages:
139
-
140
-
- Only a single character needed!
141
-
Save precious space in the subject line.
142
-
- A clear visual indicator of the type of change.
143
-
- Clearly separates type from scope/content.
144
-
- Language-agnostic.
145
-
- They look great. At least on macOS.
146
-
147
-
!!! important
148
-
149
-
Although we are in favor of using leading emojis to indicate the type, we do **not** allow emojis further down the subject line.
150
-
This makes it easier to `grep` for commit types.
151
-
152
-
The list in the table below is in order of priority, e.g. a backwards-incompatible change might improve an existing feature by breaking its API, but should _not_ be typed as an improvement (👌).
153
-
Similarly, if a dependency is changed, it's convenient to quickly spot this, e.g. when updating a conda feedstock.
154
-
155
-
| Emoji | Meaning | Similar to [Angular type](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)| In changelog summary? |
**Versioning**: We try to adhere to [SemVer](https://semver.org/).
7
+
8
+
!!!note
9
+
10
+
The stipulations below are based on experience, but are still evolving.
11
+
This text is mainly here to provide a starting point for discussion with collaborators.
12
+
<!-- TODO: Look into [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) and see if we want to use/adapt their specification. -->
13
+
14
+
## Commit messages
15
+
16
+
> A well-cared for (commit) log is a beautiful and useful thing
17
+
18
+
This quote comes from the following article, which should be considered a mandatory read for anyone maintaining a package:
The summary, slightly adapted by personal preferences (indicated in boldface):
23
+
24
+
*[Separate subject/title from body with a blank line](https://cbea.ms/git-commit/#separate).
25
+
*[Limit the subject line to 50 characters](https://cbea.ms/git-commit/#limit-50)**if possible, 72 is a hard limit**.
26
+
*[Capitalize the subject line](https://cbea.ms/git-commit/#capitalize) and [do not end it with a period](https://cbea.ms/git-commit/#end).
27
+
*[Use the imperative mood in the subject line](https://cbea.ms/git-commit/#imperative).
28
+
*[Wrap the body at](https://cbea.ms/git-commit/#wrap-72)**88 characters**.
29
+
*[Use the body to explain what and why vs. how](https://cbea.ms/git-commit/#why-not-how).
30
+
31
+
In addition, try to make [atomic commits](https://www.freshconsulting.com/insights/blog/atomic-commits/) when possible.
32
+
We've also taken inspiration from the [MyST parser contribution guide](https://github.com/executablebooks/MyST-Parser?tab=contributing-ov-file#commit-messages).[^1]
33
+
34
+
[^1]: Shoutout to my boi [Chris Sewell](https://github.com/chrisjsewell). The man, the legend. The quintessential British b***ard.
35
+
36
+
Here is an example of the desired format for a commit message:
37
+
38
+
```
39
+
<TYPE-EMOJI> <SCOPE>: Summarize changes in 72 characters or less
40
+
41
+
More detailed explanatory text, if necessary. Explain the problem that this
42
+
commit is solving. Focus on what you are changing, why you are making this
43
+
change and why you chose your approach, as opposed to how the change was made
44
+
(the code and comments should explain that). Are there side effects or other
45
+
unintuitive consequences of this change? Here's the place to explain the
46
+
context of your commit to someone else reading your message in the future
47
+
(most likely you).
48
+
49
+
PS: There is no need to mention you also added unit tests when adding a new
50
+
feature. The code diff already makes this clear.
51
+
```
52
+
53
+
Besides being an invaluable resources for future maintainers, writing a commit message forces you to explain your change.
54
+
It forces you to stop and think again.
55
+
Is this really the best approach to solving the issue?
56
+
If it's hard to explain the change, maybe it's a bad idea?
57
+
58
+
### Specifying the type of change
59
+
60
+
Specifying the type of change in a commit can be useful for several reasons:
61
+
62
+
- Understanding the changes of a commit.
63
+
- Where to (automatically) put the commit in the changelog, if at all.
64
+
- What to include in a support branch for a previous major release.
65
+
- Encouraging atomic commits.
66
+
- What the priority should be when reviewing open PRs.
67
+
68
+
We use **exactly one leading** emoji per commit to indicate the type of change.
69
+
Some advantages:
70
+
71
+
- Only a single character needed!
72
+
Save precious space in the subject line.
73
+
- A clear visual indicator of the type of change.
74
+
- Clearly separates type from scope/content.
75
+
- Language-agnostic.
76
+
- They look great. At least on macOS.
77
+
78
+
!!! important
79
+
80
+
Although we are in favor of using leading emojis to indicate the type, we do **not** allow emojis further down the subject line.
81
+
This makes it easier to `grep` for commit types.
82
+
83
+
The list in the table below is in order of priority, e.g. a backwards-incompatible change might improve an existing feature by breaking its API, but should _not_ be typed as an improvement (👌).
84
+
Similarly, if a dependency is changed, it's convenient to quickly spot this, e.g. when updating a conda feedstock.
85
+
86
+
| Emoji | Meaning | Similar to [Angular type](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)| In changelog summary? |
0 commit comments