Use prescribed templates for RFCs and ADRs

[SoumayaMauthoorMOJ]

• Superseded by: N/A
• Related:
  • Use both RFCs and ADRs for documenting changes #47
  • Use prescribed templates for RFCs and ADRs #48
  • Use GitHub Discussions to document RFCs #39
  • Store RFCs and ADRs in the relevant repository and publish to handbook #49

Need (Context / Problem)

We need some recommendations for what to include in RFCs and/or ADRs in order to make sure that all relevant items are recorded whilst minimising duplication and ensuring proportionality

Approach

Title: Should start with a verb, as we have used for the RFC strategy discussions

RFC Template

Based on this template which is based on Stanford's NABC approach

Status: Proposed, Accepted, Superseded, Rejected

Need (Context / Problem)

Why do we need to have this change? What was the main reason why you came up with this proposal?

Approach

How are you planning to satisfy the need defined above? The explanation should be as detailed as necessary to fulfill the need.

Pros & Cons

What are the benefits of the proposed approach? Focus on the factual benefits rather than personal points of view.

Alternatives

Write down at least one alternative together with their pros and cons.

---

ADR Template

Based on GDS Documenting architecture decisions

Status: Proposed, Accepted, Superseded, Rejected

Context

The facts behind the need to make the decision

Decision

What the team has decided to do

Consequences

Both positive and negative consequences of the decision

Pros and Cons

These templates have a minimalistic structure which should make it easy to use. They also make it easy to understand the difference. between RFCs and ADRs.

Alternatives

• The vue.js RFC Template includes a few more sections like adoption strategy, which could be helpful, but could also make it more needlessly complicated
• We could add a rationale heading to the ADR template to force people to add a rationale which is often skipped, but this would stray from the GDS way.
• There are many more possible templates out there - we could allow teams to chose the template they prefer as long as they are surfaced centrally