docs(contributing): add section on Design Documents

Author: carmstrong

CONTRIBUTING.md

@@ -44,14 +44,11 @@ This is a rough outline of what a contributor's workflow looks like:
 
 Thanks for your contributions!
 
-### Design Proposals
+### Design Documents
 
-When considering a design proposal, we are looking for:
-
-- A description of the problem this design proposal solves
-- A pull request that modifies the documentation, describing the feature you are proposing
-- Prefix your pull request with `Proposal:` in the title
-- Please review the existing Proposals before reporting a new one.
+Most substantial changes to Deis should follow a [Design Document](http://docs.deis.io/en/latest/contributing/design-documents/)
+describing the proposed changes and how they are tested and verified before they
+are accepted into the project.
 
 ### Commit Style Guideline
 

docs/contributing/design-documents.rst

@@ -0,0 +1,74 @@
+:title: Design Documents
+:description: Information necessary for a feature design document.
+
+.. _design-documents:
+
+Design Documents
+================
+
+Before submitting a pull request which will change the behavior of Deis significantly,
+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 :ref:`merge_approval` review process as final
+PRs 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 :ref:`standards` for more information on pull request and commit message formatting.

docs/contributing/hacking.rst

@@ -2,8 +2,8 @@
 
 .. _hacking:
 
-Hacking on Deis
-===============
+Development Environment
+=======================
 
 This document is for developers who are interested in working directly on the
 Deis codebase. In this guide, we walk you through the process of setting up

docs/contributing/index.rst

@@ -10,6 +10,7 @@ Contributing
 .. toctree::
 
     overview
+    design-documents
     hacking
     testing
     standards

docs/contributing/overview.rst

@@ -24,6 +24,8 @@ Contribute Code
 We are always looking for help improving the core framework, modules, tooling and test coverage.
 Interested in contributing code? Let’s chat in IRC. Make sure to check out issues tagged `easy-fix`_.
 
+When you're ready to begin writing code, review :ref:`design-documents` and :ref:`hacking`.
+
 Share your Experience
 ---------------------
 Interact with the community on our user mailing list or live in our IRC channel,

docs/contributing/standards.rst

@@ -4,19 +4,26 @@
 
 .. _standards:
 
-PR Checklist
-============
+Submitting a Pull Request
+=========================
 
 Proposed changes to Deis are made as GitHub `pull requests`_.
 
 Please make sure your PR follows this checklist:
 
-1. `Single Issue`_
-2. `Include Tests`_
-3. `Include Docs`_
-4. `Code Standards`_
-5. `Commit Style`_
+1. `Design Document`_
+2. `Single Issue`_
+3. `Include Tests`_
+4. `Include Docs`_
+5. `Code Standards`_
+6. `Commit Style`_
 
+Design Document
+---------------
+
+Before opening a pull request, ensure your change also references a design
+document if the contribution is substantial. For more information, see
+:ref:`design-documents`.
 
 Single Issue
 ------------
@@ -82,18 +89,6 @@ the exception that lines of code may be up to 99 characters long. Docstrings and
 tests are required for all public methods, although the flake8_ tool used by
 Deis does not enforce this.
 
-
-Design Proposals
-----------------
-
-When considering a design proposal, we are looking for:
-
-- A description of the problem this design proposal solves
-- A pull request that modifies the documentation, describing the feature you are proposing
-- Prefix your pull request with ``Proposal:`` in the title
-- Please review the existing Proposals before reporting a new one.
-
-
 .. _commit_style_guide:
 
 Commit Style