Merge pull request #24 from weaveworks/init_docs

docs: use adrs for decisions
liquidmetal-dev · Nov 10, 2021 · d8a96a7 · d8a96a7
2 parents fff66ad + ae750d8
commit d8a96a7
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 0 deletions.
diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md
@@ -0,0 +1,17 @@
+<!-- ADR will have been discussed using a GitHub discussion prior to creating this -->
+# 0. Title
+<!-- A short and clear title which is prefixed with the ADR number -->
+
+* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- mandatory -->
+* Date: 2020-10-29 [YYY-MM-DD - date of the decision] <!-- mandatory -->
+* Authors: [list of GitHub handles for the authors]
+* Deciders: [list of GitHub handles for those that made the decision]  <!-- mandatory -->
+
+## Context
+<!-- What is the context of the decision and whats the motivation -->
+
+## Decision
+<!-- What is the decision that has been made -->
+
+## Consequences
+<!-- Whats the result or impact of this decision. Does anything need to change and are new GitHub issues created as a result -->
diff --git a/docs/adr/0001-use-adrs-for-decisions.md b/docs/adr/0001-use-adrs-for-decisions.md
@@ -0,0 +1,23 @@
+# 1. Use ADRs to record decisions
+
+* Status: accepted
+* Date: 2021-11-10
+* Authors: @richardcase
+* Deciders: @richardcase
+
+## Context
+
+Decisions that affect the development of Cluster API Provider MicroVM that are not captured via a proposal need to be captured in some way. We need a method that is lightweight and easy to discover the decision that have been made. The record of decisions will help future contributors to the project to understand why something has been implemented or is done a certain way.
+
+## Decision
+
+The project will use [Architectural Decision Records (ADR)](https://adr.github.io/) to record decisions that are made outside of a proposal.
+
+A [template](./0000-template.md) has been created based on prior work:
+
+* https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+* https://adr.github.io/madr/
+
+## Consequences
+
+When decisions are made that affect the entire project then a new ADR needs to be created. Likewise, if a decision has been superceded then we need to capture this as a new ADR and mark the previous ADR as superceded. Maintainers and contributors will need to decide when an ADR is to be created.