Maintenance#

This chapter describes the maintenance structure of icalendar.

icalendar Maintainers#

Currently the maintainers are the following people.

Maintainers need the following permissions.

Admin access to the repository.

These can be enabled by a current maintainer or a GitHub organization administrator in the settings.

Maintainer or Owner access to the PyPI project.

Each owner and maintainer needs a PyPI account. All PyPI accounts require two-factor authentication (2FA) enabled. Owners can invite either new owners or maintainers in the collaboration Section on PyPI.

Maintainer access to the Read the Docs project.

Existing maintainers can invite another maintainer through the Maintainers page.

Environments/Configure PyPI access for GitHub Workflows to grant new releases from tags.

Organization owners and repository administrators can grant this access in Settings ‣ Environments ‣ PyPI, or at collective/icalendar, by adding their GitHub username to the list of Required Reviewers.

Owner or Manager access to icalendar-coc@googlegroups.com

This Google Group is used for managing Code of Conduct infringement reports. Managers may manage and moderate messages, whereas Owners may also manage members. Management is performed through Google Groups icalendar-coc settings.

Registered access to the OSS Fuzz issue tracker for icalendar.

icalendar contributors use this issue tracker for managing Fuzz testing issues that arise from time to time. New issues do not get immediately disclosed to the public, and require that you register with a Google Account. Add your Google Account's email address to google/oss-fuzz, and create a pull request, to request the following access:

instant notification about fuzzing errors
undisclosed fuzzing issues

Existing issues will be disclosed after some time to the public.

Collaborators#

Collaborators have write access to the repository. As a collaborator, you can

merge pull requests,
initiate a new release, and
become a Code owner.

The maintainers of icalendar want to have as many knowledgeable people with write access taking responsibility as possible for these reasons:

a constant flow of fixes and new features
better code review
lower bus factor and backup
future maintainers

Nobody should merge their own pull requests. If you like to review or merge pull requests of other people and you have shown that you know how to contribute, you can ask to become a collaborator. A maintainer may ask if you would like to become one.

Code owner#

A code owner is a type of collaborator or maintainer who is responsible for a specific part of the code. Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.

You may ask, or be invited, to become a code owner as part of becoming a collaborator or maintainer. When doing so, you or the inviter may submit a pull request to update the .github/CODEOWNERS file.

New releases#

This section explains how to create a new release on PyPI.

Since collaborators and maintainers have write access to the repository, they can start the release process. However, only people with Environments/Configure PyPI access can approve an automated release to PyPI.

Set an environment variable to use in subsequent commands during the release process.
```
export VERSION=7.0.0
```
Update the main branch.
```
git checkout main
git pull
```
When cutting any new release that you'll tag and want to be considered as "stable", on the main or development branch, update the Sphinx configuration file docs/conf.py to match that version.

Hide the warning banner.
```
html_theme_options = {
    # ...
    "show_version_warning_banner": False,
```
Check that the file CHANGES.rst is up to date with the latest merged pull requests, and the version you want to release is correctly named. Change the date of the release, and remove empty sections.
```
-7.0.0 (unreleased)
+7.0.0 (2026-02-11)
```

Create a commit on a release branch to release this version.

git checkout -b release-$VERSION main
git add CHANGES.rst docs/_static/version-switcher.json
git commit -m"version $VERSION"

Push the commit and create a pull request. Here is an example pull request #457.
```
git push -u origin release-$VERSION
```
See if the CI-tests are running on the pull request. If they are not running, no new release can be issued. If the CI passes, merge the pull request.

Clean up behind you!

git checkout main
git pull
git branch -d release-$VERSION
git push -d origin release-$VERSION

Create a tag for the release on its release branch *.x and see if the CI-tests are running.
```
git checkout main
git pull
git checkout 7.x
git rebase main
git push 7.x  # to collective/icalendar
git tag "v$VERSION"
git push upstream "v$VERSION" # to collective/icalendar
```
Warning

Once a tag is pushed to the repository, it must not be re-tagged or deleted. This creates issues for downstream repositories. See #1033.
Once the tag is pushed and its CI-tests pass, check the GitHub Actions, and wait for maintainers to get an email:
```
Subject: Deployment review in collective/icalendar

tests: PyPI is waiting for your review
```
If the release is approved by a maintainer, it will be pushed to PyPI.

Copy this to the start of CHANGES.rst, and increase the version number.

git checkout main
git pull

7.0.0 (unreleased)
------------------

Minor changes
~~~~~~~~~~~~~

- ...

Breaking changes
~~~~~~~~~~~~~~~~

- ...

New features
~~~~~~~~~~~~

- ...

Bug fixes
~~~~~~~~~

- ...

Documentation
~~~~~~~~~~~~~

- ...

Push the new CHANGELOG so it is used for future changes.

git add CHANGES.rst
git commit -m "Add new CHANGELOG section for future release"
git push upstream main # to collective/icalendar

Once the release is pushed to PyPI, notify the issues mentioned on the new release of the new release. Example:
```
This is included in v7.0.0.
```
Update the version switcher file docs/_static/version-switcher.json.

Note

The remaining steps may be performed after the release because they pertain exclusively to documentation, which isn't included in the release.

Note

The following examples were used for the 7.0.0 release.

Important

Making a pull request won't have any effect to the version switcher on Read the Docs until it gets on to the main branch, so you might as well edit and push directly on the main branch for this step.
1. When cutting a new stable release version, on the main branch, update docs/_static/version-switcher.json to match that version.
  1. Copy the second previous major version and renumber it to the first previous version, in other words, copy 5.x and renumber the copy to 6.x.
    { "version": "6.x", "url": "https://icalendar.readthedocs.io/en/6.x/" },
  2. Next, edit the array item for the previous version to reflect the current major release.
    { "name": "7.x (stable)", "version": "v7.0.0", "url": "https://icalendar.readthedocs.io/en/stable/", "preferred": "true" },
2. When cutting a minor or patch release version, on the main or development branch, update docs/_static/version-switcher.json to match that version's tag name.
```
{
    "name": "7.x (stable)",
    "version": "v7.0.1",
    "url": "https://icalendar.readthedocs.io/en/stable/",
    "preferred": "true"
},
```
When cutting a new stable release version, update the Sphinx configuration file docs/conf.py as shown.
1. On the main branch, which is now the development branch, show the warning banner.
```
html_theme_options = {
    # ...
    "show_version_warning_banner": True,
```
2. On the previous numbered major release branch, show the warning banner.
```
html_theme_options = {
    # ...
    "show_version_warning_banner": True,
```
Configure Read the Docs.
1. Deactivate any non-stable releases. Click on the ellipsis icon, and select Configure version. Toggle the Active switch to deactivate the version.
2. Click Add version to do just that. Search for the previous major version #.x. Click on the version that appears in the select menu that matches your search. Toggle the Active switch to activate the version.

Links#

This section contains useful links for maintainers and collaborators.

Updating Python versions#

When adding support for a new Python version, or removing support for an old one, the following files need to be updated:

.github/workflows/tests.yml: Add or remove the Python version from the test matrix.
tox.ini: Update the envlist to include or remove the Python version.
pyproject.toml: Update the requires-python line and the classifiers list.
README.rst: Update the compatibility information.
docs/maintenance.rst: Update this list if any new files need to be modified.

Remember to write tests that completely cover the changes, and update any documentation that mentions supported Python versions.