diff --git a/docs/docs/developers/architecture/PROCESS.md b/docs/docs/developers/architecture/PROCESS.md new file mode 100644 index 000000000..3797a511b --- /dev/null +++ b/docs/docs/developers/architecture/PROCESS.md @@ -0,0 +1,76 @@ +# ADR Creation Process + +1. Copy the `adr-template.md` file. Use the following filename pattern: + `adr-{next_number}-{title}.md` +2. Create a draft Pull Request if you want to get an early feedback. +3. Make sure the context and a solution is clear and well documented. +4. Add an entry to a list in the [README](./README.md) file. +5. Create a Pull Request to propose a new ADR. + +## What is an ADR? + +An ADR is a document to document an implementation and design that may or may +not have been discussed in an RFC. + +While an RFC is meant to replace synchronous communication in a distributed +environment, an ADR is meant to document an already made decision. + +An ADR won't come with much of a communication overhead because the discussion +was recorded in an RFC or a synchronous discussion. If the consensus came from +a synchronous discussion then a short excerpt should be added to the ADR to +explain the goals. + +## ADR life cycle + +ADR creation is an **iterative** process. Instead of having a high amount of +communication overhead, an ADR is used when there is already a decision made +and implementation details need to be added. The ADR should document what the +collective consensus for the specific issue is and how to solve it. + +1. Every ADR should start with either an RFC or discussion where consensus has + been met. + +2. Once consensus is met, a GitHub Pull Request (PR) is created with a new + document based on the `adr-template.md`. + +3. If a _proposed_ ADR is merged, then it should clearly document outstanding + issues either in ADR document notes or in a GitHub Issue. + +4. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer + to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be + merged is if the author abandons it. + +5. Merged ADRs SHOULD NOT be pruned. + +### ADR status + +Status has two components: + +```text +{CONSENSUS STATUS} {IMPLEMENTATION STATUS} +``` + +IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. + +#### Consensus Status + +```text +DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx + \ | + \ | + v v + ABANDONED +``` + +* `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. +* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. +* `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. +* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. +* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. +* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. +* `ABANDONED`: the ADR is no longer pursued by the original authors. + +## Language used in ADR + +* The context/background should be written in the present tense. +* Avoid using a first, personal form. diff --git a/docs/docs/developers/architecture/README.md b/docs/docs/developers/architecture/README.md new file mode 100644 index 000000000..8928135d5 --- /dev/null +++ b/docs/docs/developers/architecture/README.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 1 +--- + +# Architecture Decision Records (ADR) + +Inspired by [the ADRs of the Cosmos SDK](https://docs.cosmos.network/v0.50/build/architecture). + +This is a location to record all high-level architecture decisions in the Warden Protocol. + +An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. +An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. +An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). + +You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). + +## Rationale + +ADRs are intended to be the primary mechanism for proposing new feature designs +and new processes, for collecting community input on an issue, and for +documenting the design decisions. + +An ADR should provide: + +* Context on the relevant goals and the current state +* Proposed changes to achieve the goals +* Summary of pros and cons +* References +* Changelog + +Note the distinction between an ADR and a spec. The ADR provides the context, +intuition, reasoning, and justification for a change in architecture, or for +the architecture of something new. The spec is much more compressed and +streamlined summary of everything as it stands today. + +If recorded decisions turned out to be lacking, convene a discussion, record +the new decisions here, and then modify the code to match. + +## Creating new ADR + +Read about the [PROCESS](./PROCESS.md). + +### Use RFC 2119 Keywords + +When writing ADRs, follow the same best practices for writing RFCs. When +writing RFCs, key words are used to signify the requirements in the +specification. These words are often capitalized: "MUST", "MUST NOT", +"REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", +and "OPTIONAL. They are to be interpreted as described in [RFC +2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## ADR Table of Contents + +### Draft + +* [ADR 044: Guidelines for Updating Protobuf Definitions](./adr-044-protobuf-updates-guidelines.md) diff --git a/docs/docs/developers/architecture/_category_.json b/docs/docs/developers/architecture/_category_.json new file mode 100644 index 000000000..bbf3879fc --- /dev/null +++ b/docs/docs/developers/architecture/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "ADRs", + "position": 99 +} diff --git a/docs/docs/developers/architecture/adr-template.md b/docs/docs/developers/architecture/adr-template.md new file mode 100644 index 000000000..820637cd8 --- /dev/null +++ b/docs/docs/developers/architecture/adr-template.md @@ -0,0 +1,84 @@ +# ADR {ADR-NUMBER}: {TITLE} + +## Changelog + +* {date}: {changelog} + +## Status + +{DRAFT | PROPOSED} Not Implemented + +> Please have a look at the [PROCESS](./PROCESS.md#adr-status) page. +> Use DRAFT if the ADR is in a draft stage (draft PR) or PROPOSED if it's in review. + +## Abstract + +> "If you can't explain it simply, you don't understand it well enough." Provide +> a simplified and layman-accessible explanation of the ADR. +> A short (~200 word) description of the issue being addressed. + +## Context + +> This section describes the forces at play, including technological, political, +> social, and project local. These forces are probably in tension, and should be +> called out as such. The language in this section is value-neutral. It is simply +> describing facts. It should clearly explain the problem and motivation that the +> proposal aims to resolve. +> {context body} + +## Alternatives + +> This section describes alternative designs to the chosen design. This section +> is important and if an adr does not have any alternatives then it should be +> considered that the ADR was not thought through. + +## Decision + +> This section describes our response to these forces. It is stated in full +> sentences, with active voice. "We will ..." +> {decision body} + +## Consequences + +> This section describes the resulting context, after applying the decision. All +> consequences should be listed here, not just the "positive" ones. A particular +> decision may have positive, negative, and neutral consequences, but all of them +> affect the team and project in the future. + +### Backwards Compatibility + +> All ADRs that introduce backwards incompatibilities must include a section +> describing these incompatibilities and their severity. The ADR must explain +> how the author proposes to deal with these incompatibilities. ADR submissions +> without a sufficient backwards compatibility treatise may be rejected outright. + +### Positive + +> {positive consequences} + +### Negative + +> {negative consequences} + +### Neutral + +> {neutral consequences} + +## Further Discussions + +> While an ADR is in the DRAFT or PROPOSED stage, this section should contain a +> summary of issues to be solved in future iterations (usually referencing +> comments from a pull-request discussion). +> +> Later, this section can optionally list ideas or improvements the author or +> reviewers found during the analysis of this ADR. + +## Test Cases [optional] + +Test cases for an implementation are mandatory for ADRs that are affecting +consensus changes. Other ADRs can choose to include links to test cases if +applicable. + +## References + +* {reference link} diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 29649a5de..f0398d7a2 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -41,6 +41,7 @@ const config: Config = { docs: { routeBasePath: '/', sidebarPath: './sidebars.ts', + exclude: ['**/adr-template.md'], }, theme: { customCss: ['./src/css/custom.css'],