When to write a proposal
Small fixes and documentation changes do not need one. Write a proposal when a change adds to the language, alters how existing code behaves, or introduces a new part of the standard library. If you are unsure, start a conversation first and the maintainers will tell you.
The steps
- 01Write a short proposal describing the problem and the change.
- 02Open it for discussion and revise it as feedback arrives.
- 03The maintainers accept or reject it, and the outcome is recorded.
- 04Accepted proposals are implemented, then marked once they ship.
Writing the proposal
A proposal is a single Markdown file. Keep it short and concrete. Use these headings, in this order:
- Summary: one paragraph describing the change.
- Motivation: the problem, and why it matters.
- Design: the change itself, with examples.
- Alternatives: what else you considered and why you chose this.
- Unresolved questions: what is still open.
Statuses
Each proposal carries one status at a time.
- draftThe author is still writing. Not yet open for review.
- proposedOpen for public discussion.
- acceptedApproved by the maintainers, waiting for an implementation.
- implementedShipped in a release.
- rejectedDeclined. The text and the reasons are kept for the record.
- withdrawnPulled back by its author before a decision.
Numbering
Numbers are assigned in order when a proposal is first submitted and never reused, so TDP-001 always refers to the same document.