1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
Contributing
============
Process
-------
As an open source project, ``cryptography`` welcomes contributions of all
forms. These can include:
* Bug reports and feature requests
* Pull requests for both code and documentation
* Patch reviews
You can file bugs and submit pull requests on `GitHub`_. To discuss larger
changes you can start a conversation on `our mailing list`_.
Because cryptography is so complex, and the implications of getting it wrong so
devastating, ``cryptography`` has a strict code review policy:
* Patches must *never* be pushed directly to ``master``, all changes (even the
most trivial typo fixes!) must be submitted as a pull request.
* A committer may *never* merge their own pull request, a second party must
merge their changes. If multiple people work on a pull request, it must be
merged by someone who did not work on it.
* A patch which breaks tests, or introduces regressions by changing or removing
existing tests should not be merged. Tests must always be passing on
``master``.
* If somehow the tests get into a failing state on ``master`` (such as by a
backwards incompatible release of a dependency) no pull requests may be
merged until this is rectified.
The purpose of these policies is to minimize the chances we merge a change
which jeopardizes our users' security.
If you believe you've identified a security issue in ``cryptography``, please
follow the directions on the :doc:`security page </security>`.
Code
----
When in doubt, refer to `PEP 8`_ for Python code.
Every code file must start with the boilerplate notice of the Apache License.
Additionally, every Python code file must contain
.. code-block:: python
from __future__ import absolute_import, division, print_function
C bindings
----------
When binding C code with ``cffi`` we have our own style guide, it's pretty
simple.
Don't name parameters:
.. code-block:: c
// Good
long f(long);
// Bad
long f(long x);
...unless they're inside a struct:
.. code-block:: c
struct my_struct {
char *name;
int number;
...;
};
Don't include stray ``void`` parameters:
.. code-block:: c
// Good
long f();
// Bad
long f(void);
Wrap lines at 80 characters like so:
.. code-block:: c
// Pretend this went to 80 characters
long f(long, long,
int *)
Include a space after commas between parameters:
.. code-block:: c
// Good
long f(int, char *)
// Bad
long f(int,char *)
Documentation
-------------
All features should be documented with prose.
Docstrings should be written like this:
.. code-block:: python
def some_function(some_arg):
"""
Does some things.
:param some_arg: Some argument.
"""
So, specifically:
* Always use three double quotes.
* Put the three double quotes on their own line.
* No blank line at the end.
* Use Sphinx parameter/attribute documentation `syntax`_.
When documenting a new module in the ``hazmat`` package, its documentation
should begin with the "Hazardous Materials" warning:
.. code-block:: rest
.. hazmat::
Development Environment
-----------------------
Working on ``cryptography`` requires the installation of a small number of
development dependencies. These are listed in ``dev-requirements.txt`` and they
can be installed in a `virtualenv`_ using `pip`_. Once you've installed the
dependencies, install ``cryptography`` in ``editable`` mode. For example:
.. code-block:: console
$ # Create a virtualenv and activate it
$ pip install --requirement dev-requirements.txt
$ pip install --editable .
You are now ready to run the tests and build the documentation.
Running Tests
-------------
``cryptography`` unit tests are found in the ``tests/`` directory and are
designed to be run using `pytest`_. `pytest`_ will discover the tests
automatically, so all you have to do is:
.. code-block:: console
$ py.test
...
4294 passed in 15.24 seconds
This runs the tests with the default Python interpreter.
You can also verify that the tests pass on other supported Python interpreters.
For this we use `tox`_, which will automatically create a `virtualenv`_ for
each supported Python version and run the tests. For example:
.. code-block:: console
$ tox
...
ERROR: py26: InterpreterNotFound: python2.6
py27: commands succeeded
ERROR: pypy: InterpreterNotFound: pypy
ERROR: py32: InterpreterNotFound: python3.2
py33: commands succeeded
docs: commands succeeded
pep8: commands succeeded
You may not have all the required Python versions installed, in which case you
will see one or more ``InterpreterNotFound`` errors.
Building Documentation
----------------------
``cryptography`` documentation is stored in the ``docs/`` directory. It is
written in `reStructured Text`_ and rendered using `Sphinx`_.
Use `tox`_ to build the documentation. For example:
.. code-block:: console
$ tox -e docs
...
docs: commands succeeded
congratulations :)
The HTML documentation index can now be found at ``docs/_build/html/index.html``
.. _`GitHub`: https://github.com/pyca/cryptography
.. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
.. _`PEP 8`: http://www.peps.io/8/
.. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists
.. _`pytest`: https://pypi.python.org/pypi/pytest
.. _`tox`: https://pypi.python.org/pypi/tox
.. _`virtualenv`: https://pypi.python.org/pypi/virtualenv
.. _`pip`: https://pypi.python.org/pypi/pip
.. _`sphinx`: https://pypi.python.org/pypi/sphinx
.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
|
