Skip to content

Commit 89a57cc

Browse files
mbercxmbercx
committed
📚 Add development standards to Design notes
For now we'll add this to the template package documentation, to make it easy to share with collaborators. It might also be desirable to place this in the template docs, but it could also make those too verbose. Perhaps adding a link is the better option once we converge on the developments standards here.
1 parent 4b20f3c commit 89a57cc

File tree

1 file changed

+116
-0
lines changed

1 file changed

+116
-0
lines changed

‎docs/design.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,119 @@ The configuration is stored in `.pre-commit-config.yaml`, and only uses `hatch f
6767
* `hatch fmt -l`
6868

6969
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+
### Commit messages
78+
79+
> A well-cared for log is a beautiful and useful thing
80+
81+
This quote comes from the following article, which should be considered a mandatory read for anyone maintaining a package:
82+
83+
[https://cbea.ms/git-commit/](https://cbea.ms/git-commit/)
84+
85+
The summary, slightly adapted by personal preferences (indicated in boldface):
86+
87+
* [Separate subject/title from body with a blank line](https://cbea.ms/git-commit/#separate).
88+
* [Limit the subject line to 50 characters](https://cbea.ms/git-commit/#limit-50) **if possible, 72 is a hard limit**.
89+
* [Capitalize the subject line](https://cbea.ms/git-commit/#capitalize) and [do not end it with a period](https://cbea.ms/git-commit/#end).
90+
* [Use the imperative mood in the subject line](https://cbea.ms/git-commit/#imperative).
91+
* [Wrap the body at](https://cbea.ms/git-commit/#wrap-72) **88 characters**.
92+
* [Use the body to explain what and why vs. how](https://cbea.ms/git-commit/#why-not-how).
93+
94+
In addition, try to make [atomic commits](https://www.freshconsulting.com/insights/blog/atomic-commits/) when possible.
95+
96+
#### Specifying the type of change
97+
98+
!!!note
99+
100+
The stipulations below are based on experience, but are still evolving.
101+
This text is mainly here to provide a starting point for discussion with collaborators.
102+
TODO: Look into [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) and see if we want to use/adapt their specification.
103+
104+
Specifying the type of change in a commit can be useful for several reasons:
105+
106+
- Understanding the changes of a commit.
107+
- Where to (automatically) put the commit in the changelog, if at all.
108+
- What to include in a support branch for a previous major release.
109+
- Encouraging atomic commits.
110+
- What the priority should be when reviewing open PRs.
111+
112+
We use **exactly one leading** emoji per commit to indicate the type of change.
113+
Some advantages:
114+
115+
- Only a single character needed!
116+
Save precious space in the subject line.
117+
- A clear visual indicator of the type of change.
118+
- Clearly separates type from scope/content.
119+
- Language-agnostic.
120+
- They look great. At least on macOS.
121+
122+
!!! important
123+
124+
Although we are in favor of using emojis in the subject line, we do **not** allow emojis in the body.
125+
This makes it easier to `grep` for commit types.
126+
127+
| Emoji | Meaning | Similar to [Angular type](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) | In changelog summary? |
128+
| ----- | ---------------------------------------------------------------- | ----------------------------------------- | ------------------------- |
129+
| 💥 | introduce a backward-incompatible (breaking) change / remove deprecated code | `\<type>!` (use `!` + `BREAKING CHANGE:`) | **Yes** |
130+
| ✨ | introduce new features | `feat` | **Yes** |
131+
| 👌 | improve an existing code/feature (no breaking) | `perf`/`feat` | **Yes** |
132+
| 🐛 | fix a code bug | `fix` | **Yes** |
133+
| ❌ | mark code as deprecated (note removal version/replacement) | `refactor` | **Yes** |
134+
| 📦 | update or change a dependency | `build` | **Yes** |
135+
| 📚 | add or adapt documentation | `docs` | No |
136+
| 🔄 | refactor existing code with no behavior change | `refactor` | No |
137+
| 🧪 | add or adapt tests | `test` | No |
138+
| 🚀 | bump the package version for release | `chore` | No |
139+
| 🧹 | clean up comments / small formatting | `style` | No |
140+
| ⏪ | revert a previous commit | `revert` | No |
141+
| 🔧 | devops-related changes (pre-commit, CI/CD, etc.) | `ci` | No |
142+
| 🐭 | minor changes (typos etc.; exclude from changelog) | `chore` | No |
143+
| ❓ | anything not covered above (last resort) | `chore` | No |
144+
145+
!!!note
146+
147+
We are aware of other standards like [GitMoji](https://gitmoji.dev/), but limit the number in order to avoid choice overload.
148+
Too many options make it difficult for contributors to know all of them, makes changelogs too fragmented and leads to decision paralysis.
149+
Moreover, we avoid emojis that typically have width issues in some terminals.
150+
151+
!!!note
152+
153+
Not everyone likes emojis. In the dropdown below you can find some common concerns.
154+
155+
??? "Common concerns"
156+
157+
> Tooling can’t parse emojis.
158+
159+
We haven't needed to use much tooling so far, and built our own for e.g. the changelog.
160+
161+
> Search/grep is harder.
162+
163+
You can grep for emojis too!
164+
Moreover, the body of the commit should not contain any emojis, so it's quite easy to look for commit types:
165+
166+
git log | grep '[💥✨👌🐛❌📦]'
167+
168+
> Accessibility / screen readers read ‘sparkles’
169+
170+
This is a fair point.
171+
In case we start working with collaborators that rely on such tools we will adapt.
172+
173+
> Rendering/width issues in some terminals.
174+
175+
We selected emojis with default emoji presentation (no variation selector), which render correctly in modern terminals.
176+
177+
> Ambiguity / overchoice
178+
179+
This just depends on conventions.
180+
You can have _more_ ASCII keywords to choose from. If we keep a small, fixed set, like the one above, this is not an issue.
181+
182+
> Not serious/professional.
183+
184+
The icon is metadata, not decoration.
185+
It improves triage and doesn’t replace clear subjects/bodies.

0 commit comments

Comments
 (0)