You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

101 lines
3.2 KiB

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 <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 d8d2907e985d0098ba99280fff496711175c529e. 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>
3 years ago
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 <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 d8d2907e985d0098ba99280fff496711175c529e. 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>
3 years ago
  1. # ADR {ADR-NUMBER}: {TITLE}
  2. ## Changelog
  3. - {date}: {changelog}
  4. ## Status
  5. > An architecture decision is considered "proposed" when a PR containing the ADR
  6. > is submitted. When merged, an ADR must have a status associated with it, which
  7. > must be one of: "Accepted", "Rejected", "Deprecated" or "Superseded".
  8. >
  9. > An accepted ADR's implementation status must be tracked via a tracking issue,
  10. > milestone or project board (only one of these is necessary). For example:
  11. >
  12. > Accepted
  13. >
  14. > [Tracking issue](https://github.com/tendermint/tendermint/issues/123)
  15. > [Milestone](https://github.com/tendermint/tendermint/milestones/123)
  16. > [Project board](https://github.com/orgs/tendermint/projects/123)
  17. >
  18. > Rejected ADRs are captured as a record of recommendations that we specifically
  19. > do not (and possibly never) want to implement. The ADR itself must, for
  20. > posterity, include reasoning as to why it was rejected.
  21. >
  22. > If an ADR is deprecated, simply write "Deprecated" in this section. If an ADR
  23. > is superseded by one or more other ADRs, provide local a reference to those
  24. > ADRs, e.g.:
  25. >
  26. > Superseded by [ADR 123](./adr-123.md)
  27. Accepted | Rejected | Deprecated | Superseded by
  28. ## Context
  29. > This section contains all the context one needs to understand the current state,
  30. > and why there is a problem. It should be as succinct as possible and introduce
  31. > the high level idea behind the solution.
  32. ## Alternative Approaches
  33. > This section contains information around alternative options that are considered
  34. > before making a decision. It should contain a explanation on why the alternative
  35. > approach(es) were not chosen.
  36. ## Decision
  37. > This section records the decision that was made.
  38. > It is best to record as much info as possible from the discussion that happened.
  39. > This aids in not having to go back to the Pull Request to get the needed information.
  40. ## Detailed Design
  41. > This section does not need to be filled in at the start of the ADR, but must
  42. > be completed prior to the merging of the implementation.
  43. >
  44. > Here are some common questions that get answered as part of the detailed design:
  45. >
  46. > - What are the user requirements?
  47. >
  48. > - What systems will be affected?
  49. >
  50. > - What new data structures are needed, what data structures will be changed?
  51. >
  52. > - What new APIs will be needed, what APIs will be changed?
  53. >
  54. > - What are the efficiency considerations (time/space)?
  55. >
  56. > - What are the expected access patterns (load/throughput)?
  57. >
  58. > - Are there any logging, monitoring or observability needs?
  59. >
  60. > - Are there any security considerations?
  61. >
  62. > - Are there any privacy considerations?
  63. >
  64. > - How will the changes be tested?
  65. >
  66. > - If the change is large, how will the changes be broken up for ease of review?
  67. >
  68. > - Will these changes require a breaking (major) release?
  69. >
  70. > - Does this change require coordination with the SDK or other?
  71. ## Consequences
  72. > This section describes the consequences, after applying the decision. All
  73. > consequences should be summarized here, not just the "positive" ones.
  74. ### Positive
  75. ### Negative
  76. ### Neutral
  77. ## References
  78. > Are there any relevant PR comments, issues that led up to this, or articles
  79. > referenced for why we made the given design choice? If so link them here!
  80. - {reference link}