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, macOS, and Linux builders (both
25``pyca/cryptography-manylinux1`` and ``pyca/cryptography-manylinux2010``) have
26the latest OpenSSL. If anything is out of date follow the instructions for
27upgrading 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