From ea3c9c1b8e43998226cb11e1afeb535582d3ca01 Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Fri, 8 Sep 2023 21:40:44 +0200 Subject: [PATCH] docs: Start formally documenting decisions as ADRs (#10) Ensure that project decisions are clear and transparent to potential contributors by documenting them in `docs/decisions`, starting with the decision to use conventional commits. Use the MADR format (https://adr.github.io/madr/). --- {doc => docs}/CLAs.md | 0 {doc => docs}/ViewModelInterface.md | 0 .../0001-use-conventional-commits.md | 68 ++++++++++++++++ docs/decisions/adr-template.md | 79 +++++++++++++++++++ 4 files changed, 147 insertions(+) rename {doc => docs}/CLAs.md (100%) rename {doc => docs}/ViewModelInterface.md (100%) create mode 100644 docs/decisions/0001-use-conventional-commits.md create mode 100644 docs/decisions/adr-template.md diff --git a/doc/CLAs.md b/docs/CLAs.md similarity index 100% rename from doc/CLAs.md rename to docs/CLAs.md diff --git a/doc/ViewModelInterface.md b/docs/ViewModelInterface.md similarity index 100% rename from doc/ViewModelInterface.md rename to docs/ViewModelInterface.md diff --git a/docs/decisions/0001-use-conventional-commits.md b/docs/decisions/0001-use-conventional-commits.md new file mode 100644 index 000000000..c747c7f8f --- /dev/null +++ b/docs/decisions/0001-use-conventional-commits.md @@ -0,0 +1,68 @@ +# 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: +> +> ``` +> [optional scope]: +> [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 diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md new file mode 100644 index 000000000..54143f1d3 --- /dev/null +++ b/docs/decisions/adr-template.md @@ -0,0 +1,79 @@ +--- +# These are optional elements. Feel free to remove any of them. +status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} +date: {YYYY-MM-DD when the decision was last updated} +deciders: {list everyone involved in the decision} +consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication} +informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication} +--- +# {short title of solved problem and solution} + +## Context and Problem Statement + +{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. +You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.} + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## Decision Outcome + +Chosen option: "{title of option 1}", because +{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. + + +### Consequences + +* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …} +* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …} +* … + + +## Validation + +{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} + + +## Pros and Cons of the Options + +### {title of option 1} + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + +### {title of other option} + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +## More Information + +{You might want to provide additional evidence/confidence for the decision outcome here and/or +document the team agreement on the decision and/or +define when this decision when and how the decision should be realized and if/when it should be re-visited and/or +how the decision is validated. +Links to other decisions and resources might here appear as well.}