Design Documents

Design documents serve as an agreed upon plan for the implementation of substantial changes and as a record of the design choices made. See section Change Proposal Process for the overview on the overall contribution process.

Creation: Design documents are created from the template doc/dev/design/TEMPLATE.rst. While the design is still being discussed, it is in status WIP and linked in the section WIP. The document can be merged in this state as soon as the proposal is accepted, even if it still needs more work.

Once discussion on the design converges and the design document is finalized, its status becomes one of Active, Postponed, or Rejected and it is inserted to the corresponding section.
Implementation: Together with the implementation of the change, user manuals and any other documentation are updated.

The design document is only updated if amendments to the described design are found to be necessary during this phase.
Completion and Freeze: Once all parts of the implementation are completed, the design document is marked as Completed and linked to section Completed.

After this point, the design document is frozen as historical record and no longer updated. Later substantial changes undergo the entire process again, creating new design documents where appropriate.

During implementation the design may also become suspended (Postponed) or abandoned (Rejected or Outdated).
Replacement: If the implementation has changed so much that a design document is no longer a useful reference for the current system, it’s status is changed to Outdated and it is linked to section Outdated.

Design Documents

WIP

Postponed

Active

Completed

Outdated

Rejected