Maintenance¶

The goal of this section is to make sure that the icalendar library receives a clear maintenance structure with it that is transparent.

Maintainers¶

Currently, the maintainers are

Maintainers need this:

Admin access to the repository.
These can be enabled by a current maintainer or an GitHub organisation administrator in the settings.
Maintainer or Owner access to the PyPI project.
The new maintainer needs a PyPI account for this with Two Factor Authentication (2FA) enabled because icalendar is a critical project on PyPI. The access can be given in the collaboration Section on PyPI.
Maintainer access to the Read The Docs project.
This can be given by existing maintainers listed on the project’s page. TODO: link to the settings
PyPI environment access for GitHub Actions grant new releases from tags.
This access can be granted in Settings → Environments → PyPI by adding the GitHub username to the list of “Required Reviewers”.

Collaborators¶

Collaborators are people with write access to the repository. As a collaborator, you can

merge Pull Requests,
initiate a new release, see below.

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 for becoming a collaborator or a maintainer asks you if you would like to become one.

New Releases¶

This explains how to create a new release on PyPI.

Since collaborators and maintainers have write access the the repository, they can start the release process. However, only people with PyPI environment access for GitHub Actions can approve an automated release to PyPI.

Check that the CHANGES.rst is up to date with the latest merged pull requests and the version you want to release is correctly named.

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

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 tests are running, 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 v6.0.0
git push upstream v6.0.0 # 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:

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