Laurens Van Houtven | 5a42298 | 2014-03-15 21:42:31 +0100 | [diff] [blame] | 1 | Contributing |
| 2 | ============ |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 3 | |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 4 | First of all, thank you for your interest in contributing to pyOpenSSL! |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 5 | This project has no company backing its development therefore we're dependent on help by the community. |
| 6 | |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 7 | |
Laurens Van Houtven | 5a42298 | 2014-03-15 21:42:31 +0100 | [diff] [blame] | 8 | Filing bug reports |
| 9 | ------------------ |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 10 | |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 11 | Bug reports are very welcome. |
Hynek Schlawack | 35147f0 | 2015-09-06 09:00:15 +0200 | [diff] [blame] | 12 | Please file them on the `GitHub issue tracker`_. |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 13 | Good bug reports come with extensive descriptions of the error and how to reproduce it. |
Jean-Paul Calderone | 0679a69 | 2014-03-16 10:17:09 -0400 | [diff] [blame] | 14 | Reporters are strongly encouraged to include an `short, self contained, correct example <http://www.sscce.org/>`_. |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 15 | |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 16 | |
Laurens Van Houtven | 5a42298 | 2014-03-15 21:42:31 +0100 | [diff] [blame] | 17 | Patches |
| 18 | ------- |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 19 | |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 20 | All patches to pyOpenSSL should be submitted in the form of pull requests to the main pyOpenSSL repository, `pyca/pyopenssl`_. |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 21 | These pull requests should satisfy the following properties: |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 22 | |
Hynek Schlawack | a2995a1 | 2015-10-28 12:14:57 +0100 | [diff] [blame] | 23 | |
| 24 | Code |
| 25 | ^^^^ |
| 26 | |
Hynek Schlawack | 35147f0 | 2015-09-06 09:00:15 +0200 | [diff] [blame] | 27 | - The pull request should focus on one particular improvement to pyOpenSSL. |
| 28 | Create different pull requests for unrelated features or bugfixes. |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 29 | - Code should follow `PEP 8`_, especially in the "do what code around you does" sense. |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 30 | Follow OpenSSL naming for callables whenever possible is preferred. |
Jean-Paul Calderone | 0679a69 | 2014-03-16 10:17:09 -0400 | [diff] [blame] | 31 | - Pull requests that introduce code must test all new behavior they introduce as well as for previously untested or poorly tested behavior that they touch. |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 32 | - Pull requests are not allowed to break existing tests. |
Hynek Schlawack | 35147f0 | 2015-09-06 09:00:15 +0200 | [diff] [blame] | 33 | We usually don't comment on pull requests that are breaking the CI because we consider them work in progress. |
| 34 | Please note that not having 100% code coverage for the code you wrote/touched also causes our CI to fail. |
Hynek Schlawack | a2995a1 | 2015-10-28 12:14:57 +0100 | [diff] [blame] | 35 | |
| 36 | |
| 37 | Documentation |
| 38 | ^^^^^^^^^^^^^ |
| 39 | |
| 40 | When introducing new functionality, please remember to write documentation. |
| 41 | |
| 42 | - New functions and methods should have a docstring describing what they do, what parameters they takes, what types those parameters are, and what they return. |
| 43 | |
| 44 | .. code-block:: python |
| 45 | |
| 46 | def dump_publickey(type, pkey): |
| 47 | """ |
| 48 | Dump a public key to a buffer. |
| 49 | |
| 50 | :param type: The file type (one of :data:`FILETYPE_PEM` or |
| 51 | :data:`FILETYPE_ASN1`). |
| 52 | :param PKey pkey: The PKey to dump. |
| 53 | |
| 54 | :return: The buffer with the dumped key in it. |
| 55 | :rtype: bytes |
| 56 | """ |
| 57 | |
| 58 | |
| 59 | Don't forget to add an ``.. auto(function|class|method)::`` statement to the relevant API document found in ``doc/api/`` to actually add your function to the Sphinx documentation. |
| 60 | - Do *not* use ``:py:`` prefixes when cross-linking (Python is default). |
| 61 | Do *not* use the generic ``:data:`` or ``:obj:``. |
| 62 | Instead use more specific types like ``:class:``, ``:func:`` or ``:meth:`` if applicable. |
| 63 | - Pull requests that introduce features or fix bugs should note those changes in the CHANGELOG.rst_ file. |
| 64 | Please add new entries to the *top* of the *current* Changes section followed by a line linking to the relevant pull request: |
| 65 | |
| 66 | .. code-block:: rst |
| 67 | |
Hynek Schlawack | 65e4def | 2016-03-13 15:07:52 +0100 | [diff] [blame] | 68 | - Added ``OpenSSL.crypto.some_func()`` to do something awesome. |
Hynek Schlawack | a2995a1 | 2015-10-28 12:14:57 +0100 | [diff] [blame] | 69 | [`#1 <https://github.com/pyca/pyopenssl/pull/1>`_] |
| 70 | |
| 71 | |
| 72 | - Use `semantic newlines`_ in reStructuredText_ files (files ending in ``.rst``). |
| 73 | |
| 74 | |
| 75 | Review |
| 76 | ------ |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 77 | |
Laurens Van Houtven | 36a2665 | 2014-03-15 21:52:25 +0100 | [diff] [blame] | 78 | Finally, pull requests must be reviewed before merging. |
| 79 | This process mirrors the `cryptography code review process`_. |
| 80 | Everyone can perform reviews; this is a very valuable way to contribute, and is highly encouraged. |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 81 | |
Hynek Schlawack | 8f4eeb5 | 2015-09-06 15:12:40 +0200 | [diff] [blame] | 82 | Pull requests are merged by `members of PyCA`_. |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 83 | They should, of course, keep all the requirements detailed in this document as well as the ``pyca/cryptography`` merge requirements in mind. |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 84 | |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 85 | The final responsibility for the reviewing of merged code lies with the person merging it. |
| 86 | Since pyOpenSSL is a sensitive project from a security perspective, reviewers are strongly encouraged to take this review and merge process very seriously. |
Laurens Van Houtven | 290aba1 | 2014-03-14 15:20:18 +0100 | [diff] [blame] | 87 | |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 88 | |
| 89 | Finding Help |
| 90 | ------------ |
| 91 | |
| 92 | If you need any help with the contribution process, you'll find us hanging out at ``#cryptography-dev`` on Freenode_ IRC. |
| 93 | You can also ask questions on our `mailing list`_. |
| 94 | |
Hynek Schlawack | 238effd | 2016-03-17 14:06:35 +0100 | [diff] [blame] | 95 | Please note that this project is released with a Contributor `Code of Conduct`_. |
| 96 | By participating in this project you agree to abide by its terms. |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 97 | |
| 98 | |
Hynek Schlawack | 105bfb7 | 2015-10-28 12:16:40 +0100 | [diff] [blame] | 99 | Security |
| 100 | -------- |
| 101 | |
| 102 | If you feel that you found a security-relevant bug that you would prefer to discuss in private, please send us a GPG_-encrypted e-mail. |
| 103 | |
| 104 | The maintainer can be reached at hs@ox.cx and his GPG key ID is ``0xAE2536227F69F181`` (Fingerprint: ``C2A0 4F86 ACE2 8ADC F817 DBB7 AE25 3622 7F69 F181``). |
| 105 | Feel free to cross-check this information with Keybase_. |
| 106 | |
| 107 | |
Hynek Schlawack | 35147f0 | 2015-09-06 09:00:15 +0200 | [diff] [blame] | 108 | .. _GitHub issue tracker: https://github.com/pyca/pyopenssl/issues |
Hynek Schlawack | 8d4f976 | 2016-03-19 08:15:03 +0100 | [diff] [blame] | 109 | .. _GPG: https://en.wikipedia.org/wiki/GNU_Privacy_Guard |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 110 | .. _Keybase: https://keybase.io/hynek |
| 111 | .. _pyca/pyopenssl: https://github.com/pyca/pyopenssl |
| 112 | .. _PEP 8: https://www.python.org/dev/peps/pep-0008/ |
Laurens Van Houtven | 5a42298 | 2014-03-15 21:42:31 +0100 | [diff] [blame] | 113 | .. _cryptography code review process: https://cryptography.io/en/latest/development/reviewing-patches/ |
Hynek Schlawack | 8fb864a | 2015-06-07 19:09:49 +0200 | [diff] [blame] | 114 | .. _freenode: https://freenode.net |
Hynek Schlawack | 35147f0 | 2015-09-06 09:00:15 +0200 | [diff] [blame] | 115 | .. _mailing list: https://mail.python.org/mailman/listinfo/cryptography-dev |
Hynek Schlawack | 8f4eeb5 | 2015-09-06 15:12:40 +0200 | [diff] [blame] | 116 | .. _members of PyCA: https://github.com/orgs/pyca/people |
Hynek Schlawack | a2995a1 | 2015-10-28 12:14:57 +0100 | [diff] [blame] | 117 | .. _semantic newlines: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ |
Hynek Schlawack | 8d4f976 | 2016-03-19 08:15:03 +0100 | [diff] [blame] | 118 | .. _reStructuredText: http://sphinx-doc.org/rest.html |
Hynek Schlawack | a2995a1 | 2015-10-28 12:14:57 +0100 | [diff] [blame] | 119 | .. _CHANGELOG.rst: https://github.com/pyca/pyopenssl/blob/master/CHANGELOG.rst |
Hynek Schlawack | 238effd | 2016-03-17 14:06:35 +0100 | [diff] [blame] | 120 | .. _`Code of Conduct`: https://github.com/pyca/pyopenssl/blob/master/CODE_OF_CONDUCT.rst |