From 953ebf8ab4b14c96ce921caea6a619dbf69dfa77 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 8 Dec 2013 10:28:30 -0800 Subject: Improved the docs -- more glossary entries, more advice for writing docs --- docs/contributing.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 97f31e0b..4647818a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -141,6 +141,9 @@ should begin with the "Hazardous Materials" warning: .. hazmat:: +When referring to a hypothetical individual (such as "a person receiving an +encrypted message") use gender neutral pronouns (they/them/their). + Development Environment ----------------------- -- cgit v1.2.3 From 5246e2db3100160b948a632e810010e1b23a9e91 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 12:23:18 -0800 Subject: Fixed headers in docs --- docs/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 4647818a..934bb45a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -48,7 +48,7 @@ Additionally, every Python code file must contain 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. @@ -161,7 +161,7 @@ dependencies, install ``cryptography`` in ``editable`` mode. For example: 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 @@ -195,7 +195,7 @@ 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`_. -- cgit v1.2.3 From e21b0b25bdda1eaa5a29aa585dd858bd21ff1016 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 12:39:05 -0800 Subject: Several policy reccomendations for API design --- docs/contributing.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 934bb45a..09833ed3 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -47,6 +47,40 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function +API Considerations +~~~~~~~~~~~~~~~~~~ + +Most projects' APIs are designed with a philosophy of "make easy things easy, +and make hard things possible". One of the perils of writing cryptographic code +is that code that is secure looks just like code that isn't, and produces +results that are also difficult to distinguish. As a result ``cryptography`` +has, as a design philosophy: "make it hard to do insecure things". Here are a +few strategies for API design which should be both followed, and should inspire +other API choices: + +If it is incorrect to ignore the result of a method, it should raise an +exception, and not return a boolean ``True``/``False`` flag. For example, a +method to verify a signature should raise ``InvalidSignature``, and not return +whether the signature was valid. + +.. code-block:: python + + # This is bad. + def verify(sig): + # ... + return is_valid + + # Good! + def verify(sig): + # ... + if not is_valid: + raise InvalidSignature + +APIs at the :doc:`/hazmat/primitives/index` layer should always take an +explicit backend, APIs at the recipes layer should automatically use the +:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow +specifiying a different backend. + C bindings ~~~~~~~~~~ -- cgit v1.2.3 From 2a5b4a8aafcfa3122c366c4415294eca9ad8de7f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 17:53:08 -0800 Subject: Fixed a mis-spelled word --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 09833ed3..100f13f5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -79,7 +79,7 @@ whether the signature was valid. APIs at the :doc:`/hazmat/primitives/index` layer should always take an explicit backend, APIs at the recipes layer should automatically use the :func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow -specifiying a different backend. +specifying a different backend. C bindings ~~~~~~~~~~ -- cgit v1.2.3 From f3f0018fb956dcc075798bd3d2eb49916471f23c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 19:22:33 -0800 Subject: Document the need for test coverage --- docs/contributing.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 100f13f5..a8010a9a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -28,6 +28,7 @@ devastating, ``cryptography`` has a strict code review policy: * 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. +* All merged patches must have 100% test coverage. The purpose of these policies is to minimize the chances we merge a change which jeopardizes our users' security. -- cgit v1.2.3 From f8796b15a279db82cdefcd00bebfef4cdef8fee8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 20:28:55 -0800 Subject: Renamed bindings to backends --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index a8010a9a..cb9c7283 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -79,7 +79,7 @@ whether the signature was valid. APIs at the :doc:`/hazmat/primitives/index` layer should always take an explicit backend, APIs at the recipes layer should automatically use the -:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow +:func:`~cryptography.hazmat.backends.default_backend`, but optionally allow specifying a different backend. C bindings -- cgit v1.2.3