1Doing a release 2=============== 3 4Doing a release of ``cryptography`` requires a few steps. 5 6Security Releases 7----------------- 8 9In addition to the other steps described below, for a release which fixes a 10security vulnerability, you should also include the following steps: 11 12* Request a `CVE from MITRE`_. Once you have received the CVE, it should be 13 included in the :doc:`changelog`. Ideally you should request the CVE before 14 starting the release process so that the CVE is available at the time of the 15 release. 16* Ensure that the :doc:`changelog` entry credits whoever reported the issue. 17* The release should be announced on the `oss-security`_ mailing list, in 18 addition to the regular announcement lists. 19 20Verifying OpenSSL version 21------------------------- 22 23The release process creates wheels bundling OpenSSL for Windows, macOS, and 24Linux. Check that the Windows and macOS Jenkins builders have the latest 25version of OpenSSL installed and verify that the latest version is present in 26the ``pyca/cryptography-manylinux1`` docker containers. If anything is out 27of date follow the instructions for upgrading OpenSSL. 28 29Upgrading OpenSSL 30----------------- 31 32Use the `upgrading OpenSSL issue template`_. 33 34Bumping the version number 35-------------------------- 36 37The next step in doing a release is bumping the version number in the 38software. 39 40* Update the version number in ``src/cryptography/__about__.py``. 41* Update the version number in ``vectors/cryptography_vectors/__about__.py``. 42* Set the release date in the :doc:`/changelog`. 43* Do a commit indicating this. 44* Send a pull request with this. 45* Wait for it to be merged. 46 47Performing the release 48---------------------- 49 50The commit that merged the version number bump is now the official release 51commit for this release. You will need to have ``gpg`` installed and a ``gpg`` 52key in order to do a release. Once this has happened: 53 54* Run ``python release.py {version}``. 55 56The release should now be available on PyPI and a tag should be available in 57the repository. 58 59Verifying the release 60--------------------- 61 62You should verify that ``pip install cryptography`` works correctly: 63 64.. code-block:: pycon 65 66 >>> import cryptography 67 >>> cryptography.__version__ 68 '...' 69 >>> import cryptography_vectors 70 >>> cryptography_vectors.__version__ 71 '...' 72 73Verify that this is the version you just released. 74 75For the Windows wheels check the builds for the ``cryptography-wheel-builder`` 76job and verify that the final output for each build shows it loaded and linked 77the expected OpenSSL version. 78 79Post-release tasks 80------------------ 81 82* Update the version number to the next major (e.g. ``0.5.dev1``) in 83 ``src/cryptography/__about__.py`` and 84 ``vectors/cryptography_vectors/__about__.py``. 85* Close the `milestone`_ for the previous release on GitHub. 86* Add new :doc:`/changelog` entry with next version and note that it is under 87 active development 88* Send a pull request with these items 89* Check for any outstanding code undergoing a deprecation cycle by looking in 90 ``cryptography.utils`` for ``DeprecatedIn**`` definitions. If any exist open 91 a ticket to increment them for the next release. 92* Send an email to the `mailing list`_ and `python-announce`_ announcing the 93 release. 94 95.. _`CVE from MITRE`: https://cveform.mitre.org/ 96.. _`oss-security`: https://www.openwall.com/lists/oss-security/ 97.. _`upgrading OpenSSL issue template`: https://github.com/pyca/cryptography/issues/new?template=openssl-release.md 98.. _`milestone`: https://github.com/pyca/cryptography/milestones 99.. _`mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev 100.. _`python-announce`: https://mail.python.org/mailman/listinfo/python-announce-list 101