diff --git a/doc/adr/index.rst b/doc/adr/index.rst new file mode 100644 index 00000000000..9c2fec672b0 --- /dev/null +++ b/doc/adr/index.rst @@ -0,0 +1,27 @@ +Architectural Decision Records +============================== + +We document our architectural and design decisions for all of our components. +In order to do that, there is practice called architectural decision records ("ADR"), +that we can integrate into our workflow. +An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences. + +The goals are: + +* making decisions transparent to internal/external stakeholders and contributors. + +* getting feeback on decisions that we're about to make or have made + +* providing external contributors a framework to propose architectural changes + +* providing a big picture of all major decisions that were made + +The general process for creating an ADR is: + +1. cloning the repository + +2. creating a new file with the format `-.rst` in the directory `doc/adr` + +3. adding the ADR in the table of content tree of the Readthedocs + +4. committing and pushing to the repository diff --git a/doc/index.rst b/doc/index.rst index e1ebf3e0153..e687b49c80e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,6 +13,12 @@ To read more about the overall architecture of writing applications using Plutus howtos/index troubleshooting +.. toctree:: + :caption: Architecture design records + :maxdepth: 1 + + adr/index + .. toctree:: :caption: Reference :maxdepth: 2