Repository navigation
Document pre-release, backport, and security release processes #2186
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
SashankBhamidi
wants to merge
4
commits into
main
Choose a base branch
from
release-process-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
18a4cb6
document pre-release, backport, and security release processes
SashankBhamidi a84b953
add retag and GHSA to Vale vocabulary
SashankBhamidi 83544ce
apply stevepiercy's review suggestions
SashankBhamidi f53a5b7
move tag warning before the shell commands
SashankBhamidi File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -95,9 +95,11 @@ When doing so, you or the inviter may submit a pull request to update the :file: | |
| Release versions | ||
| ---------------- | ||
|
|
||
| .. seealso:: | ||
| .. seealso:: | ||
| :doc:`/reference/versions-branches` | ||
|
|
||
| .. _new-releases: | ||
|
|
||
| New releases | ||
| ------------ | ||
|
|
||
|
|
@@ -123,6 +125,11 @@ However, only people with ``Environments/Configure PyPI`` access can approve an | |
|
|
||
| make new-version | ||
|
|
||
| .. note:: | ||
|
|
||
| :program:`make new-version` reads the version from the ``main`` branch. | ||
| For a backport release on a ``*.x`` branch, set ``VERSION`` manually instead. | ||
|
|
||
| #. Copy and paste the new version into an environment variable to use in subsequent commands during the release process. | ||
|
|
||
| .. code-block:: shell | ||
|
|
@@ -176,12 +183,12 @@ However, only people with ``Environments/Configure PyPI`` access can approve an | |
|
|
||
| git add CHANGES.rst news/ docs/conf.py | ||
| git add .github/workflows/tests.yml # Only for a new major release | ||
| git commit -m"version $VERSION" | ||
| git commit -m "version $VERSION" | ||
| git push # to PyCalendar/icalendar | ||
|
|
||
| #. See if the `CI tests <https://github.com/PyCalendar/icalendar/actions>`_ are running on the commit. | ||
| If they are not running, no new release can be issued. | ||
| If the CI passes, go ahead. | ||
| #. Confirm the `CI tests <https://github.com/PyCalendar/icalendar/actions>`_ are running on the commit and pass before continuing. | ||
| No tag should be pushed until CI is green on the version commit. | ||
| If CI is not running, no release can be issued. | ||
|
|
||
| #. Create a tag for the release on its release branch ``*.x``, push, and make sure the `CI tests`_ are running. | ||
|
|
||
|
|
@@ -227,29 +234,34 @@ However, only people with ``Environments/Configure PyPI`` access can approve an | |
|
|
||
| git push # to PyCalendar/icalendar | ||
|
|
||
| #. Next create a tag, and push the tag. | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| git tag "v$VERSION" | ||
| git push upstream "v$VERSION" # to PyCalendar/icalendar | ||
| #. Next, create a tag, and push the tag. | ||
|
|
||
| .. warning:: | ||
|
|
||
| Once a tag is pushed to the repository, it must not be re-tagged or deleted. | ||
| This creates issues for downstream repositories. | ||
| See :issue:`1033`. | ||
|
|
||
| #. Once the tag is pushed and its `CI tests`_ pass, check the `GitHub Actions <https://github.com/PyCalendar/icalendar/actions>`_, and wait for maintainers to get an email: | ||
| .. code-block:: shell | ||
|
|
||
| git tag "v$VERSION" | ||
| git push upstream "v$VERSION" # to PyCalendar/icalendar | ||
|
|
||
| #. Once the tag is pushed and its `CI tests`_ pass, check `GitHub Actions <https://github.com/PyCalendar/icalendar/actions>`_. | ||
| The ``deploy-tag-to-pypi`` and ``deploy-github-release`` jobs will wait for a manual approval. | ||
| Maintainers listed as Required Reviewers in :menuselection:`Settings --> Environments --> PyPI` will receive an email: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| Subject: Deployment review in PyCalendar/icalendar | ||
|
|
||
| tests: PyPI is waiting for your review | ||
|
|
||
| #. If the release is approved by a maintainer, it will be pushed to `PyPI`_. | ||
| Don't wait for that, continue. | ||
| Approve the deployment in GitHub Actions. | ||
| PyPI publishing uses `Trusted Publishing (OIDC) <https://docs.pypi.org/trusted-publishers/>`_. | ||
| No API token is needed. | ||
| The approval window is 30 days. | ||
| If it expires, push a new tag with a bumped version number. | ||
|
|
||
| #. Update the version switcher file :file:`docs/_static/version-switcher.json`. | ||
|
|
||
|
|
@@ -342,7 +354,7 @@ However, only people with ``Environments/Configure PyPI`` access can approve an | |
| git push # to PyCalendar/icalendar | ||
|
|
||
| #. If you cut a new *major* release version, update the Sphinx configuration file :file:`docs/conf.py` on the *previous* numbered major release branch to show the version warning banner. | ||
| For example, when releasing 7.0.0, checkout ``6.x``, and update it as shown. | ||
| For example, when releasing 7.0.0, check out ``6.x``, and update it as shown. | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
|
|
@@ -364,13 +376,141 @@ However, only people with ``Environments/Configure PyPI`` access can approve an | |
| #. Manually trigger the "latest" version on `Read the Docs <https://app.readthedocs.org/projects/icalendar/>`_. | ||
| To the right in the row for "latest," click the ellipsis :guilabel:`…`, and from the pop-up menu select :guilabel:`Rebuild version`. | ||
|
|
||
| #. Advance the ``*.x`` stable branch to the new tag so it stays current for future backports. | ||
|
|
||
| .. note:: | ||
|
|
||
| If the stable branch is behind the latest tag, push it forward before starting any backport. | ||
| A branch that's out of date causes cherry-pick conflicts and forces a version bump. | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| git checkout 7.x | ||
| git pull | ||
| git merge main | ||
| git push # to PyCalendar/icalendar | ||
|
|
||
| #. Add a comment to each of the issues mentioned in the new release. | ||
| Example: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| This is included in v7.0.0. | ||
|
|
||
| .. _pre-releases: | ||
|
|
||
| Pre-releases | ||
| ------------ | ||
|
|
||
| Pre-releases use `PEP 440 <https://peps.python.org/pep-0440/>`_ suffixes: ``8.0.0a1``, ``8.0.0b1``, ``8.0.0rc1``. | ||
| The release steps are the same as a standard release, with the following differences. | ||
|
|
||
| The tag goes on ``main``, not on a ``*.x`` branch. | ||
| When the stable branch is eventually cut, follow the standard process from :ref:`new-releases`. | ||
|
|
||
| After you create the GitHub release, check that the :guilabel:`This is a pre-release` checkbox is set on the release page. | ||
| The workflow sets it automatically for PEP 440 pre-release version tags. | ||
| If the checkbox is not set, edit the release on GitHub and set it manually before the release is widely announced. | ||
|
|
||
| When commenting on issues, use the qualifier so users know the version is not stable: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| This is included in v8.0.0a1 (alpha). | ||
|
|
||
|
|
||
| .. _backport-releases: | ||
|
|
||
| Backport releases | ||
| ----------------- | ||
|
|
||
| A backport release cherry-picks specific commits onto a ``*.x`` stable branch to ship a fix without taking everything on ``main``. | ||
|
|
||
| #. Set the version: | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. See earlier comment about setting the environment variable. |
||
|
|
||
| .. code-block:: shell | ||
|
|
||
| export VERSION=7.3.2 | ||
|
|
||
| #. Check that the stable branch is at the latest published tag. | ||
| If it's behind, advance it first (see the last step of :ref:`new-releases`). | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| git checkout 7.x | ||
| git pull | ||
|
|
||
| #. Cherry-pick the commits from ``main``: | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| git cherry-pick <commit-hash> [<commit-hash> ...] | ||
|
|
||
| Conflicts between branches are common, usually around error types or control-flow that diverged. | ||
| After resolving any conflicts, run ``pytest`` to confirm that tests pass. | ||
|
|
||
| #. Add a news fragment in ``news/``, then build the change log: | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| make changes | ||
|
|
||
| #. Commit and push to the stable branch: | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| git add CHANGES.rst news/ | ||
| git commit -m "version $VERSION" | ||
| git push # to PyCalendar/icalendar | ||
|
|
||
| #. Confirm CI passes, then tag: | ||
|
|
||
| .. code-block:: shell | ||
|
|
||
| git tag "v$VERSION" | ||
| git push upstream "v$VERSION" | ||
|
|
||
| .. warning:: | ||
|
|
||
| Tags can't be moved or deleted once pushed. | ||
| If a release turns out to be broken, cut a new version. | ||
| Don't attempt to retag. | ||
| See :issue:`1033`. | ||
|
|
||
| #. Approve the ``deploy-tag-to-pypi`` and ``deploy-github-release`` jobs in `GitHub Actions <https://github.com/PyCalendar/icalendar/actions>`_ when they appear. | ||
| Only maintainers listed as Required Reviewers in :menuselection:`Settings --> Environments --> PyPI` can approve. | ||
| The approval window is 30 days. | ||
| After that, you'd need to retag the commit with a new version. | ||
|
|
||
| #. Comment on each fixed issue: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| This is fixed in v7.3.2. | ||
|
|
||
|
|
||
| .. _security-releases: | ||
|
|
||
| Security releases | ||
| ----------------- | ||
|
|
||
| A security release follows the :ref:`backport-releases` process, with an embargo until the fix ships. | ||
|
|
||
| #. Don't discuss the vulnerability publicly until the fix is released. | ||
| 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. | ||
|
|
||
| #. Open a draft `GitHub Security Advisory <https://github.com/PyCalendar/icalendar/security/advisories>`_. | ||
| Request a CVE from the advisory form. | ||
| The advisory stays private until you publish it. | ||
|
|
||
| #. Develop the fix in the GHSA's private fork, or in a local branch not pushed until release day. | ||
|
|
||
| #. Coordinate with the other maintainers on timing before tagging. | ||
|
|
||
| #. Release the fix as a backport patch and as the next ``main`` release simultaneously. | ||
|
|
||
| #. After PyPI confirms the release, publish the GHSA. | ||
| Coordinate the public announcement with the docs maintainer. | ||
|
|
||
|
|
||
| Links | ||
| ----- | ||
|
|
@@ -398,7 +538,7 @@ When adding support for a new Python version, or removing support for an old one | |
| Update the ``requires-python`` line and the ``classifiers`` list. | ||
| :file:`docs/reference/versions-branches.rst` | ||
| Update the compatibility information. | ||
| :file:`docs/maintenance.rst` | ||
| :file:`docs/contribute/maintenance.rst` | ||
| Update this list if any new files need to be modified. | ||
| `Branch Protection Rules <https://github.com/PyCalendar/icalendar/settings/branch_protection_rules>`_ | ||
| Update the branch protection rules so that they match the required test names. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| Added pre-release, backport release, and security release process documentation to :doc:`/contribute/maintenance`. :user:`SashankBhamidi` |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
haha, this is one of my pet peeves, either is valid, but the lack of a space triggers me.