Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 157 additions & 17 deletions docs/contribute/maintenance.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------

Expand All @@ -123,6 +125,11 @@ However, only people with ``Environments/Configure PyPI`` access can approve an

make new-version

.. note::

:program:`make new-version` reads the version from the ``main`` branch.
For a backport release on a ``*.x`` branch, set ``VERSION`` manually instead.

#. Copy and paste the new version into an environment variable to use in subsequent commands during the release process.

.. code-block:: shell
Expand Down Expand Up @@ -176,12 +183,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"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

haha, this is one of my pet peeves, either is valid, but the lack of a space triggers me.

git push # to PyCalendar/icalendar

#. See if the `CI tests <https://github.com/PyCalendar/icalendar/actions>`_ 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 <https://github.com/PyCalendar/icalendar/actions>`_ 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.

Expand Down Expand Up @@ -227,29 +234,34 @@ However, only people with ``Environments/Configure PyPI`` access can approve an

git push # to PyCalendar/icalendar

#. Next create a tag, and push the tag.

.. code-block:: shell

git tag "v$VERSION"
git push upstream "v$VERSION" # to PyCalendar/icalendar
#. Next, create a tag, and push the tag.

.. warning::

Once a tag is pushed to the repository, it must not be re-tagged or deleted.
This creates issues for downstream repositories.
See :issue:`1033`.

#. Once the tag is pushed and its `CI tests`_ pass, check the `GitHub Actions <https://github.com/PyCalendar/icalendar/actions>`_, and wait for maintainers to get an email:
.. code-block:: shell

git tag "v$VERSION"
git push upstream "v$VERSION" # to PyCalendar/icalendar

#. Once the tag is pushed and its `CI tests`_ pass, check `GitHub Actions <https://github.com/PyCalendar/icalendar/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

Subject: Deployment review in PyCalendar/icalendar

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) <https://docs.pypi.org/trusted-publishers/>`_.
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`.

Expand Down Expand Up @@ -342,7 +354,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

Expand All @@ -364,13 +376,141 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
#. Manually trigger the "latest" version on `Read the Docs <https://app.readthedocs.org/projects/icalendar/>`_.
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.

.. 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.

.. code-block:: shell

git checkout 7.x
git pull
git merge main
git push # to PyCalendar/icalendar

#. 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 <https://peps.python.org/pep-0440/>`_ suffixes: ``8.0.0a1``, ``8.0.0b1``, ``8.0.0rc1``.
The release steps are the same as a standard release, with the following 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 you create the GitHub release, 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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See earlier comment about setting the environment variable.


.. 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 <commit-hash> [<commit-hash> ...]

Conflicts between branches are common, usually around error types or control-flow that diverged.
After resolving any conflicts, run ``pytest`` to confirm that tests pass.

#. Add a news fragment in ``news/``, then build the change log:

.. 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 can't 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 <https://github.com/PyCalendar/icalendar/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 the commit 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 an 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 <https://github.com/PyCalendar/icalendar/security/advisories/new>`_ instead, and close the public issue.

#. Open a draft `GitHub Security Advisory <https://github.com/PyCalendar/icalendar/security/advisories>`_.
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
-----
Expand Down Expand Up @@ -398,7 +538,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 <https://github.com/PyCalendar/icalendar/settings/branch_protection_rules>`_
Update the branch protection rules so that they match the required test names.
Expand Down
2 changes: 2 additions & 0 deletions docs/styles/config/vocabularies/icalendar/accept.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ defusedxml
dicts
[Dd]ocstrings?
fuzzer
GHSAs?
Hanoka
icalendar(\.[a-z]+)+
iCal
Expand All @@ -28,6 +29,7 @@ python\-icalendar
Repology
recur.recur
reformats
retag(ged|ging|s)?
RFCs?
SARIF
sphinx_copybutton
Expand Down
1 change: 1 addition & 0 deletions news/+release-process-docs.documentation
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added pre-release, backport release, and security release process documentation to :doc:`/contribute/maintenance`. :user:`SashankBhamidi`