Skip to content

Commit f53a5b7

Browse files
move tag warning before the shell commands
1 parent 83544ce commit f53a5b7

1 file changed

Lines changed: 37 additions & 22 deletions

File tree

‎docs/contribute/maintenance.rst‎

Lines changed: 37 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,18 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
119119
120120
If there are any changes to the module, then open a pull request and merge it.
121121

122-
#. Set an environment variable to use in subsequent commands during the release process.
122+
#. Determine the new version of icalendar.
123+
124+
.. code-block:: shell
125+
126+
make new-version
127+
128+
.. note::
129+
130+
:program:`make new-version` reads the version from the ``main`` branch.
131+
For a backport release on a ``*.x`` branch, set ``VERSION`` manually instead.
132+
133+
#. Copy and paste the new version into an environment variable to use in subsequent commands during the release process.
123134

124135
.. code-block:: shell
125136
@@ -225,17 +236,17 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
225236
226237
#. Next, create a tag, and push the tag.
227238
228-
.. code-block:: shell
229-
230-
git tag "v$VERSION"
231-
git push upstream "v$VERSION" # to PyCalendar/icalendar
232-
233239
.. warning::
234240
235241
Once a tag is pushed to the repository, it must not be re-tagged or deleted.
236242
This creates issues for downstream repositories.
237243
See :issue:`1033`.
238244
245+
.. code-block:: shell
246+
247+
git tag "v$VERSION"
248+
git push upstream "v$VERSION" # to PyCalendar/icalendar
249+
239250
#. Once the tag is pushed and its `CI tests`_ pass, check `GitHub Actions <https://github.com/PyCalendar/icalendar/actions>`_.
240251
The ``deploy-tag-to-pypi`` and ``deploy-github-release`` jobs will wait for a manual approval.
241252
Maintainers listed as Required Reviewers in :menuselection:`Settings --> Environments --> PyPI` will receive an email:
@@ -247,8 +258,10 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
247258
tests: PyPI is waiting for your review
248259
249260
Approve the deployment in GitHub Actions.
250-
PyPI publishing uses `Trusted Publishing (OIDC) <https://docs.pypi.org/trusted-publishers/>`_; no API token is needed.
251-
The approval window is 30 days; if it expires, push a new tag with a bumped version number.
261+
PyPI publishing uses `Trusted Publishing (OIDC) <https://docs.pypi.org/trusted-publishers/>`_.
262+
No API token is needed.
263+
The approval window is 30 days.
264+
If it expires, push a new tag with a bumped version number.
252265
253266
#. Update the version switcher file :file:`docs/_static/version-switcher.json`.
254267
@@ -365,18 +378,18 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
365378
366379
#. Advance the ``*.x`` stable branch to the new tag so it stays current for future backports.
367380
381+
.. note::
382+
383+
If the stable branch is behind the latest tag, push it forward before starting any backport.
384+
A branch that's out of date causes cherry-pick conflicts and forces a version bump.
385+
368386
.. code-block:: shell
369387
370388
git checkout 7.x
371389
git pull
372390
git merge main
373391
git push # to PyCalendar/icalendar
374392
375-
.. note::
376-
377-
If the stable branch is behind the latest tag, push it forward before starting any backport.
378-
A branch that's out of date causes cherry-pick conflicts and forces a version bump.
379-
380393
#. Add a comment to each of the issues mentioned in the new release.
381394
382395
.. code-block:: text
@@ -389,12 +402,12 @@ Pre-releases
389402
------------
390403
391404
Pre-releases use `PEP 440 <https://peps.python.org/pep-0440/>`_ suffixes: ``8.0.0a1``, ``8.0.0b1``, ``8.0.0rc1``.
392-
The release steps are the same as a standard release, with these differences.
405+
The release steps are the same as a standard release, with the following differences.
393406
394407
The tag goes on ``main``, not on a ``*.x`` branch.
395408
When the stable branch is eventually cut, follow the standard process from :ref:`new-releases`.
396409
397-
After the GitHub release is created, check that the :guilabel:`This is a pre-release` checkbox is set on the release page.
410+
After you create the GitHub release, check that the :guilabel:`This is a pre-release` checkbox is set on the release page.
398411
The workflow sets it automatically for PEP 440 pre-release version tags.
399412
If the checkbox is not set, edit the release on GitHub and set it manually before the release is widely announced.
400413
@@ -433,9 +446,9 @@ A backport release cherry-picks specific commits onto a ``*.x`` stable branch to
433446
git cherry-pick <commit-hash> [<commit-hash> ...]
434447
435448
Conflicts between branches are common, usually around error types or control-flow that diverged.
436-
After resolving, run ``pytest`` to confirm no new failures.
449+
After resolving any conflicts, run ``pytest`` to confirm that tests pass.
437450
438-
#. Add a news fragment in ``news/``, then build the changelog:
451+
#. Add a news fragment in ``news/``, then build the change log:
439452
440453
.. code-block:: shell
441454
@@ -458,13 +471,15 @@ A backport release cherry-picks specific commits onto a ``*.x`` stable branch to
458471
459472
.. warning::
460473
461-
Tags cannot be moved or deleted once pushed.
462-
If a release turns out to be broken, cut a new version; don't attempt to retag.
474+
Tags can't be moved or deleted once pushed.
475+
If a release turns out to be broken, cut a new version.
476+
Don't attempt to retag.
463477
See :issue:`1033`.
464478
465479
#. Approve the ``deploy-tag-to-pypi`` and ``deploy-github-release`` jobs in `GitHub Actions <https://github.com/PyCalendar/icalendar/actions>`_ when they appear.
466480
Only maintainers listed as Required Reviewers in :menuselection:`Settings --> Environments --> PyPI` can approve.
467-
The approval window is 30 days; after that you'd need to retag with a new version.
481+
The approval window is 30 days.
482+
After that, you'd need to retag the commit with a new version.
468483
469484
#. Comment on each fixed issue:
470485
@@ -478,7 +493,7 @@ A backport release cherry-picks specific commits onto a ``*.x`` stable branch to
478493
Security releases
479494
-----------------
480495
481-
A security release follows the :ref:`backport-releases` process, with embargo until the fix ships.
496+
A security release follows the :ref:`backport-releases` process, with an embargo until the fix ships.
482497
483498
#. Don't discuss the vulnerability publicly until the fix is released.
484499
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.
@@ -502,7 +517,7 @@ Links
502517
503518
This section contains useful links for maintainers and collaborators.
504519
505-
- 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>`_.
520+
- 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>`_.
506521
- `Python Calendaring Ecosystem <https://pycal.org/>`_
507522
- `Future of icalendar, looking for maintainer #360 <https://github.com/PyCalendar/icalendar/discussions/360>`_
508523
- `Comment on the Plone tests running with icalendar <https://github.com/PyCalendar/icalendar/pull/447#issuecomment-1277643634>`_

0 commit comments

Comments
 (0)