1Submitting patches
2==================
3
4* Always make a new branch for your work.
5* Patches should be small to facilitate easier review. `Studies have shown`_
6  that review quality falls off as patch size grows. Sometimes this will result
7  in many small PRs to land a single large feature.
8* Larger changes should be discussed in a ticket before submission.
9* New features and significant bug fixes should be documented in the
10  :doc:`/changelog`.
11* You must have legal permission to distribute any code you contribute and it
12  must be available under both the BSD and Apache Software License Version 2.0
13  licenses.
14
15If you believe you've identified a security issue in packaging, please
16follow the directions on the :doc:`security page </security>`.
17
18Code
19----
20
21This project's source is auto-formatted with |black|. You can check if your
22code meets our requirements by running our linters against it with ``nox -s
23lint`` or ``pre-commit run --all-files``.
24
25`Write comments as complete sentences.`_
26
27Every code file must start with the boilerplate licensing notice:
28
29.. code-block:: python
30
31    # This file is dual licensed under the terms of the Apache License, Version
32    # 2.0, and the BSD License. See the LICENSE file in the root of this repository
33    # for complete details.
34
35Additionally, every Python code file must contain
36
37.. code-block:: python
38
39    from __future__ import absolute_import, division, print_function
40
41
42Tests
43-----
44
45All code changes must be accompanied by unit tests with 100% code coverage (as
46measured by the combined metrics across our build matrix).
47
48
49Documentation
50-------------
51
52All features should be documented with prose in the ``docs`` section.
53
54When referring to a hypothetical individual (such as "a person receiving an
55encrypted message") use gender neutral pronouns (they/them/their).
56
57Docstrings are typically only used when writing abstract classes, but should
58be written like this if required:
59
60.. code-block:: python
61
62    def some_function(some_arg):
63        """
64        Does some things.
65
66        :param some_arg: Some argument.
67        """
68
69So, specifically:
70
71* Always use three double quotes.
72* Put the three double quotes on their own line.
73* No blank line at the end.
74* Use Sphinx parameter/attribute documentation `syntax`_.
75
76
77.. |black| replace:: ``black``
78.. _black: https://pypi.org/project/black/
79.. _`Write comments as complete sentences.`: https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html
80.. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists
81.. _`Studies have shown`: http://www.ibm.com/developerworks/rational/library/11-proven-practices-for-peer-review/
82