README.rst (3440B)
1 Design document lifecycle 2 ######################### 3 4 Design documents record why a change was considered and how its design 5 evolved. They are not the normative specification after a design has been 6 implemented. Implemented protocol behavior belongs in the API specification; 7 implementation, deployment, and operational behavior belongs in the 8 corresponding reference manual. 9 10 Required metadata 11 ================= 12 13 Every numbered design document must begin with these fields: 14 15 ``Design status`` 16 The state of the design decision. The allowed values are ``Draft``, 17 ``Proposed``, ``Accepted``, ``Experimental``, ``Superseded``, ``Rejected``, 18 and ``Abandoned``. 19 20 ``Implementation status`` 21 The state of the described implementation. The allowed values are ``Not 22 started``, ``Prototype``, ``Partial``, ``Implemented``, ``Removed``, 23 ``Unknown``, and ``N/A``. 24 25 ``DD shepherd`` 26 The person currently responsible for moving the design forward and keeping 27 its status accurate. Use ``TBD`` when no current shepherd has agreed to 28 take responsibility; historical authorship is not an assignment of current 29 ownership. 30 31 ``Historical contributors`` 32 The people who made substantive contributions to the design text. Do not 33 include authors of repository-wide formatting-only changes. 34 35 ``First published`` 36 The ISO date of the first commit containing substantive content for this DD. 37 Copied template or predecessor-file history does not count. 38 39 ``Last substantive change`` 40 The ISO date of the newest commit that changed the design's meaning. Pure 41 spelling, formatting, build, or title-normalization changes do not count. 42 43 The following fields are added when applicable: 44 45 ``Implementation evidence`` 46 Repositories and ISO dates that establish a prototype, landing, completion, 47 or removal. Work that is present only on a feature branch must be identified 48 as such and has implementation status ``Prototype``. 49 50 ``Superseded by`` 51 The successor design or normative specification. 52 53 ``Normative references`` 54 The API specifications and reference manuals that now own the implemented 55 behavior. 56 57 ``Upstream follow-up`` 58 A discrepancy whose authoritative source is generated by, or maintained in, 59 another repository. Generated files in this repository must not be edited 60 by hand. 61 62 Interpreting lifecycle states 63 ============================= 64 65 The two status fields are deliberately independent. For example, a design 66 can be ``Superseded`` while its historical implementation remains 67 ``Implemented``. A feature that has substantial implementation only on a 68 non-main branch is a ``Prototype``, not ``Partial`` or ``Implemented``. 69 Policy documents use ``N/A`` unless they define measurable software or 70 platform deliverables. 71 72 Titles beginning with ``XX`` are a legacy visual marker for deprecated design 73 documents. They are retained for historical continuity, but the metadata 74 fields are authoritative. 75 76 Maintaining design documents 77 ============================ 78 79 When a feature lands, update its implementation status and evidence, check 80 only Definition-of-Done items supported by repository or API evidence, and add 81 the normative references. Preserve useful historical discussion, but place a 82 prominent note before stale material so readers do not mistake it for current 83 behavior. Unresolved product, security, or legal questions must remain 84 explicit instead of being silently resolved from implementation accidents.