Templates for RFCs and ADRs used at Microsoft in the 1JS Engineering System.

adr.md

TITLE

Date: YYYY-MM-DD

Status

PROPOSED | ACCEPTED | DEPRECATED

Context

The issue motivating this decision, and any context that influences or constrains the decision.

Decision

The change that we're proposing or have agreed to implement.

Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

rfc.md

{{TITLE: a human-readable title for this RFC!}}

Summary

{{A concise, one-paragraph description of the change.}}

Motivation

{{Why are we doing this? What pain points does this resolve? What use cases does it support? What is the expected outcome? Use real, concrete examples to make your case!}}

Detailed Explanation

{{Describe the expected changes in detail, }}

Rationale and Alternatives

{{Discuss 2-3 different alternative solutions that were considered. This is required, even if it seems like a stretch. Then explain why this is the best choice out of available ones.}}

Implementation

{{Give a high-level overview of implementation requirements and concerns. Be specific about areas of code that need to change, and what their potential effects are. Discuss which sub-components will be affected, and what its overall code effect might be.}}

{{THIS SECTION IS REQUIRED FOR RATIFICATION -- you can skip it if you don't know the technical details when first submitting the proposal, but it must be there before it's accepted}}

How We Teach This

{{ How should this feature be introduced and taught to existing users? }}

Prior Art

{{This section is optional if there are no actual prior examples in other tools}}

{{Discuss existing examples of this change in other tools, and how they've addressed various concerns discussed above, and what the effect of those decisions has been}}

Unresolved Questions and Bikeshedding

{{Write about any arbitrary decisions that need to be made (syntax, colors, formatting, minor UX decisions), and any questions for the proposal that have not been answered.}}

{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}}