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