Design Documents¶

Before submitting a pull request which will significantly alter the behavior of any Deis component, such as a new feature or major refactoring, contributors should first open an issue representing a design document.

Goals¶

Design documents help ensure project contributors:

• Involve stakeholders as early as possible in a feature's development
• Ensure code changes accomplish the original motivations and design goals
• Establish clear acceptance criteria for a feature or change
• Enforce test-driven design methodology and automated test coverage

Contents¶

Design document issues should be named Design Doc: <change description> and contain the following sections:

Goal¶

This section should briefly describe the proposed change and the motivations behind it. Tests will be written to ensure this design goal is met by the change.

This section should also reference a separate GitHub issue tracking the feature or change, which will typically be assigned to a release milestone.

Code Changes¶

This section should detail the code changes necessary to accomplish the change, as well as the proposed implementation. This should be as detailed as necessary to help reviewers understand the change.

Tests¶

All changes should be covered by automated tests, either unit or integration tests (ideally both). This section should detail how tests will be written to validate that the change accomplishes the design goals and doesn't introduce any regressions.

If a change cannot be sufficiently covered by automated testing, the design should be reconsidered. If there is no test coverage whatsoever for an affected section of code, a separate issue should be filed to integrate automated testing with that section of the codebase.

The tests described here also form the acceptance criteria for the change, so that when it's completed maintainers can merge the pull request after confirming the tests pass CI.

Approval¶

A design document follows the same merge approval review process as final pull requests do, and maintainers will take extra care to ensure that any stakeholders for the change are included in the discussion and review of the design document.

Once the design is accepted, the author can complete the change and submit a pull request for review. The pull request should close both the design document for the change as well as any issues that either track the issue or are closed as a result of the change.

See Submitting a Pull Request for more information on pull request and commit message formatting.