diff --git a/docs/contribute/maintenance.rst b/docs/contribute/maintenance.rst index f01bd1c7c..b9248f154 100644 --- a/docs/contribute/maintenance.rst +++ b/docs/contribute/maintenance.rst @@ -95,9 +95,11 @@ When doing so, you or the inviter may submit a pull request to update the :file: Release versions ---------------- -.. seealso:: +.. seealso:: :doc:`/reference/versions-branches` +.. _new-releases: + New releases ------------ @@ -117,13 +119,7 @@ However, only people with ``Environments/Configure PyPI`` access can approve an If there are any changes to the module, then open a pull request and merge it. -#. Determine the new version of icalendar. - - .. code-block:: shell - - make new-version - -#. Copy and paste the new version into an environment variable to use in subsequent commands during the release process. +#. Set an environment variable to use in subsequent commands during the release process. .. code-block:: shell @@ -176,12 +172,12 @@ However, only people with ``Environments/Configure PyPI`` access can approve an git add CHANGES.rst news/ docs/conf.py git add .github/workflows/tests.yml # Only for a new major release - git commit -m"version $VERSION" + git commit -m "version $VERSION" git push # to PyCalendar/icalendar -#. See if the `CI tests `_ are running on the commit. - If they are not running, no new release can be issued. - If the CI passes, go ahead. +#. Confirm the `CI tests `_ are running on the commit and pass before continuing. + No tag should be pushed until CI is green on the version commit. + If CI is not running, no release can be issued. #. Create a tag for the release on its release branch ``*.x``, push, and make sure the `CI tests`_ are running. @@ -227,7 +223,7 @@ However, only people with ``Environments/Configure PyPI`` access can approve an git push # to PyCalendar/icalendar - #. Next create a tag, and push the tag. + #. Next, create a tag, and push the tag. .. code-block:: shell @@ -240,7 +236,9 @@ However, only people with ``Environments/Configure PyPI`` access can approve an This creates issues for downstream repositories. See :issue:`1033`. -#. Once the tag is pushed and its `CI tests`_ pass, check the `GitHub Actions `_, and wait for maintainers to get an email: +#. Once the tag is pushed and its `CI tests`_ pass, check `GitHub Actions `_. + The ``deploy-tag-to-pypi`` and ``deploy-github-release`` jobs will wait for a manual approval. + Maintainers listed as Required Reviewers in :menuselection:`Settings --> Environments --> PyPI` will receive an email: .. code-block:: text @@ -248,8 +246,9 @@ However, only people with ``Environments/Configure PyPI`` access can approve an tests: PyPI is waiting for your review -#. If the release is approved by a maintainer, it will be pushed to `PyPI`_. - Don't wait for that, continue. + Approve the deployment in GitHub Actions. + PyPI publishing uses `Trusted Publishing (OIDC) `_; no API token is needed. + The approval window is 30 days; if it expires, push a new tag with a bumped version number. #. Update the version switcher file :file:`docs/_static/version-switcher.json`. @@ -342,7 +341,7 @@ However, only people with ``Environments/Configure PyPI`` access can approve an git push # to PyCalendar/icalendar #. If you cut a new *major* release version, update the Sphinx configuration file :file:`docs/conf.py` on the *previous* numbered major release branch to show the version warning banner. - For example, when releasing 7.0.0, checkout ``6.x``, and update it as shown. + For example, when releasing 7.0.0, check out ``6.x``, and update it as shown. .. code-block:: shell @@ -364,20 +363,146 @@ However, only people with ``Environments/Configure PyPI`` access can approve an #. Manually trigger the "latest" version on `Read the Docs `_. To the right in the row for "latest," click the ellipsis :guilabel:`…`, and from the pop-up menu select :guilabel:`Rebuild version`. +#. Advance the ``*.x`` stable branch to the new tag so it stays current for future backports. + + .. code-block:: shell + + git checkout 7.x + git pull + git merge main + git push # to PyCalendar/icalendar + + .. note:: + + If the stable branch is behind the latest tag, push it forward before starting any backport. + A branch that's out of date causes cherry-pick conflicts and forces a version bump. + #. Add a comment to each of the issues mentioned in the new release. - Example: .. code-block:: text This is included in v7.0.0. +.. _pre-releases: + +Pre-releases +------------ + +Pre-releases use `PEP 440 `_ suffixes: ``8.0.0a1``, ``8.0.0b1``, ``8.0.0rc1``. +The release steps are the same as a standard release, with these differences. + +The tag goes on ``main``, not on a ``*.x`` branch. +When the stable branch is eventually cut, follow the standard process from :ref:`new-releases`. + +After the GitHub release is created, check that the :guilabel:`This is a pre-release` checkbox is set on the release page. +The workflow sets it automatically for PEP 440 pre-release version tags. +If the checkbox is not set, edit the release on GitHub and set it manually before the release is widely announced. + +When commenting on issues, use the qualifier so users know the version is not stable: + +.. code-block:: text + + This is included in v8.0.0a1 (alpha). + + +.. _backport-releases: + +Backport releases +----------------- + +A backport release cherry-picks specific commits onto a ``*.x`` stable branch to ship a fix without taking everything on ``main``. + +#. Set the version: + + .. code-block:: shell + + export VERSION=7.3.2 + +#. Check that the stable branch is at the latest published tag. + If it's behind, advance it first (see the last step of :ref:`new-releases`). + + .. code-block:: shell + + git checkout 7.x + git pull + +#. Cherry-pick the commits from ``main``: + + .. code-block:: shell + + git cherry-pick [ ...] + + Conflicts between branches are common, usually around error types or control-flow that diverged. + After resolving, run ``pytest`` to confirm no new failures. + +#. Add a news fragment in ``news/``, then build the changelog: + + .. code-block:: shell + + make changes + +#. Commit and push to the stable branch: + + .. code-block:: shell + + git add CHANGES.rst news/ + git commit -m "version $VERSION" + git push # to PyCalendar/icalendar + +#. Confirm CI passes, then tag: + + .. code-block:: shell + + git tag "v$VERSION" + git push upstream "v$VERSION" + + .. warning:: + + Tags cannot be moved or deleted once pushed. + If a release turns out to be broken, cut a new version; don't attempt to retag. + See :issue:`1033`. + +#. Approve the ``deploy-tag-to-pypi`` and ``deploy-github-release`` jobs in `GitHub Actions `_ when they appear. + Only maintainers listed as Required Reviewers in :menuselection:`Settings --> Environments --> PyPI` can approve. + The approval window is 30 days; after that you'd need to retag with a new version. + +#. Comment on each fixed issue: + + .. code-block:: text + + This is fixed in v7.3.2. + + +.. _security-releases: + +Security releases +----------------- + +A security release follows the :ref:`backport-releases` process, with embargo until the fix ships. + +#. Don't discuss the vulnerability publicly until the fix is released. + If someone files a public issue, ask them to use `GitHub's private vulnerability reporting `_ instead, and close the public issue. + +#. Open a draft `GitHub Security Advisory `_. + Request a CVE from the advisory form. + The advisory stays private until you publish it. + +#. Develop the fix in the GHSA's private fork, or in a local branch not pushed until release day. + +#. Coordinate with the other maintainers on timing before tagging. + +#. Release the fix as a backport patch and as the next ``main`` release simultaneously. + +#. After PyPI confirms the release, publish the GHSA. + Coordinate the public announcement with the docs maintainer. + Links ----- This section contains useful links for maintainers and collaborators. -- To remove private information from an iCalendar file for bug reports, use `icalendar-anonymizer `_ either through its `website `_ or `install it locally `_. +- To remove private information from an iCalendar file for bug reports, use `icalendar-anonymizer `_ either through its `website `_ or `install it locally `_. - `Python Calendaring Ecosystem `_ - `Future of icalendar, looking for maintainer #360 `_ - `Comment on the Plone tests running with icalendar `_ @@ -398,7 +523,7 @@ When adding support for a new Python version, or removing support for an old one Update the ``requires-python`` line and the ``classifiers`` list. :file:`docs/reference/versions-branches.rst` Update the compatibility information. -:file:`docs/maintenance.rst` +:file:`docs/contribute/maintenance.rst` Update this list if any new files need to be modified. `Branch Protection Rules `_ Update the branch protection rules so that they match the required test names. diff --git a/docs/styles/config/vocabularies/icalendar/accept.txt b/docs/styles/config/vocabularies/icalendar/accept.txt index 6f9627a30..4ad09f7e0 100644 --- a/docs/styles/config/vocabularies/icalendar/accept.txt +++ b/docs/styles/config/vocabularies/icalendar/accept.txt @@ -29,6 +29,8 @@ Repology recur.recur reformats RFCs? +GHSAs? +retag(ged|ging|s)? SARIF sphinx_copybutton sphinx_design diff --git a/news/+release-process-docs.documentation b/news/+release-process-docs.documentation new file mode 100644 index 000000000..b8dd7867e --- /dev/null +++ b/news/+release-process-docs.documentation @@ -0,0 +1 @@ +Added pre-release, backport release, and security release process documentation to :doc:`/contribute/maintenance`. @SashankBhamidi