This text is adapted from JEP-2 and is intended as writing prompts for ARM proposals. Any of the sections not flagged as REQUIRED is optional.
REQUIRED -- Provide a one-paragraph summary of the proposal, no more than a few sentences. This summary will be rolled up into feature lists and other documents, so please take the time to make it short and sweet.
What are the goals of this proposal? Omit this section if you have nothing to say beyond what's already in the summary.
Describe any goals you wish to identify specifically as being out of scope for this proposal.
If the success of this work can be gauged by specific numerical metrics and associated goals then describe them here.
Why should this work be done? What are its benefits? Who's asking for it? How does it compare to the competition, if any?
REQUIRED -- Describe the enhancement in detail: Both what it is and, to the extent understood, how you intend to implement it. Summarize, at a high level, all of the interfaces you expect to modify or extend, including APIs, command-line switches, network protocols, and file formats. Explain how failures in applications using this enhancement will be diagnosed, both during development and in production. Describe any open design issues.
This section will evolve over time as the work progresses, ultimately becoming the authoritative high-level description of the end result. Include hyperlinks to additional documents as required.
What kinds of test development and execution will be required in order to validate this enhancement, beyond the usual mandatory unit tests? Be sure to list any special platform or hardware requirements.
What criteria should people use to evaluate the alternatives? If there are suggestions you have as the author for helping readers decide between alternatives (or whether to the ARM should be implemented at all), build a decision tree here.
Did you consider any alternative approaches or technologies? If so then please describe them here and explain why they were not chosen.
Describe which, if any, of the alternatives you recommend and why you prefer it. This could walk through the Author's use of the "Evaluation" decision tree explaining the rationale.
Describe any risks or assumptions that must be considered along with this proposal. Could any plausible events derail this work, or even render it unnecessary? If you have mitigation plans for the known risks then please describe them.
Describe all dependencies that this ARM has on other ARMs, components, products, or anything else. Dependences upon other ARMs should also be listed in the "depends:" field in the metadata.json.
Describe any ARMs that depend upon this ARM before they can be implemented.
How will this work impact other parts of the platform, the product, and the contributors working on them? Omit any irrelevant items.
- Other Puppet components: ...
- Compatibility: ...
- Security: ...
- Performance/scalability: ...
- User experience: ...
- I18n/L10n: ...
- Accessibility: ...
- Portability: ...
- Packaging/installation: ...
- Documentation: ...
- Spin-offs/Future work: ...
- Other: ...