Skip to content

Commit

Permalink
Updating the ADR template (cosmos#7449)
Browse files Browse the repository at this point in the history
* Updating the ADR template

Introducing few small sections to the template:

* Summary: IMHO it's very valuable for every reader to quickly see what this ADR is about. Must be short.
* Backwards Compatibility -- each ADR MUST analyze backward compatibility issue. Let's make it clear and put as the ADR subsection.
* Test Cases -- often, when analyzing a problem and implementing a solution, it's very useful to define test-cases. Hence it SHOULD be a part of the template.

Inspiration: Enterprise Ethreum Alliance Proposal [template](https://github.com/EntEthAlliance/EEPs/blob/master/draft/templates/EEP0002-Standards_Proposal_Template.md)

* change Summary -> Abstract
  • Loading branch information
robert-zaremba authored Oct 5, 2020
1 parent d9ede65 commit 435fc83
Showing 1 changed file with 22 additions and 1 deletion.
23 changes: 22 additions & 1 deletion docs/architecture/adr-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,35 @@
> A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement.
> {Deprecated|Proposed|Accepted} {Implemented|Not Implemented}

## 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.
> 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}

## 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}
Expand All @@ -35,6 +50,12 @@

{neutral consequences}


## 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}

0 comments on commit 435fc83

Please sign in to comment.