From c72e63fc52edc73012e6958d6d587524f64a10be Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 9 Sep 2013 21:44:26 -0700 Subject: More fully document the contribution process, move most of the details from CONTRIBUTING.rst to sphinx. --- CONTRIBUTING.rst | 48 +++++++------------------------ docs/contributing.rst | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 91 insertions(+), 38 deletions(-) create mode 100644 docs/contributing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3ee89b80..9575e845 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,43 +1,15 @@ -Process -======= +Contributing to cryptography +============================ -This repository has a mandatory code review policy. Contributions -should happen through pull requests. Never commit to ``master`` -directly. +As an open source project, cryptography welcomes contributions of many forms. -Code -==== +Examples of contributions include: -When in doubt, refer to `PEP 8`_ for Python code. +* Code patches +* Documentation improvements +* Bug reports and patch reviews -Every code file must start with the boilerplate notice of the Apache License. -Additionally, every Python code file must contain +Extensive contribution guidelines are available in the repository at +``docs/contributing.rst``, or online at: -.. code-block:: python - - from __future__ import absolute_import, division, print_function - -Docs -==== - -Write docstrings 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`_. - - -.. _`PEP 8`: http://www.peps.io/8/ -.. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists +https://cryptography.readthedocs.org/en/latest/contributing/ diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..486149c1 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,80 @@ +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, the merger + may not be any of them. +* 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. + +We do not yet have a formal security contact. To report security issues in +``cryptography`` you should email ``alex.gaynor@gmail.com``, messages may be +encrypted with PGP to key fingerprint +``E27D 4AA0 1651 72CB C5D2 AF2B 125F 5C67 DFE9 4084`` (this public key is +available from most commonly-used keyservers). + +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 + +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`_. + + +.. _`Github`: https://github.com/alex/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 diff --git a/docs/index.rst b/docs/index.rst index 34996d7f..c8f63883 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,4 +32,5 @@ Contents architecture primitives/index + contributing community -- cgit v1.2.3 From 2c67c82b9674c87085d30e6127c863b4b2c29966 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 9 Sep 2013 23:44:13 -0700 Subject: Captitalize GH properly --- docs/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 486149c1..b4c72ba4 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -11,7 +11,7 @@ forms. These can include: * Pull requests for both code and documentation * Patch reviews -You can file bugs and submit pull requests on `Github`_. To discuss larger +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 @@ -74,7 +74,7 @@ So, specifically: - Use Sphinx parameter/attribute documentation `syntax`_. -.. _`Github`: https://github.com/alex/cryptography +.. _`GitHub`: https://github.com/alex/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 -- cgit v1.2.3 From 2354fcdcb46589eeba3fe0cfd25e3f2315b2b89f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 10 Sep 2013 19:15:36 -0500 Subject: changes to parameterize_encrypt_test to support other NIST vectors * ECB has no IV so we need to be able to pass params rather than have them hardcoded in the method --- tests/primitives/test_nist.py | 52 +++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/tests/primitives/test_nist.py b/tests/primitives/test_nist.py index 65d130ad..8bef118e 100644 --- a/tests/primitives/test_nist.py +++ b/tests/primitives/test_nist.py @@ -28,13 +28,13 @@ from cryptography.primitives.block import BlockCipher, ciphers, modes from ..utils import load_nist_vectors_from_file -def parameterize_encrypt_test(cipher, vector_type, fnames): - return pytest.mark.parametrize(("key", "iv", "plaintext", "ciphertext"), +def parameterize_encrypt_test(cipher, vector_type, params, fnames): + return pytest.mark.parametrize(params, list(itertools.chain.from_iterable( load_nist_vectors_from_file( os.path.join(cipher, vector_type, fname), "ENCRYPT", - ["key", "iv", "plaintext", "ciphertext"], + params ) for fname in fnames )) @@ -42,20 +42,24 @@ def parameterize_encrypt_test(cipher, vector_type, fnames): class TestAES_CBC(object): - @parameterize_encrypt_test("AES", "KAT", [ - "CBCGFSbox128.rsp", - "CBCGFSbox192.rsp", - "CBCGFSbox256.rsp", - "CBCKeySbox128.rsp", - "CBCKeySbox192.rsp", - "CBCKeySbox256.rsp", - "CBCVarKey128.rsp", - "CBCVarKey192.rsp", - "CBCVarKey256.rsp", - "CBCVarTxt128.rsp", - "CBCVarTxt192.rsp", - "CBCVarTxt256.rsp", - ]) + @parameterize_encrypt_test( + "AES", "KAT", + ("key", "iv", "plaintext", "ciphertext"), + [ + "CBCGFSbox128.rsp", + "CBCGFSbox192.rsp", + "CBCGFSbox256.rsp", + "CBCKeySbox128.rsp", + "CBCKeySbox192.rsp", + "CBCKeySbox256.rsp", + "CBCVarKey128.rsp", + "CBCVarKey192.rsp", + "CBCVarKey256.rsp", + "CBCVarTxt128.rsp", + "CBCVarTxt192.rsp", + "CBCVarTxt256.rsp", + ] + ) def test_KAT(self, key, iv, plaintext, ciphertext): cipher = BlockCipher( ciphers.AES(binascii.unhexlify(key)), @@ -65,11 +69,15 @@ class TestAES_CBC(object): actual_ciphertext += cipher.finalize() assert binascii.hexlify(actual_ciphertext) == ciphertext - @parameterize_encrypt_test("AES", "MMT", [ - "CBCMMT128.rsp", - "CBCMMT192.rsp", - "CBCMMT256.rsp", - ]) + @parameterize_encrypt_test( + "AES", "MMT", + ("key", "iv", "plaintext", "ciphertext"), + [ + "CBCMMT128.rsp", + "CBCMMT192.rsp", + "CBCMMT256.rsp", + ] + ) def test_MMT(self, key, iv, plaintext, ciphertext): cipher = BlockCipher( ciphers.AES(binascii.unhexlify(key)), -- cgit v1.2.3