* Update ADR template
The reason for this proposed update to the ADR template is twofold:
1. There's currently no easy way to cross-reference between ADRs and
issues/PRs on GitHub. This may be easy to manage for those with
context while they're working on implementing an ADR, but after time
passes and for complex ADRs it gets more difficult for newcomers to
the codebase to track both the implementation status of the ADR or
its historical context and discussions.
2. We should not allow for "proposed" ADRs. An ADR is a **decision
record**, which implies acceptance, and not a proposal. RFCs provide
a mechanism to make proposals.
Signed-off-by: Thane Thomson <connect@thanethomson.com>
* Add example of one ADR superseding another
Signed-off-by: Thane Thomson <connect@thanethomson.com>
* Move "Proposed" ToC entries to "Accepted".
It's possible some of these should actually be "Implemented", but I did not try
to go through each one to distinguish.
* Revert "Move "Proposed" ToC entries to "Accepted"."
This reverts commit d8d2907e98.
Signed-off-by: Thane Thomson <connect@thanethomson.com>
* Fix Markdown formatting
Signed-off-by: Thane Thomson <connect@thanethomson.com>
* Add "Deprecated" section to ADR TOC
Signed-off-by: Thane Thomson <connect@thanethomson.com>
* Expand ADR template to explicitly cater for rejected ADRs
Signed-off-by: Thane Thomson <connect@thanethomson.com>
Co-authored-by: M. J. Fromberger <fromberger@interchain.io>
This is a location to record all high-level architecture decisions in the tendermint project.
You can read more about the ADR concept in this blog post.
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.
Note the context/background should be written in the present tense.
Thane Thomson