doing-a-release.rst 3.7 KB

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