1Contributing 2============ 3 4First of all, thank you for your interest in contributing to pyOpenSSL! 5This project has no company backing its development therefore we're dependent on help by the community. 6 7 8Filing bug reports 9------------------ 10 11Bug reports are very welcome. 12Please file them on the `GitHub issue tracker`_. 13Good bug reports come with extensive descriptions of the error and how to reproduce it. 14Reporters are strongly encouraged to include an `short, self contained, correct example <http://www.sscce.org/>`_. 15 16 17Patches 18------- 19 20All patches to pyOpenSSL should be submitted in the form of pull requests to the main pyOpenSSL repository, `pyca/pyopenssl`_. 21These pull requests should satisfy the following properties: 22 23 24Code 25^^^^ 26 27- The pull request should focus on one particular improvement to pyOpenSSL. 28 Create different pull requests for unrelated features or bugfixes. 29- Code should follow `PEP 8`_, especially in the "do what code around you does" sense. 30 Follow OpenSSL naming for callables whenever possible is preferred. 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. 32- Pull requests are not allowed to break existing tests. 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. 35 36 37Documentation 38^^^^^^^^^^^^^ 39 40When 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 68 - Added ``OpenSSL.crypto.some_func()`` to do something awesome. 69 [`#1 <https://github.com/pyca/pyopenssl/pull/1>`_] 70 71 72- Use `semantic newlines`_ in reStructuredText_ files (files ending in ``.rst``). 73 74 75Review 76------ 77 78Finally, pull requests must be reviewed before merging. 79This process mirrors the `cryptography code review process`_. 80Everyone can perform reviews; this is a very valuable way to contribute, and is highly encouraged. 81 82Pull requests are merged by `members of PyCA`_. 83They should, of course, keep all the requirements detailed in this document as well as the ``pyca/cryptography`` merge requirements in mind. 84 85The final responsibility for the reviewing of merged code lies with the person merging it. 86Since pyOpenSSL is a sensitive project from a security perspective, reviewers are strongly encouraged to take this review and merge process very seriously. 87 88 89Finding Help 90------------ 91 92If you need any help with the contribution process, you'll find us hanging out at ``#cryptography-dev`` on Freenode_ IRC. 93You can also ask questions on our `mailing list`_. 94 95Please note that this project is released with a Contributor `Code of Conduct`_. 96By participating in this project you agree to abide by its terms. 97 98 99Security 100-------- 101 102If 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 104The 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``). 105Feel free to cross-check this information with Keybase_. 106 107 108.. _GitHub issue tracker: https://github.com/pyca/pyopenssl/issues 109.. _GPG: https://en.wikipedia.org/wiki/GNU_Privacy_Guard 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/ 113.. _cryptography code review process: https://cryptography.io/en/latest/development/reviewing-patches/ 114.. _freenode: https://freenode.net 115.. _mailing list: https://mail.python.org/mailman/listinfo/cryptography-dev 116.. _members of PyCA: https://github.com/orgs/pyca/people 117.. _semantic newlines: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ 118.. _reStructuredText: http://sphinx-doc.org/rest.html 119.. _CHANGELOG.rst: https://github.com/pyca/pyopenssl/blob/master/CHANGELOG.rst 120.. _`Code of Conduct`: https://github.com/pyca/pyopenssl/blob/master/CODE_OF_CONDUCT.rst 121