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 by adding the GitHub username to the list of Required Reviewers.

Collaborators#

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

merge pull requests, and
initiate a new release.

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

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.

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.
```
export VERSION=6.3.0
```

Create a commit on the release branch (or equivalent) to release this version.

git checkout main
git pull
git checkout -b release main
git add CHANGES.rst
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
```
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
git push -d origin release

Create a tag for the release and see if the CI-tests are running.

git checkout main
git pull
git tag "v$VERSION"
git push upstream "v$VERSION" # could be origin or whatever reference

Once the tag is pushed and its CI-tests are passing, maintainers will get an e-mail:

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. If that happens, notify the issues that were fixed about this release.

Copy this to the start of CHANGES.rst.

6.3.1 (unreleased)
------------------

Minor changes:

- ...

Breaking changes:

- ...

New features:

- ...

Bug fixes:

- ...

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

git checkout main
git pull
git add CHANGES.rst
git commit -m"Add new CHANGELOG section for future release

See https://icalendar.readthedocs.io/en/latest/maintenance.html#new-releases"
git push upstream main # could be origin or whatever reference

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 test the changes thoroughly, and update any documentation that mentions supported Python versions.