github.com/technosophos/deis@v1.7.1-0.20150915173815-f9005256004b/docs/contributing/design-documents.rst (about)

     1  :title: Design Documents
     2  :description: Information necessary for a feature design document.
     3  
     4  .. _design-documents:
     5  
     6  Design Documents
     7  ================
     8  
     9  Before submitting a pull request which will change the behavior of Deis significantly,
    10  such as a new feature or major refactoring, contributors should first open
    11  an issue representing a design document.
    12  
    13  Goals
    14  -----
    15  
    16  Design documents help ensure project contributors:
    17  
    18  * Involve stakeholders as early as possible in a feature's development
    19  * Ensure code changes accomplish the original motivations and design goals
    20  * Establish clear acceptance criteria for a feature or change
    21  * Enforce test-driven design methodology and automated test coverage
    22  
    23  Contents
    24  --------
    25  
    26  Design document issues should be named ``Design Doc: <change description>`` and
    27  contain the following sections.
    28  
    29  Goal
    30  ^^^^
    31  
    32  This section should briefly describe the proposed change and the motivations
    33  behind it. Tests will be written to ensure this design goal is met by
    34  the change.
    35  
    36  This section should also reference a separate GitHub issue tracking
    37  the feature or change, which will typically be assigned to a release milestone.
    38  
    39  Code Changes
    40  ^^^^^^^^^^^^
    41  
    42  This section should detail the code changes necessary to accomplish the change,
    43  as well as the proposed implementation. This should be as detailed as necessary to
    44  help reviewers understand the change.
    45  
    46  Tests
    47  ^^^^^
    48  
    49  All changes should be covered by automated tests, either unit or integration tests
    50  (ideally both). This section should detail how tests will be written to validate
    51  that the change accomplishes the design goals and doesn't introduce any regressions.
    52  
    53  If a change cannot be sufficiently covered by automated testing, the design
    54  should be reconsidered. If there is no test coverage whatsoever for an affected
    55  section of code, a separate issue should be filed to integrate automated testing
    56  with that section of the codebase.
    57  
    58  The tests described here also form the acceptance criteria for the change, so
    59  that when it's completed maintainers can merge the pull request after confirming
    60  the tests pass CI.
    61  
    62  Approval
    63  --------
    64  
    65  A design document follows the same :ref:`merge_approval` review process as final
    66  PRs do, and maintainers will take extra care to ensure that any stakeholders for
    67  the change are included in the discussion and review of the design document.
    68  
    69  Once the design is accepted, the author can complete the change and submit a pull
    70  request for review. The pull request should close both the design document for
    71  the change as well as any issues that either track the issue or are closed as a
    72  result of the change.
    73  
    74  See :ref:`standards` for more information on pull request and commit message formatting.