diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b17ad3bca62..e729811d4dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ - [Ease of reviewing](#ease-of-reviewing) - [Workflow](#workflow) - [Project Board](#project-board) + - [Architecture Decision Records (ADR)](#architecture-decision-records-adr) - [Development Procedure](#development-procedure) - [Testing](#testing) - [Pull Requests](#pull-requests) @@ -99,6 +100,14 @@ We use self-organizing principles to coordinate and collaborate across organizat The developers work in sprints, which are available in a [GitHub Project](https://github.com/orgs/cosmos/projects/28/views/2). +## Architecture Decision Records (ADR) + +When proposing an architecture decision for Gaia, please start by opening an [issue](https://github.com/cosmos/gaia/issues/new/choose) or a [discussion](https://github.com/cosmos/gaia/discussions/new) with a summary of the proposal. Once the proposal has been discussed and there is rough alignment on a high-level approach to the design, you may either start development, or write an ADR. + +If your architecture decision is a simple change, you may contribute directly without writing an ADR. However, if you are proposing a significant change, please include a corresponding ADR. + +To create an ADR, follow the [template](./docs/architecture/adr-template.md) and [doc](./docs/architecture/README.md). If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/gaia/tree/main/docs/architecture). + ## Development Procedure `main` must be stable, include only completed features and never fail `make lint`, `make run-tests`, or `make build/install`. diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md new file mode 100644 index 00000000000..a547cc29186 --- /dev/null +++ b/docs/architecture/PROCESS.md @@ -0,0 +1,57 @@ +# 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 and solicit input from the stewarding team, if you want to get an early feedback. +3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded. +4. Add an entry to a list in the README file [Table of Contents](./README.md#adr-table-of-contents). +5. Create a Pull Request to propose a new ADR. + +## ADR life cycle + +ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST firstly understand the problem and collect feedback through a GitHub Issue. + +1. Every proposal SHOULD start with a new GitHub Issue or be a result of existing Issues. The Issue should contain just a brief proposal summary. + +2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`. + +3. An ADR doesn't have to arrive to `main` with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. + +4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. + +5. 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. + +6. Merged ADRs SHOULD NOT be deleted. + +### ADR status + +Status has two components: + +```text +{CONSENSUS STATUS} {IMPLEMENTATION STATUS} +``` + +IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. + +#### Consensus Status + +```mermaid +flowchart TD + A[DRAFT] --> B[PROPOSED] + B --> C[LAST CALL YYYY-MM-DD] + B --> D[ABANDONED] + C --> E[ACCEPTED or REJECTED] + E --> F[SUPERSEDED by ADR-xxx] +``` + +* `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 agreement 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/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 00000000000..ebf8f04afb3 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,64 @@ + + +# Architecture Decision Records (ADR) + +This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. + +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 [here](https://adr.github.io/). + +## 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 +- Discarded solution spaces and why they were discarded +- 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 turn 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 + +### Accepted + +- n/a + +### Proposed + +- n/a + +### Draft + +- n/a + +### Rejected + +- [ADR 001: Interchain Accounts](./adr-001-interchain-accounts.md) diff --git a/docs/readiness/adr-001-interchain-accounts.md b/docs/architecture/adr-001-interchain-accounts.md similarity index 92% rename from docs/readiness/adr-001-interchain-accounts.md rename to docs/architecture/adr-001-interchain-accounts.md index c73c97c5d71..30f0b57abf3 100644 --- a/docs/readiness/adr-001-interchain-accounts.md +++ b/docs/architecture/adr-001-interchain-accounts.md @@ -2,26 +2,19 @@ order: 2 --> ---- - -ADR: 001 -Title: Interchain Accounts -Status: Draft Implements -Category: Feature -Author: Sean King & Damian Nolan -Created: 2022-01-19 -Mdified: 2022-01-19 -Requires: Cosmos-SDK, go-ibc -Required-By: mauth -Implements: Interchain Accounts ---- - # ADR 001: Interchain Accounts ## Changelog - 2022-02-04: added content - 2022-01-19: init +- 2023-06-28: mark as rejected + +## Status + +REJECTED Not Implemented + +**Reason:** The IBC team decided to integrate this functionality directly into their codebase and maintain it, because multiple users require it. ## Abstract @@ -98,4 +91,4 @@ There are future releases of Interchain Accounts which are expected to be backwa ## Additional Research & References - [Why Interchain Accounts Change Everything for Cosmos Interoperability](https://medium.com/chainapsis/why-interchain-accounts-change-everything-for-cosmos-interoperability-59c19032bf11) -- [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts) +- [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts) \ No newline at end of file diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md new file mode 100644 index 00000000000..95e5a5886e6 --- /dev/null +++ b/docs/architecture/adr-template.md @@ -0,0 +1,58 @@ + + +# 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 contains all the context one needs to understand the current state, and why there is a problem. +> It should be as succinct as possible and introduce the high level idea behind the solution. +> The language in this section is value-neutral. It is simply describing facts. + +## Decision + +> This section explains all of the details of the proposed solution, including implementation details. +It should also describe affects / corollary items that may need to be changed as a part of this. +If the proposed change will be large, please also indicate a way to do the change to maximize ease of review. +(e.g. the optimal split of things to do between separate PR's) + +## Consequences + +> This section describes the consequences, after applying the decision. +> All consequences should be summarized here, not just the "positive" ones. + +### Positive + +> {positive consequences} + +### Negative + +> {negative consequences} + +### Neutral + +> {neutral consequences} + +## References + +> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here! + +* {reference link} diff --git a/docs/readiness/README.md b/docs/readiness/README.md deleted file mode 100644 index 98d8e19ac72..00000000000 --- a/docs/readiness/README.md +++ /dev/null @@ -1,112 +0,0 @@ - - -# Architecture Decision Records (ADR) - -This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. - -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 - -### Process - -1. Copy the `template.md` file. Use the following filename pattern: `adr-next_number-title.md` -2. Link the ADR in the related feature epic -3. Create a draft Pull Request if you want to get early feedback. -4. Make sure the context and a solution is clear and well documented. -5. Add an entry to a list in the README file [Table of Contents](#adr-table-of-contents). -6. Create a Pull Request to publish the ADR proposal. - -### Life cycle - -ADR creation is an **iterative** process. Rather than solving all decisions in a single PR, it's best to first understand the problem and then solicit feedback through Github Issues. - -1. Every proposal should start with a new GitHub Issue and be linked to the corresponding Feature Epic. The Issue should contain a brief proposal summary. - -2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `template.md`. - -3. An ADR doesn't have to arrive to `master` with an `accepted` status in a single PR. If the motivation is clear and the solution is sound, we should be able to merge it and keep a `proposed` status. - -4. If a `proposed` ADR is merged, then it should clearly document outstanding issues in the Feature Epic. - -5. The PR should always be merged. In the case of a faulty ADR, it's still preferable to merge it with a `rejected` status. The only time the ADR should not be merged is if the author abandons it. - -6. Merged ADRs **should not** be pruned. - -### Status - -Status has two components: - -``` -{CONSENSUS STATUS} {IMPLEMENTATION STATUS} -``` - -IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. - -#### Consensus Status - -``` -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 Hub 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. - -**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 - -### Accepted - -- n/a - -### Proposed - -- n/a - -### Draft - -- [ADR 001: Interchain Accounts](./adr-001-interchain-accounts.md) diff --git a/docs/readiness/template.md b/docs/readiness/template.md deleted file mode 100644 index e7f148a2b98..00000000000 --- a/docs/readiness/template.md +++ /dev/null @@ -1,95 +0,0 @@ - - ---- - -ADR: (number) -Title: (short title) -Status: (current ADR status) -Category: (Module or Feature) -Author: (primary & additional authors) -Created: (creation date) -Mdified: (modification date) -Requires: (optional list of downstream ADRs) -Required-By: (optional list of upstream ADRs) -Implements: (optional list of component ADRs) ---- - -# ADR {ADR-NUMBER}: {TITLE} - -## Changelog - -- {date}: {changelog} - -## Abstract - -> "If you can't explain it simply, you don't understand it well enough." Provide a short (~200 word) high level description of the issue being addressed and rationale for such. - -## Rationale - -> Describe the context and rationale for proposing a new feature or module. The language in this section is value-neutral and should clearly explain the problem and motivation that the proposal aims to resolve. - -## Desired Outcome - -> Provides succinct answers to the issues documented above. Response should include desired characteristics / properties of feature/protocol, and effects if properties are violated. - -## Consequences - -> This section describes the resulting context, after applying the decision (positive, neutral, and negative). - -#### Backwards Compatibility - -> Discussion of compatibility or lack thereof with previous standards. - -#### Forward Compatibility - -> Discussion of compatibility or lack thereof with expected future standards. - -## Technical Specification - -> Details main technical standard, may include some of the following: syntax, semantics, sub-protocols, algorithms, data structures, etc. - -## Development - -> Documents the following for readiness/deployment milestones - -- Integration requirements (CLI) -- Testing (Simulations, Core Team Testing, Partner Testing) -- Audits (Internal Dev review, Third-party review, Bug Bounty) -- Networks (Testnets, Productionnets, Mainnets) - -### Backwards Compatibility - -> Discussion of compatibility or lack thereof with expected future standards. - -## Governance [optional] - -> If relevant, will include: - -- Linked Hub Governance proposal -- Core Community Governance -- Steering Community -- Timelines & Roadmap - -## Project Integrations [optional] - -> Document internal and/or external integration partners - -- Gaia Integrations -- Integration Partner -- IBC Readiness - -#### Downstream User Impact Report - -#### Upstream Partner Impact Report - -#### Inter-module Dependence - -## Support - -> Includes additional technical, marketing, educational, etc support - -## Additional Research & References - -> Additional links or sections to address