From 65065e6054381d8f654e58a7fda5c1cb75113952 Mon Sep 17 00:00:00 2001 From: Thane Thomson Date: Wed, 2 Mar 2022 10:25:30 -0500 Subject: [PATCH] docs: update ADR template (#7789) * 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 * Add example of one ADR superseding another Signed-off-by: Thane Thomson * 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 d8d2907e985d0098ba99280fff496711175c529e. Signed-off-by: Thane Thomson * Fix Markdown formatting Signed-off-by: Thane Thomson * Add "Deprecated" section to ADR TOC Signed-off-by: Thane Thomson * Expand ADR template to explicitly cater for rejected ADRs Signed-off-by: Thane Thomson Co-authored-by: M. J. Fromberger --- docs/architecture/README.md | 5 ++++- docs/architecture/adr-template.md | 28 +++++++++++++++++++++++----- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index a29e69db0..86b54fc51 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -86,13 +86,16 @@ Note the context/background should be written in the present tense. - [ADR-075: RPC Event Subscription Interface](./adr-075-rpc-subscription.md) - [ADR-076: Combine Spec and Tendermint Repositories](./adr-076-combine-spec-repo.md) +### Deprecated + +None + ### Rejected - [ADR-023: ABCI-Propose-tx](./adr-023-ABCI-propose-tx.md) - [ADR-029: Check-Tx-Consensus](./adr-029-check-tx-consensus.md) - [ADR-058: Event-Hashing](./adr-058-event-hashing.md) - ### Proposed - [ADR-007: Trust-Metric-Usage](./adr-007-trust-metric-usage.md) diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md index 00e553437..27225fd70 100644 --- a/docs/architecture/adr-template.md +++ b/docs/architecture/adr-template.md @@ -6,12 +6,30 @@ ## Status -> A decision may be "proposed" if it hasn't been agreed upon yet, or "accepted" -> once it is agreed upon. Once the ADR has been implemented mark the ADR as -> "implemented". If a later ADR changes or reverses a decision, it may be marked -> as "deprecated" or "superseded" with a reference to its replacement. +> An architecture decision is considered "proposed" when a PR containing the ADR +> is submitted. When merged, an ADR must have a status associated with it, which +> must be one of: "Accepted", "Rejected", "Deprecated" or "Superseded". +> +> An accepted ADR's implementation status must be tracked via a tracking issue, +> milestone or project board (only one of these is necessary). For example: +> +> Accepted +> +> [Tracking issue](https://github.com/tendermint/tendermint/issues/123) +> [Milestone](https://github.com/tendermint/tendermint/milestones/123) +> [Project board](https://github.com/orgs/tendermint/projects/123) +> +> Rejected ADRs are captured as a record of recommendations that we specifically +> do not (and possibly never) want to implement. The ADR itself must, for +> posterity, include reasoning as to why it was rejected. +> +> If an ADR is deprecated, simply write "Deprecated" in this section. If an ADR +> is superseded by one or more other ADRs, provide local a reference to those +> ADRs, e.g.: +> +> Superseded by [ADR 123](./adr-123.md) -{Deprecated|Declined|Accepted|Implemented} +Accepted | Rejected | Deprecated | Superseded by ## Context