<aside> 🌏 This page is public.
</aside>
We currently don't have an agreed upon commit message convention. This makes it harder for new contributors and employees to come in. This RFC outlines proposals for a commit message convention.
We currently practise three different commit message conventions. I propose we agree on a single one of them.
Simple descriptive sentences that explain what's happening.
👍 They are easy and don't require much checking
👎 They often miss the context where things are happening though.
[component] Change description
which is like the first one, but describes the context of the change
👍 Does not impose much syntax
👍 Clarifies the context of the change which befits our monorepo
👎 Provides no means for communicating breaking changes
Conventional commits seem to be used intermittently by some folks
👍 Very flexible in what it can communicate
👎 Complex syntax that necessitates commit message checkers to be enforced
👎 Will take some time to learn due to its complexity
Other than convention we should agree on these rules of style
Capitalize the subject line: begin all subject lines with a capital letter.
Good: [warp drive] Implement refractor coil
Bad: [warp drive] implement refractor coil
Do not end the subject line with a period because the punctuation adds no value and space is precious when all you've got is 72 characters
Good: [warp drive] Implement refractor coil
Bad: [warp drive] implement refractor coil.
Use the imperative mood in the subject line which means "like a command or instruction". Particularly, don't use past-tense.
Good:
Refactor ws-manager API
Update getting started documentation
Fix the nil-deref bug
Bad:
Refactored the ws-manager API
Updated getting started documentation
Fixed the nil-deref bug
Note, that the default message for merge requests is in imperative mood also, e.g. Merge branch 'foobar'
.
Limit the subject line to 50 characters which is more of a soft limit. The hard limit (imposed by Git) is at 72 characters. Short messages force us to focus on what matters.
What are relevant documents, links, resources? Feel free to embed a Google Docs if you find it easier to review/collaborate there.