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
165 changes: 145 additions & 20 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 @@ -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

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

Expand All @@ -240,16 +236,19 @@ 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 <https://github.com/PyCalendar/icalendar/actions>`_, and wait for maintainers to get an email:
#. 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 +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

Expand All @@ -364,20 +363,146 @@ 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.

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

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

This section contains useful links for maintainers and collaborators.

- To remove private information from an iCalendar file for bug reports, use `icalendar-anonymizer <https://github.com/PyCalendar/icalendar-anonymizer>`_ either through its `website <https://icalendar-anonymizer.com/>`_ or `install it locally <https://docs.icalendar-anonymizer.com/latest/installation.html>`_.
- To remove private information from an iCalendar file for bug reports, use `icalendar-anonymizer <https://github.com/pycalendar/icalendar-anonymizer>`_ either through its `website <https://icalendar-anonymizer.com/>`_ or `install it locally <https://docs.icalendar-anonymizer.com/latest/installation.html>`_.
- `Python Calendaring Ecosystem <https://pycal.org/>`_
- `Future of icalendar, looking for maintainer #360 <https://github.com/PyCalendar/icalendar/discussions/360>`_
- `Comment on the Plone tests running with icalendar <https://github.com/PyCalendar/icalendar/pull/447#issuecomment-1277643634>`_
Expand All @@ -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 <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 @@ -29,6 +29,8 @@ Repology
recur.recur
reformats
RFCs?
GHSAs?
retag(ged|ging|s)?
SARIF
sphinx_copybutton
sphinx_design
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`. @SashankBhamidi