diff --git a/docs/contribute/maintenance.rst b/docs/contribute/maintenance.rst index 54d9d12..8e601ff 100644 --- a/docs/contribute/maintenance.rst +++ b/docs/contribute/maintenance.rst @@ -30,11 +30,11 @@ Maintainers need the following permissions. Collaborators ------------- -Collaborators are people with write access to the repository. +Collaborators have write access to the repository. As a collaborator, you can -- merge Pull Requests, -- initiate a new release, see below. +- 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: @@ -44,72 +44,76 @@ We want to have as many knowledgeable people with write access taking responsibi - 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. +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. +A maintainer may ask if you would like to become one. -New Releases + +New releases ------------ -This explains how to create a new release on `PyPI `_. +This section 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. +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 :file:`CHANGES.rst` is up to date with the `latest merged pull requests `_, and the version you want to release is correctly named. -1. 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. + .. code-block:: shell - .. code-block:: bash + export VERSION=6.3.0 - export VERSION=6.3.0 +#. Create a commit on the ``release`` branch (or equivalent) to release this version. -2. Create a commit on the ``release`` branch (or equivalent) to release this version. + .. code-block:: shell - .. code-block:: bash + git checkout main + git pull + git checkout -b release main + git add CHANGES.rst + git commit -m"version $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 `_. -3. Push the commit and `create a pull request `__ - Here is an `example pull request #457 `__. + .. code-block:: shell - .. code-block:: bash + git push -u origin release - 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. -4. 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. -5. Clean up behind you! +#. Clean up behind you! - .. code-block:: bash + .. code-block:: shell - git checkout main - git pull - git branch -d release - git push -d origin release + git checkout main + git pull + git branch -d release + git push -d origin release -6. Create a tag for the release and see if the `CI-tests`_ are running. +#. Create a tag for the release and see if the `CI-tests`_ are running. - .. code-block:: bash + .. code-block:: shell - git checkout main - git pull - git tag "v$VERSION" - git push upstream "v$VERSION" # could be origin or whatever reference + git checkout main + git pull + git tag "v$VERSION" + git push upstream "v$VERSION" # could be origin or whatever reference -7. Once the tag is pushed and its `CI-tests`_ are passing, maintainers will get an e-mail:: +#. Once the tag is pushed and its `CI-tests`_ are passing, maintainers will get an e-mail: - Subject: Deployment review in collective/icalendar + .. code-block:: text - tests: PyPI is waiting for your review + Subject: Deployment review in collective/icalendar -8. 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. -9. Copy this to the start of ``CHANGES.rst``:: + 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``. + + .. code-block:: text 6.3.1 (unreleased) ------------------ @@ -130,35 +134,41 @@ However, only people with ``PyPI environment access for GitHub Actions`` can app - ... -10. Push the new CHANGELOG so it is used for future changes. +#. Push the new ``CHANGELOG`` so it is used for future changes. - .. code-block:: bash + .. code-block:: shell - git checkout main - git pull - git add CHANGES.rst - git commit -m"Add new CHANGELOG section for future release + 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 + 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: +This section contains useful links for maintainers and collaborators. -- `Future of icalendar, looking for maintainer #360 `__ -- `Comment on the Plone tests running with icalendar `__ +- `Future of icalendar, looking for maintainer #360 `_ +- `Comment on the Plone tests running with icalendar `_ -Updating Python Versions + +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: +When adding support for a new Python version, or removing support for an old one, the following files need to be updated: -1. ``.github/workflows/tests.yml``: Add or remove the Python version from the test matrix. -2. ``tox.ini``: Update the ``envlist`` to include or remove the Python version. -3. ``pyproject.toml``: Update the ``requires-python`` line and the ``classifiers`` list. -4. ``README.rst``: Update the compatibility information. -5. ``docs/maintenance.rst``: Update this list if any new files need to be modified. +:file:`.github/workflows/tests.yml` + Add or remove the Python version from the test matrix. +:file:`tox.ini` + Update the ``envlist`` to include or remove the Python version. +:file:`pyproject.toml` + Update the ``requires-python`` line and the ``classifiers`` list. +:file:`README.rst` + Update the compatibility information. +:file:`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. +Remember to test the changes thoroughly, and update any documentation that mentions supported Python versions.