From 2135c68ccbdad94378809902b52fcad546efd5b3 Mon Sep 17 00:00:00 2001
From: Will Yardley <wyardley@users.noreply.github.com>
Date: Fri, 27 Sep 2024 15:56:22 -0700
Subject: [PATCH 1/7] docs(github-actions): clarify & consolidate GitHub
Actions usage docs (#1011)
Resolves: #907
* chore(scripts): remove non-existant file from version bump script
* docs(automatic-releases): drop extrenous github push configuration
* docs(homepage): remove link to old github config & update token scope config
* docs(github-actions): expand descriptions & clarity of actions configs
* docs(github-actions): add configuration & description of publish action
* docs(github-actions): revert removal of namespace prefix from examples
---
docs/automatic-releases/github-actions.rst | 727 +++++++++++++++++++--
docs/automatic-releases/index.rst | 8 -
docs/configuration.rst | 2 +-
docs/github-action.rst | 139 ----
docs/index.rst | 26 +-
scripts/bump_version_in_docs.py | 1 -
6 files changed, 698 insertions(+), 205 deletions(-)
delete mode 100644 docs/github-action.rst
diff --git a/docs/automatic-releases/github-actions.rst b/docs/automatic-releases/github-actions.rst
index ca6b8661f..36bf58541 100644
--- a/docs/automatic-releases/github-actions.rst
+++ b/docs/automatic-releases/github-actions.rst
@@ -1,95 +1,728 @@
-.. _github-actions:
+.. _gh_actions:
-Setting up python-semantic-release on GitHub Actions
-====================================================
+GitHub Actions
+==============
-Python Semantic Release includes a GitHub Action which runs the ``version`` and
-``publish`` commands. The repository is set to ``PyPI``. You can read the full set
-of inputs available, and their descriptions in the `action definition`_.
+There are two official GitHub Actions for Python Semantic Release:
-Your project's configuration file will be used as normal.
+1. :ref:`python-semantic-release/python-semantic-release@TAG <gh_actions-psr>`
+ This is the main action that runs the :ref:`version <cmd-version>` CLI
+ command. It is used to (1) determine the next version number, (2) stamp the
+ version number, (3) run the build command, (4) build the changelog, (5) commit
+ the changes, (6) tag the commit, (7) publish the commit & tag and lastly
+ (8) create a GitHub release. For more information review the
+ :ref:`version command documentation <cmd-version>` and see
+ :ref:`below <gh_actions-psr>` for the Action configuration options.
-The GitHub Action provides the following outputs:
+2. :ref:`python-semantic-release/publish-action@TAG <gh_actions-publish>`
+ This action is used to execute the :ref:`publish <cmd-publish>` CLI command.
+ It is used to upload files, such as distribution artifacts and other assets,
+ to a GitHub release.
-+-------------+-----------------------------------------------------------+
-| Output | Description |
-+-------------+-----------------------------------------------------------+
-| released | "true" if a release was made, "false" otherwise |
-+-------------+-----------------------------------------------------------+
-| version | The newly released version if one was made, otherwise |
-| | the current version |
-+-------------+-----------------------------------------------------------+
-| tag | The Git tag corresponding to the "version" output. The |
-| | format is dictated by your configuration. |
-+-------------+-----------------------------------------------------------+
+.. note::
+ These GitHub Actions are only simplified wrappers around the
+ python-semantic-release CLI. Ultimately, they download and install the
+ published package from PyPI so if you find that you are trying to do something
+ more advanced or less common, you may need to install and use the CLI directly.
-.. _action definition: https://github.com/python-semantic-release/python-semantic-release/blob/master/action.yml
+.. _gh_actions-psr:
-Example Workflow
-----------------
+Python Semantic Release Action
+''''''''''''''''''''''''''''''
+
+The official `Python Semantic Release GitHub Action`_ is a `GitHub Docker Action`_,
+which means at the beginning of the job it will build a Docker image that contains
+the Python Semantic Release package and its dependencies. It will then run the
+job step inside the Docker Container. This is done to ensure that the environment
+is consistent across all GitHub Runners regardless of platform. With this choice,
+comes some limitations of non-configurable options like a pre-defined python
+version, lack of installed build tools, and an inability to utilize caching.
+
+The primary benefit of using the GitHub Action is that it is easy to set up and
+use for most projects. We handle a lot of the git configuration under the hood,
+so you don't have to handle it yourself. There are a plenty of customization
+options available which are detailed individually below.
+
+Most importantly your project's configuration file will be used as normal, as
+your project will be mounted into the container for the action to use.
+
+.. _Python Semantic Release GitHub Action: https://github.com/marketplace/actions/python-semantic-release
+.. _GitHub Docker Action: https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action
+
+.. seealso::
+
+ `action.yml`__: the code definition of the action
+
+ __ https://github.com/python-semantic-release/python-semantic-release/blob/master/action.yml
+
+.. _gh_actions-psr-inputs:
+
+Inputs
+------
+
+GitHub Action inputs are used for select configuration and provide the necessary
+information to execute the action. The inputs are passed to the action using the
+``with`` keyword in the workflow file. Many inputs will mirror the command line
+options available in the :ref:`version <cmd-version>` command. This section
+outlines each supported input and its purpose.
+
+----
+
+.. _gh_actions-psr-inputs-build_metadata:
+
+``build_metadata``
+""""""""""""""""""
+
+**Type:** ``string``
+
+Explicitly set the build metadata of the version. This is equivalent to running the command:
+
+.. code:: shell
+
+ semantic-release version --build-metadata <metadata>
+
+**Required:** ``false``
+
+.. seealso::
+
+ - :ref:`cmd-version-option-build-metadata` option for the :ref:`version <cmd-version>` command
+
+----
+
+.. _gh_actions-psr-inputs-changelog:
+
+``changelog``
+"""""""""""""
+
+**Type:** ``Literal["true", "false"]``
+
+Override whether the action should generate a changelog or not. This option is
+equivalent to adding either ``--changelog`` (on ``true``) or ``--no-changelog``
+(on ``false``) to the :ref:`version <cmd-version>` command.
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-changelog` options for the :ref:`version <cmd-version>`
+ command
+
+----
+
+.. _gh_actions-psr-inputs-commit:
+
+``commit``
+""""""""""
+
+**Type:** ``Literal["true", "false"]``
+
+Override whether the action should commit any changes to the local repository. Changes
+include the version stamps, changelog, and any other files that are modified and added
+to the index during the build command. This option is equivalent to adding either
+``--commit`` (on ``true``) or ``--no-commit`` (on ``false``) to the
+:ref:`version <cmd-version>` command.
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-commit` options for the :ref:`version <cmd-version>` command
+
+----
+
+.. _gh_actions-psr-inputs-directory:
+
+``directory``
+"""""""""""""
+
+If the project is not at the root of the repository (like in monorepos), you
+can specify a sub-directory to change into before running semantic-release.
+
+**Required:** ``false``
+
+**Default:** ``.``
+
+----
+
+.. _gh_actions-psr-inputs-force:
+
+``force``
+"""""""""
+
+**Type:** ``Literal["prerelease", "patch", "minor", "major"]``
+
+Force the next version to be a specific bump type. This is equivalent to running
+the command:
+
+.. code:: shell
+
+ semantic-release version --<type>
+
+ # Ex: force a patch level version bump
+ semantic-release version --patch
+
+
+**Required:** ``false``
+
+.. seealso::
+
+ - :ref:`cmd-version-option-force-level` options for the :ref:`version <cmd-version>` command
+
+----
+
+.. _gh_actions-psr-inputs-git_committer_email:
+
+``git_committer_email``
+"""""""""""""""""""""""
+
+The email of the account used to commit. If customized, it must be associated
+with the provided token.
+
+**Required:** ``false``
+
+----
+
+.. _gh_actions-psr-inputs-git_committer_name:
+
+``git_committer_name``
+""""""""""""""""""""""
+
+The name of the account used to commit. If customized, it must be associated
+with the provided token.
+
+**Required:** ``false``
+
+----
+
+.. _gh_actions-psr-inputs-github_token:
+
+``github_token``
+""""""""""""""""
+
+The GitHub Token is essential for access to your GitHub repository to allow the
+push of commits & tags as well as to create a release. Not only do you need to
+provide the token as an input but you also need to ensure that the token has the
+correct permissions.
+
+The token should have the following `permissions`_:
+
+* id-token: write
+* contents: write
+
+**Required:** ``true``
+
+.. _permissions: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions
+
+----
+
+.. _gh_actions-psr-inputs-prerelease:
+
+``prerelease``
+""""""""""""""
+
+Force the version to be a prerelease version when set to ``true``. This is equivalent
+to running the command:
+
+.. code:: shell
+
+ semantic-release version --as-prerelease
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-as-prerelease` option for the :ref:`version <cmd-version>`
+ command
+
+----
+
+.. _gh_actions-psr-inputs-prerelease_token:
+
+``prerelease_token``
+""""""""""""""""""""
+
+Override any prerelease token in the configuration file with this value, if it is
+a pre-release. This will override the matching release branch configuration's
+``prerelease_token`` value. If you always want it to be a prerelease then you must
+also set the :ref:`gh_actions-psr-inputs-prerelease` input to ``true``.
+
+This option is equivalent to running the command:
+
+.. code:: shell
+
+ semantic-release version --prerelease-token <token>
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-prerelease-token` option for the :ref:`version <cmd-version>`
+ command
+
+----
+
+.. _gh_actions-psr-inputs-push:
+
+``push``
+""""""""
+
+**Type:** ``Literal["true", "false"]``
+
+Override whether the action should push any commits or tags from the local repository
+to the remote repository. This option is equivalent to adding either ``--push`` (on
+``true``) or ``--no-push`` (on ``false``) to the :ref:`version <cmd-version>` command.
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-push` options for the :ref:`version <cmd-version>` command
+
+----
+
+.. _gh_actions-psr-inputs-root_options:
+
+``root_options``
+""""""""""""""""
+
+Additional options for the main ``semantic-release`` command, which will come
+before the :ref:`version <cmd-version>` subcommand.
+
+ **Example**
+
+ .. code:: yaml
+
+ - uses: python-semantic-release/python-semantic-release@v9.8.9
+ with:
+ root_options: "-vv --noop"
+
+ This configuration would cause the command to be
+ ``semantic-release -vv --noop version``, which would run the version command
+ verbosely but in no-operation mode.
+
+**Required:** ``false``
+
+**Default:** ``-v``
+
+.. seealso::
+
+ - :ref:`Options <cmd-main-options>` for the :ref:`semantic-release <cmd-main>` command
+
+----
+
+.. _gh_actions-psr-inputs-ssh_public_signing_key:
+
+``ssh_public_signing_key``
+""""""""""""""""""""""""""
+
+The public key associated with the private key used in signing a commit and tag.
+
+**Required:** ``false``
+
+----
+
+.. _gh_actions-psr-inputs-ssh_private_signing_key:
+
+``ssh_private_signing_key``
+"""""""""""""""""""""""""""
+
+The private key used to sign a commit and tag.
+
+**Required:** ``false``
+
+----
+
+.. _gh_actions-psr-inputs-tag:
+
+``tag``
+"""""""
+
+**Type:** ``Literal["true", "false"]``
+
+Override whether the action should create a version tag in the local repository. This
+option is equivalent to adding either ``--tag`` (on ``true``) or ``--no-tag`` (on
+``false``) to the :ref:`version <cmd-version>` command.
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-tag` options for the :ref:`version <cmd-version>` command
+
+----
+
+.. _gh_actions-psr-inputs-vcs_release:
+
+``vcs_release``
+"""""""""""""""
+
+**Type:** ``Literal["true", "false"]``
+
+Override whether the action should create a release on the VCS. This option is
+equivalent to adding either ``--vcs-release`` (on ``true``) or ``--no-vcs-release``
+(on ``false``) to the :ref:`version <cmd-version>` command.
+
+**Required:** ``false``
+
+.. note::
+ If not set, the default behavior is defined by the :ref:`version <cmd-version>`
+ command and any user :ref:`configurations <config-root>`.
+
+.. seealso::
+
+ - :ref:`cmd-version-option-vcs-release` options for the :ref:`version <cmd-version>`
+ command
+
+----
+
+.. _gh_actions-psr-outputs:
+
+Outputs
+-------
+
+The Python Semantic Release Action also provides outputs that can be used in subsequent
+steps of the workflow. These outputs are used to provide information about the release
+and any actions that were taken.
+
+----
+
+.. _gh_actions-psr-outputs-released:
+
+``released``
+""""""""""""
+
+**Type:** ``Literal["true", "false"]``
+
+A boolean value indicating whether a release was made.
+
+----
+
+.. _gh_actions-psr-outputs-version:
+
+``version``
+"""""""""""
+
+**Type:** ``string``
+
+The newly released SemVer version string if one was made,
+otherwise the current version.
+
+Example: ``1.2.3``
+
+----
+
+.. _gh_actions-psr-outputs-tag:
+
+``tag``
+"""""""
+
+**Type:** ``string``
+
+The Git tag corresponding to the ``version`` output but in
+the tag format dictated by your configuration.
+
+Example: ``v1.2.3``
+
+----
+
+.. _gh_actions-publish:
+
+Python Semantic Release Publish Action
+''''''''''''''''''''''''''''''''''''''
+
+The official `Python Semantic Release Publish Action`_ is a `GitHub Docker Action`_, which
+means at the beginning of the job it will build a Docker image that contains the Python
+Semantic Release package and its dependencies. It will then run the job step inside the
+Docker Container. This is done to ensure that the environment is consistent across all
+GitHub Runners regardless of platform. With this choice, comes some limitations of
+non-configurable options like a pre-defined python version, lack of additional 3rd party
+tools, and an inability to utilize caching.
+
+The primary benefit of using the GitHub Action is that it is easy to set up and use for
+most projects. We handle some additional configuration under the hood, so you don't have
+to handle it yourself. We do however provide a few customization options which are detailed
+individually below.
+
+Most importantly your project's configuration file will be used as normal, as your project
+will be mounted into the container for the action to use.
+
+If you have issues with the action, please open an issue on the
+`python-semantic-release/publish-action`_ repository.
+
+.. _Python Semantic Release Publish Action: https://github.com/marketplace/actions/python-semantic-release-publish
+
+.. seealso::
+
+ - `action.yml`__: the code definition for the publish action
+
+ __ https://github.com/python-semantic-release/publish-action/blob/main/action.yml
+
+.. _gh_actions-publish-inputs:
+
+Inputs
+------
+
+GitHub Action inputs are used for select configuration and provide the necessary
+information to execute the action. The inputs are passed to the action using the
+``with`` keyword in the workflow file. Many inputs will mirror the command line
+options available in the :ref:`publish <cmd-publish>` command and others will be
+specific to adjustment of the action environment. This section outlines each
+supported input and its purpose.
+
+----
+
+.. _gh_actions-publish-inputs-directory:
+
+``directory``
+"""""""""""""
+
+If the project is not at the root of the repository (like in monorepos), you
+can specify a sub-directory to change into before running semantic-release.
+
+**Required:** ``false``
+
+**Default:** ``.``
+
+----
+
+.. _gh_actions-publish-inputs-github_token:
+
+``github_token``
+""""""""""""""""
+
+The GitHub Token is essential for access to your GitHub repository to allow the
+publish of assets to a release. Not only do you need to provide the token as an
+input but you also need to ensure that the token has the correct permissions.
+
+The token should have the following `permissions`_:
+
+* ``contents: write``: Required for modifying a GitHub Release
+
+**Required:** ``true``
+
+.. _permissions: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions
+
+----
+
+.. _gh_actions-publish-inputs-root_options:
+
+``root_options``
+""""""""""""""""
+
+Additional options for the main ``semantic-release`` command, which will come
+before the :ref:`publish <cmd-publish>` subcommand.
+
+ **Example**
+
+ .. code:: yaml
+
+ - uses: python-semantic-release/publish-action@v9.8.9
+ with:
+ root_options: "-vv --noop"
+
+ This configuration would cause the command to be
+ ``semantic-release -vv --noop publish``, which would run the publish command
+ verbosely but in no-operation mode.
+
+**Required:** ``false``
+
+**Default:** ``-v``
+
+.. seealso::
+
+ - :ref:`Options <cmd-main-options>` for the :ref:`semantic-release <cmd-main>`
+ command
+
+----
+
+.. _gh_actions-publish-inputs-tag:
+
+``tag``
+"""""""
+
+**Type:** ``string``
+
+The tag corresponding to the GitHub Release that the artifacts should be published
+to. This option is equivalent to running the command:
+
+.. code:: shell
+
+ semantic-release publish --tag <tag>
+
+Python Semantic Release will automatically determine the latest release if no
+``--tag`` option is provided.
+
+**Required:** ``false``
+
+.. seealso::
+
+ - :ref:`cmd-publish-option-tag` option for the :ref:`publish <cmd-publish>` command
+
+----
+
+.. _gh_actions-publish-outputs:
+
+Outputs
+-------
+
+There are no outputs provided by the Python Semantic Release Publish Action at this time.
+
+.. note::
+ If you would like outputs to be provided by this action, please open an issue
+ on the `python-semantic-release/publish-action`_ repository.
+
+.. _python-semantic-release/publish-action: https://github.com/python-semantic-release/publish-action/issues
+
+----
+
+.. _gh_actions-examples:
+
+Examples
+''''''''
+
+Common Workflow Example
+-----------------------
+
+The following is a common workflow example that uses both the Python Semantic Release Action
+and the Python Semantic Release Publish Action. This workflow will run on every push to the
+``main`` branch and will create a new release upon a successful version determination. If a
+version is released, the workflow will then publish the package to PyPI and upload the package
+to the GitHub Release Assets as well.
.. code:: yaml
- name: Semantic Release
+ name: Continuous Delivery
on:
push:
branches:
- - master
+ - main
jobs:
release:
runs-on: ubuntu-latest
concurrency: release
+
permissions:
id-token: write
contents: write
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
with:
fetch-depth: 0
- - name: Python Semantic Release
- # Adjust tag with desired version if applicable. Version shorthand
- # is NOT available, e.g. vX or vX.X will not work.
+ - name: Action | Semantic Version Release
+ id: release
+ # Adjust tag with desired version if applicable.
uses: python-semantic-release/python-semantic-release@v9.8.9
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
+ git_committer_name: "github-actions"
+ git_committer_email: "actions@users.noreply.github.com"
-``concurrency`` is a `beta feature of GitHub Actions`_ which disallows two or more
-release jobs to run in parallel. This prevents race conditions if there are multiple
-pushes in a short period of time.
+ - name: Publish | Upload package to PyPI
+ uses: pypa/gh-action-pypi-publish@v1
+ if: steps.release.outputs.released == 'true'
-If you would like to use Python Semantic Release to create GitHub Releases against
-your repository, you will need to allow the additional ``contents: write`` permission.
-More information can be found in the `permissions for GitHub Apps documentation`_
+ - name: Publish | Upload to GitHub Release Assets
+ uses: python-semantic-release/publish-action@v9.8.9
+ if: steps.release.outputs.released == 'true'
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ tag: ${{ steps.release.outputs.tag }}
-.. _beta feature of GitHub Actions: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idconcurrency
-.. _permissions for GitHub Apps documentation: https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#contents
+.. important::
+ The `concurrency`_ directive is used on the job to prevent race conditions of more than
+ one release job in the case if there are multiple pushes to ``main`` in a short period
+ of time.
.. warning::
- You must set ``fetch-depth`` to 0 when using ``actions/checkout@v2``, since
- Python Semantic Release needs access to the full history to determine whether
- a release should be made.
+ You must set ``fetch-depth`` to 0 when using ``actions/checkout@v4``, since
+ Python Semantic Release needs access to the full history to build a changelog
+ and at least the latest tags to determine the next version.
.. warning::
The ``GITHUB_TOKEN`` secret is automatically configured by GitHub, with the
- same permissions as the user who triggered the workflow run. This causes
- a problem if your default branch is protected.
+ same permissions role as the user who triggered the workflow run. This causes
+ a problem if your default branch is protected to specific users.
You can work around this by storing an administrator's Personal Access Token
as a separate secret and using that instead of ``GITHUB_TOKEN``. In this
case, you will also need to pass the new token to ``actions/checkout`` (as
the ``token`` input) in order to gain push access.
-Multiple Projects
------------------
+.. _concurrency: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idconcurrency
+
+Version Overrides Example
+-------------------------
+
+In the case where you want to provide multiple command line options to the
+:ref:`version <cmd-version>` command, you provide them through the ``with``
+directive in the workflow file. In this example, we want to force a patch
+version bump, not produce a changelog, and provide specialized build
+metadata. As a regular CLI command, this would look like:
+
+.. code:: shell
+
+ semantic-release version --patch --no-changelog --build-metadata abc123
+
+The equivalent GitHub Action configuration would be:
+
+.. code:: yaml
+
+ # snippet
+
+ - name: Action | Semantic Version Release
+ # Adjust tag with desired version if applicable.
+ uses: python-semantic-release/python-semantic-release@v9.8.9
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ force: patch
+ changelog: false
+ build_metadata: abc123
+
+.. _gh_actions-monorepo:
+
+Actions with Monorepos
+''''''''''''''''''''''
+
+While ``python-semantic-release`` does **NOT** have full monorepo support, if you
+have multiple projects stored within a single repository (or your project is
+not at the root of the repository), you can pass the
+:ref:`directory <gh_actions-psr-inputs-directory>` input to the action to change
+directory before semantic-release execution.
+
+For multiple packages, you would need to run the action multiple times, to release
+each project. The following example demonstrates how to release two projects in
+a monorepo.
-If you have multiple projects stored within a single repository (or your
-project is not at the root of the repository), you can pass the
-``directory`` input. The step can be called multiple times to release
-multiple projects.
+The ``directory`` input directive is also available for the Python Semantic Release
+Publish Action.
.. code:: yaml
diff --git a/docs/automatic-releases/index.rst b/docs/automatic-releases/index.rst
index f0147e337..8fd44b1bf 100644
--- a/docs/automatic-releases/index.rst
+++ b/docs/automatic-releases/index.rst
@@ -16,11 +16,3 @@ Guides
travis
github-actions
cronjobs
-
-.. _automatic-github:
-
-Configuring push to Github
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-In order to push to Github and post the changelog to Github the environment variable
-:ref:`GH_TOKEN <index-creating-vcs-releases>` has to be set. It needs access to the
-``public_repo`` scope for public repositories and ``repo`` for private repositories.
diff --git a/docs/configuration.rst b/docs/configuration.rst
index ee63a99b0..2a8075173 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -575,7 +575,7 @@ Author used in commits in the format ``name <email>``.
``git_committer_name`` and ``git_committer_email`` inputs.
.. seealso::
- - :ref:`github-actions`
+ - :ref:`gh_actions`
**Default:** ``semantic-release <semantic-release>``
diff --git a/docs/github-action.rst b/docs/github-action.rst
deleted file mode 100644
index 24a539f77..000000000
--- a/docs/github-action.rst
+++ /dev/null
@@ -1,139 +0,0 @@
-.. _github-action:
-
-Python Semantic Release GitHub Action
-=====================================
-
-Python Semantic Release is also available as a GitHub action.
-
-In order to use Python Semantic Release to create GitHub Releases against
-your repository, you will need to allow the following permissions for the
-token generated by GitHub for each job:
-
-* id-token: write
-* contents: write
-
-This can be done using the `permissions`_ block in your workflow definition.
-
-.. _permissions: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions
-
-Configuring the action can be done in your workflow's YAML definition.
-The action provides the following inputs:
-
-Tokens
-------
-.. _action-github-token:
-
-``github_token``
-""""""""""""""""
-
-The GitHub token used to push release notes and new commits/tags.
-
-required: false
-
-Custom Users
-------------
-
-.. _action-git-committer-name:
-
-``git_committer_name``
-""""""""""""""""""""""
-
-The name of the account used to commit. If customized, it must be associated with the provided token.
-
-default: ``github-actions``
-
-required: false
-
-.. _action-git-committer-email:
-
-``git_committer_email``
-"""""""""""""""""""""""
-
-The email of the account used to commit. If customized, it must be associated with the provided token.
-
-default: ``actions@github.com>``
-
-required: false
-
-.. _action-ssh-public-signing-key:
-
-``ssh_public_signing_key``
-""""""""""""""""""""""""""
-
-The public key used to verify a commit. If customized, it must be associated with the same account as the provided token.
-
-required: false
-
-.. _action-ssh-private-signing-key:
-
-``ssh_private_signing_key``
-"""""""""""""""""""""""""""
-
-The private key used to verify a commit. If customized, it must be associated with the same account as the provided token.
-
-required: false
-
-Additional Options
-------------------
-
-.. _action-directory:
-
-``directory``
-"""""""""""""
-
-Sub-directory to cd into before running semantic-release
-
-required: false
-
-.. _action-root-options:
-
-``root_options``
-""""""""""""""""""""""
-
-Additional options for the main ``semantic-release`` command. Example: ``-vv --noop``
-
-required: false
-
-default: ``-v``
-
-Command Line Options
---------------------
-
-Other inputs which supply additional command-line options to the
-:ref:`version <cmd-version>` command can be optionally supplied, and have the same
-defaults as their corresponding command line option.
-
-In general, the input for an action corresponding to a command line option has the same
-name, with dashes (``-``) replaced by underscores.
-
-The command line arguments ``--prerelease``, ``--patch``, ``--minor`` and ``--major``
-are mutually exclusive, and are supplied via the ``force`` input.
-
-Flags, which require either ``--<option>`` or ``--no-<option>`` to be passed on the
-command-line, should be specified using the option name (with dashes replaced by
-underscores), and set to the value ``"true"`` to supply ``--<option>`` on the
-command-line, and ``"false"`` to specify ``--no-<option>``.
-Any other values are not accepted.
-
-The flag ``--as-prerelease`` is uniquely provided as just the ``prerelease`` flag value.
-This is for compatibility reasons.
-
-For command line options requiring a value, set the input to the required value.
-
-For example, to specify ``--patch --no-push --build-metadata abc123``, you should
-provide the following inputs:
-
-.. code:: yaml
-
- ---
-
- # ... the rest of the workflow
- - name: Python Semantic Release
- # Adjust tag with desired version if applicable. Version shorthand
- # is NOT available, e.g. vX or vX.X will not work.
- uses: python-semantic-release/python-semantic-release@v9.8.9
- with:
- # ... other options
- force: "patch"
- push: "false"
- build_metadata: "abc123"
diff --git a/docs/index.rst b/docs/index.rst
index b51b47128..643de97e9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -63,7 +63,6 @@ Documentation Contents
Changelog Templates <changelog_templates>
Multibranch Releases <multibranch_releases>
automatic-releases/index
- Python Semantic Release GitHub Action <github-action>
troubleshooting
contributing
contributors
@@ -165,19 +164,28 @@ Creating VCS Releases
You can set up Python Semantic Release to create Releases in your remote version
control system, so you can publish assets and release notes for your project.
-In order to do so, you will need to place an authentication token in the appropriate
-environment variable so that Python Semantic Release can authenticate with the remote
-VCS to push tags, create releases, or upload files.
-You should use the appropriate steps below to set this up.
+In order to do so, you will need to place an authentication token in the
+appropriate environment variable so that Python Semantic Release can authenticate
+with the remote VCS to push tags, create releases, or upload files.
GitHub (``GH_TOKEN``)
"""""""""""""""""""""
-Use a personal access token from GitHub. See :ref:`automatic-github` for
-usage. This token should be stored in the ``GH_TOKEN`` environment variable
+For local publishing to GitHub, you should use a personal access token and
+store it in your environment variables. Specify the name of the environment
+variable in your configuration setting :ref:`remote.token <config-remote-token>`.
+The default is ``GH_TOKEN``.
-To generate a token go to https://github.com/settings/tokens
-and click on *Personal access token*.
+To generate a token go to https://github.com/settings/tokens and click on
+"Generate new token".
+
+For Personal Access Token (classic), you will need the ``repo`` scope to write
+(ie. push) to the repository.
+
+For fine-grained Personal Access Tokens, you will need the `contents`__
+permission.
+
+__ https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens#repository-permissions-for-contents
GitLab (``GITLAB_TOKEN``)
"""""""""""""""""""""""""
diff --git a/scripts/bump_version_in_docs.py b/scripts/bump_version_in_docs.py
index ab7086f14..155444f12 100644
--- a/scripts/bump_version_in_docs.py
+++ b/scripts/bump_version_in_docs.py
@@ -32,7 +32,6 @@ def update_github_actions_example(filepath: Path, new_version: str) -> None:
print("NEW_VERSION environment variable is not set")
exit(1)
- update_github_actions_example(DOCS_DIR / "github-action.rst", new_version)
update_github_actions_example(
DOCS_DIR / "automatic-releases" / "github-actions.rst", new_version
)
From d46596a99945dd813d1f44d9097668051697c463 Mon Sep 17 00:00:00 2001
From: codejedi365 <codejedi365@users.noreply.github.com>
Date: Fri, 27 Sep 2024 17:41:17 -0600
Subject: [PATCH 2/7] ci(pr-workflow): limit which workflow files trigger full
testing (#1033)
---
.github/workflows/pr.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index e412f4b3f..1e79bb35c 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -27,7 +27,7 @@ jobs:
- .dockerignore
- scripts/**
ci:
- - .github/workflows/**
+ - .github/workflows/pr.yml
docs:
- docs/**
- README.rst
From c7ad31184f83e33115102fbccb5b2345e36297d5 Mon Sep 17 00:00:00 2001
From: codejedi365 <codejedi365@gmail.com>
Date: Fri, 27 Sep 2024 22:59:51 -0600
Subject: [PATCH 3/7] ci(main-wkflow): remove beautify job & enforce style via
linter
I am removing the beautify job because it causes more issues with rapid PR
completion as it will error if two PRs are merged within the test window.
Now that the test window is around 12 minutes, its easy to cause an issue.
Plus I am not quite convinced that we should be giving it write access to
the repo to modify code arbitrarily.
---
.github/workflows/main.yml | 61 +++++++++-----------------------------
1 file changed, 14 insertions(+), 47 deletions(-)
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 5fbec3078..c4828007d 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -89,75 +89,42 @@ jobs:
steps:
- uses: actions/checkout@v4
- - name: Set up Python 3.8
+ - name: Set up Python 3.12
uses: actions/setup-python@v5
with:
- python-version: 3.8
+ python-version: 3.12
- name: Install mypy & dev packages
run: |
python -m pip install --upgrade pip setuptools wheel
- python -m pip install ".[dev, mypy]"
+ python -m pip install .[dev,mypy]
- - name: ruff
+ - name: Lint | Ruff Evaluation
+ id: lint
run: |
- python -m ruff check . \
+ python -m ruff check \
--config pyproject.toml \
--output-format=full \
--exit-non-zero-on-fix
- - name: mypy
+ - name: Type-Check | MyPy Evaluation
+ id: type-check
+ if: ${{ always() && steps.lint.outcome != 'skipped' }}
run: |
python -m mypy --ignore-missing-imports semantic_release
- beautify:
- name: Beautify
- runs-on: ubuntu-latest
- concurrency: push
- needs: [test, lint]
- outputs:
- new_sha: ${{ steps.sha.outputs.SHA }}
- permissions:
- id-token: write
- contents: write
-
- steps:
- - name: Set up Python 3.9
- uses: actions/setup-python@v5
- with:
- python-version: 3.9
-
- - name: Checkout repository
- uses: actions/checkout@v4
-
- - name: Install Ruff
+ - name: Format-Check | Ruff Evaluation
+ id: format-check
+ if: ${{ always() && steps.type-check.outcome != 'skipped' }}
run: |
- python -m pip install --upgrade pip setuptools wheel
- python -m pip install ".[dev]"
+ python -m ruff format --check --config pyproject.toml
- - name: Format
- run: |
- python -m ruff format .
-
- - name: Commit and push changes
- uses: github-actions-x/commit@v2.9
- with:
- github-token: ${{ secrets.GITHUB_TOKEN }}
- commit-message: "style: beautify ${{ github.sha }}"
- name: github-actions
- email: action@github.com
-
- - name: Get new SHA
- id: sha
- run: |
- new_sha=$(git rev-parse HEAD)
- echo "SHA=$new_sha" >> $GITHUB_OUTPUT
release:
name: Semantic Release
runs-on: ubuntu-latest
concurrency: push
- needs: [test, lint, beautify]
+ needs: [test, lint]
if: github.repository == 'python-semantic-release/python-semantic-release'
environment:
name: pypi
From 87765c254a8c024ac97d8a13aff5953012bac77f Mon Sep 17 00:00:00 2001
From: codejedi365 <codejedi365@gmail.com>
Date: Fri, 27 Sep 2024 23:01:38 -0600
Subject: [PATCH 4/7] ci(pr-wkflow): add formatting enforcement to lint job to
match main
---
.github/workflows/pr.yml | 25 ++++++++++++++++++-------
1 file changed, 18 insertions(+), 7 deletions(-)
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 1e79bb35c..7189824b7 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -191,24 +191,35 @@ jobs:
steps:
- uses: actions/checkout@v4
- - name: Set up Python 3.8
+ - name: Set up Python 3.12
uses: actions/setup-python@v5
with:
- python-version: 3.8
+ python-version: 3.12
- name: Install mypy & dev packages
run: |
python -m pip install --upgrade pip setuptools wheel
- python -m pip install ".[dev, mypy]"
+ python -m pip install .[dev,mypy]
- - name: ruff
+ - name: Lint | Ruff Evaluation
+ id: lint
run: |
- python -m ruff check . \
+ python -m ruff check \
+ --config pyproject.toml \
--output-format=full \
--exit-non-zero-on-fix
- - name: mypy
- run: python -m mypy --ignore-missing-imports semantic_release
+ - name: Type-Check | MyPy Evaluation
+ id: type-check
+ if: ${{ always() && steps.lint.outcome != 'skipped' }}
+ run: |
+ python -m mypy --ignore-missing-imports semantic_release
+
+ - name: Format-Check | Ruff Evaluation
+ id: format-check
+ if: ${{ always() && steps.type-check.outcome != 'skipped' }}
+ run: |
+ python -m ruff format --check --config pyproject.toml
commitlint:
From acce60663d3876c00a418b430187ed8d70122544 Mon Sep 17 00:00:00 2001
From: codejedi365 <codejedi365@users.noreply.github.com>
Date: Sat, 28 Sep 2024 00:02:21 -0600
Subject: [PATCH 5/7] ci(main-wkflow): add file type filter to regulate testing
jobs (#1037)
---
.github/workflows/main.yml | 58 ++++++++++++++++++++++++++++++++++++++
1 file changed, 58 insertions(+)
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index c4828007d..a556f77d9 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -9,9 +9,64 @@ on:
- "pre/*"
jobs:
+
+ eval-changes:
+ name: Evaluate changes
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Evaluate | Check specific file types for changes
+ id: changed-files
+ uses: tj-actions/changed-files@v45.0.2
+ with:
+ files_yaml: |
+ build:
+ - MANIFEST.in
+ - Dockerfile
+ - .dockerignore
+ - scripts/**
+ ci:
+ - .github/workflows/main.yml
+ docs:
+ - docs/**
+ - README.rst
+ - AUTHORS.rst
+ - CONTRIBUTING.rst
+ - CHANGELOG.rst
+ src:
+ - semantic_release/**
+ - pyproject.toml
+ tests:
+ - tests/**
+
+ - name: Evaluate | Detect if any of the combinations of file sets have changed
+ id: all-changes
+ run: |
+ printf '%s\n' "any_changed=false" >> $GITHUB_OUTPUT
+ if [ "${{ steps.changed-files.outputs.build_any_changed }}" == "true" ] || \
+ [ "${{ steps.changed-files.outputs.ci_any_changed }}" == "true" ] || \
+ [ "${{ steps.changed-files.outputs.docs_any_changed }}" == "true" ] || \
+ [ "${{ steps.changed-files.outputs.src_any_changed }}" == "true" ] || \
+ [ "${{ steps.changed-files.outputs.tests_any_changed }}" == "true" ]; then
+ printf '%s\n' "any_changed=true" >> $GITHUB_OUTPUT
+ fi
+
+ outputs:
+ any-file-changes: ${{ steps.all-changes.outputs.any_changed }}
+ build-changes: ${{ steps.changed-files.outputs.build_any_changed }}
+ ci-changes: ${{ steps.changed-files.outputs.ci_any_changed }}
+ doc-changes: ${{ steps.changed-files.outputs.docs_any_changed }}
+ src-changes: ${{ steps.changed-files.outputs.src_any_changed }}
+ test-changes: ${{ steps.changed-files.outputs.tests_any_changed }}
+
+
test:
name: Python ${{ matrix.python-version }} on ${{ matrix.os }} tests
runs-on: ${{ matrix.os }}
+ needs: eval-changes
+ if: ${{ needs.eval-changes.outputs.src-changes == 'true' || needs.eval-changes.outputs.test-changes == 'true' || needs.eval-changes.outputs.ci-changes == 'true' }}
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
@@ -83,7 +138,10 @@ jobs:
with:
report_paths: ./tests/reports/*.xml
+
lint:
+ needs: eval-changes
+ if: ${{ needs.eval-changes.outputs.any-file-changes == 'true' }}
runs-on: ubuntu-latest
steps:
From 6a5d35d0d9124d6a6ee7910711b4154b006b8773 Mon Sep 17 00:00:00 2001
From: codejedi365 <codejedi365@users.noreply.github.com>
Date: Sat, 28 Sep 2024 00:10:26 -0600
Subject: [PATCH 6/7] feat(github-actions): add `is_prerelease` output to the
version action (#1038)
* test(github-actions): add test to ensure `is_prerelease` is a action output
* docs(github-actions): add description of new `is_prerelease` output for version action
---
action.yml | 4 ++++
docs/automatic-releases/github-actions.rst | 11 ++++++++++
semantic_release/cli/github_actions_output.py | 17 +++++++++-------
.../cli/test_github_actions_output.py | 20 ++++++++++++++-----
4 files changed, 40 insertions(+), 12 deletions(-)
diff --git a/action.yml b/action.yml
index dd3c1547f..726324672 100644
--- a/action.yml
+++ b/action.yml
@@ -102,6 +102,10 @@ inputs:
Build metadata to append to the new version
outputs:
+ is_prerelease:
+ description: |
+ "true" if the version is a prerelease, "false" otherwise
+
released:
description: |
"true" if a release was made, "false" otherwise
diff --git a/docs/automatic-releases/github-actions.rst b/docs/automatic-releases/github-actions.rst
index 36bf58541..77295a248 100644
--- a/docs/automatic-releases/github-actions.rst
+++ b/docs/automatic-releases/github-actions.rst
@@ -410,6 +410,17 @@ and any actions that were taken.
----
+.. _gh_actions-psr-outputs-is_prerelease:
+
+``is_prerelease``
+""""""""""""""""
+
+**Type:** ``Literal["true", "false"]``
+
+A boolean value indicating whether the released version is a prerelease.
+
+----
+
.. _gh_actions-psr-outputs-released:
``released``
diff --git a/semantic_release/cli/github_actions_output.py b/semantic_release/cli/github_actions_output.py
index 427a8bf2c..74cd0f23d 100644
--- a/semantic_release/cli/github_actions_output.py
+++ b/semantic_release/cli/github_actions_output.py
@@ -12,7 +12,9 @@ class VersionGitHubActionsOutput:
OUTPUT_ENV_VAR = "GITHUB_OUTPUT"
def __init__(
- self, released: bool | None = None, version: Version | None = None
+ self,
+ released: bool | None = None,
+ version: Version | None = None,
) -> None:
self._released = released
self._version = version
@@ -29,9 +31,7 @@ def released(self, value: bool) -> None:
@property
def version(self) -> Version | None:
- if self._version is None:
- return None
- return self._version
+ return self._version if self._version is not None else None
@version.setter
def version(self, value: Version) -> None:
@@ -41,9 +41,11 @@ def version(self, value: Version) -> None:
@property
def tag(self) -> str | None:
- if self._version is None:
- return None
- return self._version.as_tag()
+ return self.version.as_tag() if self.version is not None else None
+
+ @property
+ def is_prerelease(self) -> bool | None:
+ return self.version.is_prerelease if self.version is not None else None
def to_output_text(self) -> str:
missing = set()
@@ -61,6 +63,7 @@ def to_output_text(self) -> str:
"released": str(self.released).lower(),
"version": str(self.version),
"tag": self.tag,
+ "is_prerelease": str(self.is_prerelease).lower(),
}
return str.join("", [f"{key}={value!s}\n" for key, value in outputs.items()])
diff --git a/tests/unit/semantic_release/cli/test_github_actions_output.py b/tests/unit/semantic_release/cli/test_github_actions_output.py
index 9bac1b675..3d16fb78a 100644
--- a/tests/unit/semantic_release/cli/test_github_actions_output.py
+++ b/tests/unit/semantic_release/cli/test_github_actions_output.py
@@ -14,19 +14,28 @@
from pathlib import Path
+@pytest.mark.parametrize(
+ "version, is_prerelease",
+ [
+ ("1.2.3", False),
+ ("1.2.3-alpha.1", True),
+ ],
+)
@pytest.mark.parametrize("released", (True, False))
-def test_version_github_actions_output_format(released: bool):
- version_str = "1.2.3"
+def test_version_github_actions_output_format(
+ released: bool, version: str, is_prerelease: bool
+):
expected_output = dedent(
f"""\
released={'true' if released else 'false'}
- version={version_str}
- tag=v{version_str}
+ version={version}
+ tag=v{version}
+ is_prerelease={'true' if is_prerelease else 'false'}
"""
)
output = VersionGitHubActionsOutput(
released=released,
- version=Version.parse(version_str),
+ version=Version.parse(version),
)
# Evaluate (expected -> actual)
@@ -63,6 +72,7 @@ def test_version_github_actions_output_writes_to_github_output_if_available(
# Evaluate (expected -> actual)
assert version_str == action_outputs["version"]
assert str(True).lower() == action_outputs["released"]
+ assert str(False).lower() == action_outputs["is_prerelease"]
def test_version_github_actions_output_no_error_if_not_in_gha(
From fd8c509df1f16daf3f71a9a6fac49247017017b2 Mon Sep 17 00:00:00 2001
From: semantic-release <semantic-release>
Date: Sat, 28 Sep 2024 06:15:48 +0000
Subject: [PATCH 7/7] 9.9.0
Automatically generated by python-semantic-release
---
CHANGELOG.md | 28 ++++++++++++++++++++++
docs/automatic-releases/github-actions.rst | 10 ++++----
pyproject.toml | 2 +-
semantic_release/__init__.py | 2 +-
4 files changed, 35 insertions(+), 7 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9fc9c6892..14720ceea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,33 @@
# CHANGELOG
+## v9.9.0 (2024-09-28)
+
+### Documentation
+
+* docs(github-actions): clarify & consolidate GitHub Actions usage docs (#1011)
+
+ Resolves: #907
+
+* chore(scripts): remove non-existant file from version bump script
+
+* docs(automatic-releases): drop extrenous github push configuration
+
+* docs(homepage): remove link to old github config & update token scope config
+
+* docs(github-actions): expand descriptions & clarity of actions configs
+
+* docs(github-actions): add configuration & description of publish action
+
+* docs(github-actions): revert removal of namespace prefix from examples ([`2135c68`](https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3))
+
+### Feature
+
+* feat(github-actions): add `is_prerelease` output to the version action (#1038)
+
+* test(github-actions): add test to ensure `is_prerelease` is a action output
+
+* docs(github-actions): add description of new `is_prerelease` output for version action ([`6a5d35d`](https://github.com/python-semantic-release/python-semantic-release/commit/6a5d35d0d9124d6a6ee7910711b4154b006b8773))
+
## v9.8.9 (2024-09-27)
### Documentation
diff --git a/docs/automatic-releases/github-actions.rst b/docs/automatic-releases/github-actions.rst
index 77295a248..c603b47e7 100644
--- a/docs/automatic-releases/github-actions.rst
+++ b/docs/automatic-releases/github-actions.rst
@@ -312,7 +312,7 @@ before the :ref:`version <cmd-version>` subcommand.
.. code:: yaml
- - uses: python-semantic-release/python-semantic-release@v9.8.9
+ - uses: python-semantic-release/python-semantic-release@v9.9.0
with:
root_options: "-vv --noop"
@@ -650,7 +650,7 @@ to the GitHub Release Assets as well.
- name: Action | Semantic Version Release
id: release
# Adjust tag with desired version if applicable.
- uses: python-semantic-release/python-semantic-release@v9.8.9
+ uses: python-semantic-release/python-semantic-release@v9.9.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
git_committer_name: "github-actions"
@@ -710,7 +710,7 @@ The equivalent GitHub Action configuration would be:
- name: Action | Semantic Version Release
# Adjust tag with desired version if applicable.
- uses: python-semantic-release/python-semantic-release@v9.8.9
+ uses: python-semantic-release/python-semantic-release@v9.9.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
force: patch
@@ -738,13 +738,13 @@ Publish Action.
.. code:: yaml
- name: Release Project 1
- uses: python-semantic-release/python-semantic-release@v9.8.9
+ uses: python-semantic-release/python-semantic-release@v9.9.0
with:
directory: ./project1
github_token: ${{ secrets.GITHUB_TOKEN }}
- name: Release Project 2
- uses: python-semantic-release/python-semantic-release@v9.8.9
+ uses: python-semantic-release/python-semantic-release@v9.9.0
with:
directory: ./project2
github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/pyproject.toml b/pyproject.toml
index d70c1ecc2..d8d961e96 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "python-semantic-release"
-version = "9.8.9"
+version = "9.9.0"
description = "Automatic Semantic Versioning for Python projects"
requires-python = ">=3.8"
license = { text = "MIT" }
diff --git a/semantic_release/__init__.py b/semantic_release/__init__.py
index 30801902c..3fd3ac5dd 100644
--- a/semantic_release/__init__.py
+++ b/semantic_release/__init__.py
@@ -24,7 +24,7 @@
tags_and_versions,
)
-__version__ = "9.8.9"
+__version__ = "9.9.0"
__all__ = [
"CommitParser",