[This is a template for Magma's change proposal process, documented here.]
Proposal: [Title]
Author(s): [Author Name, Co-Author Name]
Last updated: [Date]
Discussion at https://github.com/magma/magma/issues/4888.
Context & scope
[Give the reader a very rough overview of the landscape in which the new system is being built. This isn’t a requirements doc; keep it succinct! Bring the reader up to speed. Focus on objective background facts.]
Goals
[Bulleted points; for example, “ACID compliance” for a database.]
Non-goals
[Bulleted points; for example, “ACID compliance” for a database.]
Proposal
[Start with an overview of your design, and then go into details. Focus on the trade-offs that you made in the design in order to make sure this doc has long-term value. Given the context (facts), and goals vs non-goals, this is the place to suggest a solution and substantiate why it best satisfies those goals.]
Alternatives considered
[This section lists alternative designs that might have reasonably achieved considerable outcomes. The focus of each should be on the trade-offs that each alternative makes and how those trade-offs led to the decision to select the primary design. This is probably the most important section; it shows very explicitly why the selected solution is the best given the goals. This is important, since your reader is likely wondering about one or more alternative solutions.]
Cross-cutting concerns
[These are relatively short-sections where the template forces the author to write 1-2 sentences to demonstrate consideration of how the design impacts a concern -- and how it is addressed. Teams should standardize on the set of concerns.]
Compatibility
[A discussion of the change with regard to backward / forward compatibility.]
Observability and Debug
[A description, of how issues with this design would be observed and debugged in various stages from development through production.]
Security & privacy
[A description of the security and/or privacy impact of the change (if any).]
Open issues (if applicable)
[A discussion of issues relating to this proposal for which the author does not know the solution. This section may be omitted if there are none.]