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

     1  :title: Coding Standards
     2  :description: How to propose changes to the Deis codebase.
     3  
     4  
     5  .. _standards:
     6  
     7  Submitting a Pull Request
     8  =========================
     9  
    10  Proposed changes to Deis are made as GitHub `pull requests`_.
    11  
    12  Please make sure your PR follows this checklist:
    13  
    14  1. `Design Document`_
    15  2. `Single Issue`_
    16  3. `Include Tests`_
    17  4. `Include Docs`_
    18  5. `Code Standards`_
    19  6. `Commit Style`_
    20  
    21  Design Document
    22  ---------------
    23  
    24  Before opening a pull request, ensure your change also references a design
    25  document if the contribution is substantial. For more information, see
    26  :ref:`design-documents`.
    27  
    28  Single Issue
    29  ------------
    30  
    31  When fixing or implementing a GitHub issue, resist the temptation to refactor
    32  nearby code or to fix that potential bug you noticed. Instead, open a new
    33  `pull request`_ just for that change.
    34  
    35  It's hard to reach agreement on the merit of a PR when it isn't focused. Keeping
    36  concerns separated allows pull requests to be tested, reviewed, and merged
    37  more quickly.
    38  
    39  Squash and rebase the commit or commits in your pull request into logical units
    40  of work with ``git``. Include tests and documentation changes in the same commit,
    41  so that a revert would remove all traces of the feature or fix.
    42  
    43  Most pull requests will reference a `GitHub issue`_. In the PR description--not
    44  in the commit itself--include a line such as "Closes #1234." The issue referenced
    45  will then be closed when your PR is merged.
    46  
    47  
    48  Include Tests
    49  -------------
    50  
    51  If you change or add functionality to any Deis code, your changes should include
    52  the necessary tests to prove that it works. Unit tests may be written with the
    53  component's implementation language (usually Go or Python), and functional and
    54  integration tests are written in Go. Test code can be found in the ``tests/``
    55  directory of the Deis project.
    56  
    57  While working on local code changes, always run the tests.  Be sure your
    58  proposed changes pass all of ``./tests/bin/test-integration`` on your
    59  workstation before submitting a PR.
    60  
    61  See :ref:`testing` for more information.
    62  
    63  
    64  Include Docs
    65  ------------
    66  
    67  Any change to Deis that could affect a user's experience also needs a change or
    68  addition to the relevant documentation. Deis generates the HTML documentation
    69  hosted at http://docs.deis.io/ from the text markup sources in the
    70  ``docs/`` directory.
    71  
    72  See ``docs/README.md`` in the code for more information.
    73  
    74  
    75  Code Standards
    76  --------------
    77  
    78  Deis is a Go_ and Python_ project. For both languages, we agree with
    79  `The Zen of Python`_, which emphasizes simple over clever. Readability counts.
    80  
    81  Go code should always be run through ``gofmt`` on the default settings. Lines
    82  of code may be up to 99 characters long. Documentation strings and tests are
    83  required for all public methods. Use of third-party go packages should be
    84  minimal, but when doing so, vendor code into the Deis package with the
    85  godep_ tool.
    86  
    87  Python code should always adhere to PEP8_, the python code style guide, with
    88  the exception that lines of code may be up to 99 characters long. Docstrings and
    89  tests are required for all public methods, although the flake8_ tool used by
    90  Deis does not enforce this.
    91  
    92  .. _commit_style_guide:
    93  
    94  Commit Style
    95  ------------
    96  
    97  ``git commit`` messages must follow this format::
    98  
    99      {type}({scope}): {subject}
   100      <BLANK LINE>
   101      {body}
   102      <BLANK LINE>
   103      {footer}
   104  
   105  Example
   106  """""""
   107  
   108  ::
   109  
   110      feat(logger): add frobnitz pipeline spout discovery
   111  
   112      Introduces a FPSD component compatible with the industry standard for
   113      spout discovery.
   114  
   115      BREAKING CHANGE: Fixing the buffer overflow in the master subroutine
   116          required losing compatibility with the UVEX-9. Any UVEX-9 or
   117          umVEX-8 series artifacts will need to be updated to umVX format
   118          with the consortium or vendor toolset.
   119  
   120  .. note::
   121  
   122    You can install a git hook that checks your commit message format with ``make commit-hook``
   123  
   124  Subject Line
   125  """"""""""""
   126  
   127  The first line of a commit message is its subject. It contains a brief
   128  description of the change, no longer than 50 characters.
   129  
   130  These {types} are allowed:
   131  
   132  - **feat** -> feature
   133  - **fix** -> bug fix
   134  - **docs** -> documentation
   135  - **style** -> formatting
   136  - **ref** -> refactoring code
   137  - **test** -> adding missing tests
   138  - **chore** -> maintenance
   139  
   140  The {scope} specifies the location of the change, such as "controller,"
   141  "Dockerfiles," or ".gitignore". The {subject} should use an imperative,
   142  present-tense verb: "change," not "changes" or "changed." Don't
   143  capitalize the verb or add a period (.) at the end of the subject line.
   144  
   145  Message Body
   146  """"""""""""
   147  
   148  Separate the message body from the subject with a blank line. The body
   149  can have lines up to 72 characters long. It includes the motivation for the
   150  change and points out differences from previous behavior. The body and
   151  the footer should be written as full sentences.
   152  
   153  Message Footer
   154  """"""""""""""
   155  
   156  Separate a footer from the message body with a blank line. Mention any
   157  breaking change along with the justification and migration notes. If the
   158  changes cannot be tested by Deis' test scripts, include specific instructions
   159  for manual testing.
   160  
   161  
   162  .. _merge_approval:
   163  
   164  Merge Approval
   165  --------------
   166  
   167  Deis maintainers add "**LGTM**" (Looks Good To Me) or an equivalent comment
   168  to indicate that a PR is acceptable. Any code change--other than
   169  a simple typo fix or one-line documentation change--requires at least two
   170  maintainers to accept it.
   171  
   172  No pull requests can be merged until at least one core maintainer_ signs off
   173  with an LGTM. The other LGTM can come from either a core maintainer or
   174  contributing maintainer.
   175  
   176  If the PR is from a Deis maintainer, then he or she should be the one to close
   177  it. This keeps the commit stream clean and gives the maintainer the benefit of
   178  revisiting the PR before deciding whether or not to merge the changes.
   179  
   180  
   181  .. _Python: http://www.python.org/
   182  .. _Go: http://golang.org/
   183  .. _godep: https://github.com/tools/godep
   184  .. _flake8: https://pypi.python.org/pypi/flake8/
   185  .. _PEP8: http://www.python.org/dev/peps/pep-0008/
   186  .. _`The Zen of Python`: http://www.python.org/dev/peps/pep-0020/
   187  .. _`pull request`: https://github.com/deis/deis/pulls
   188  .. _`pull requests`: https://github.com/deis/deis/pulls
   189  .. _`GitHub issue`: https://github.com/deis/deis/issues
   190  .. _maintainer: https://github.com/deis/deis/blob/master/MAINTAINERS.md