69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
|
# Use Conventional Commits
|
||
|
|
|
||
|
|
## Context and Problem Statement
|
||
|
|
|
||
|
|
* How to encourage PRs that focus on one issue?
|
||
|
|
* How to reduce the burden on the person responsible for compiling the release notes?
|
||
|
|
|
||
|
|
## Considered Options
|
||
|
|
|
||
|
|
* Adopt [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
||
|
|
* Adopt another standard
|
||
|
|
* Adopt a project-specific approach
|
||
|
|
* Do nothing
|
||
|
|
|
||
|
|
## Decision Outcome
|
||
|
|
|
||
|
|
Chosen option: "Adopt Conventional Commits", because comes out best (see below).
|
||
|
|
|
||
|
|
### Consequences
|
||
|
|
|
||
|
|
* Good, because PRs are more focused
|
||
|
|
* Good, because initial release notes are easier to produce
|
||
|
|
* Bad, because contributors have to learn about Conventional Commits during their first PR
|
||
|
|
|
||
|
|
## Pros and Cons of the Options
|
||
|
|
|
||
|
|
### Adopt Conventional Commits
|
||
|
|
|
||
|
|
To quote from https://www.conventionalcommits.org/en/v1.0.0/:
|
||
|
|
|
||
|
|
> The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
|
||
|
|
>
|
||
|
|
> The commit message should be structured as follows:
|
||
|
|
>
|
||
|
|
> ```
|
||
|
|
> <type>[optional scope]: <description>
|
||
|
|
> [optional body]
|
||
|
|
>
|
||
|
|
> [optional footer(s)]
|
||
|
|
> ```
|
||
|
|
|
||
|
|
* Good, because straightforward to understand and describe
|
||
|
|
* Good, because easy to write tooling for
|
||
|
|
* Good, because tooling already exists
|
||
|
|
* To automatically validate PR titles during PR review
|
||
|
|
* To create initial changelogs or release notes
|
||
|
|
* Bad, because contributors unaware with Conventional Commits need to learn about it
|
||
|
|
|
||
|
|
### Adopt another standard
|
||
|
|
|
||
|
|
There doesn't seem to be one in the open source world.
|
||
|
|
|
||
|
|
### Adopt a project-specific approach
|
||
|
|
|
||
|
|
Define our own standard and formatting for commit messages.
|
||
|
|
|
||
|
|
* Bad, because it's unlikely we'd come up with anything better than Conventional Commits
|
||
|
|
* Bad, because we'd have to write our own documentation
|
||
|
|
* Bad, because we'd have to write our own tooling
|
||
|
|
* Bad, because we can expect at least some contributors to already be familiar with Conventional Commits, they shouldn't have to learn our thing too
|
||
|
|
|
||
|
|
### Do nothing
|
||
|
|
|
||
|
|
Keep the status quo.
|
||
|
|
|
||
|
|
* Good, because contributors do not need to do anything different
|
||
|
|
* Bad, because contributors and reviewers can have different expectations of what is reasonable to include in a PR description, causing friction at review time
|
||
|
|
* Bad, because it keeps the burden on the person responsible for maintaining release notes and changelogs is still high
|