999-template.rst (2128B)
1 DD XY: Template 2 ############### 3 4 :Design status: Draft 5 :Implementation status: Not started 6 :DD shepherd: NAME or TBD 7 :Historical contributors: NAME(S) or TBD 8 :First published: YYYY-MM-DD 9 :Last substantive change: YYYY-MM-DD 10 11 Every numbered design document must carry all six fields above. Keep design 12 maturity separate from implementation progress: 13 14 * ``Design status`` is one of ``Draft``, ``Proposed``, ``Accepted``, 15 ``Experimental``, ``Superseded``, ``Rejected``, or ``Abandoned``. 16 * ``Implementation status`` is one of ``Not started``, ``Prototype``, 17 ``Partial``, ``Implemented``, ``Removed``, ``Unknown``, or ``N/A``. 18 19 Use ``DD shepherd: TBD`` rather than omitting ownership. List people who made 20 historically substantive contributions, not authors of purely mechanical 21 changes. ``First published`` is the date the DD first appeared, while ``Last 22 substantive change`` excludes formatting-only changes. 23 24 Add the following fields when applicable: 25 26 * ``Implementation evidence`` using repository names and ISO dates for 27 auditable landing evidence. Do not include commit hashes. State explicitly 28 when cited work is not merged into the reviewed main branch. 29 * ``Superseded by`` when the design status is ``Superseded``. 30 * ``Normative references`` for current API specifications or reference 31 manuals. A DD is not itself a normative API specification. 32 * ``Upstream follow-up`` when a verified correction belongs in generated or 33 externally maintained documentation and must not be made in this repository. 34 35 Summary 36 ======= 37 38 Motivation 39 ========== 40 41 Requirements 42 ============ 43 44 Proposed Solution 45 ================= 46 47 Test Plan 48 ========= 49 50 (If this DD concerns a new or changed feature, describe how it can be tested.) 51 52 Definition of Done 53 ================== 54 55 (Only applicable to design documents that describe a new feature. While the 56 DoD is not satisfied yet, a user-facing feature **must** be behind a feature 57 flag or dev-mode flag.) 58 59 Alternatives 60 ============ 61 62 Drawbacks 63 ========= 64 65 Discussion / Q&A 66 ================ 67 68 (This should be filled in with results from discussions on mailing lists / personal communication.)