Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Migrating from Python Semantic Release v7

Python Semantic Release 8.0.0 introduced a number of breaking changes. The internals have been changed significantly to better support highly-requested features and to streamline the maintenance of the project.

As a result, certain things have been removed, reimplemented differently, or now exhibit different behavior to earlier versions of Python Semantic Release. This page is a guide to help projects to `pip install python-semantic-release>=8.0.0` with fewer surprises.

## Python Semantic Release GitHub Action

### GitHub Action no longer publishes artifacts to PyPI or GitHub Releases

Python Semantic Release no longer uploads distributions to PyPI - see Repurposing of version and publish commands. If you are using Python Semantic Release to publish release notes and artifacts to GitHub releases, there is a new GitHub Action upload-to-gh-release which will perform this action for you.

This means the following workflows perform the same actions, and if you are using the former, you will need to modify your workflow to include the steps in the latter.

This workflow is written to use Python Semantic Release v7.33.5:

    ---
    name: Semantic Release

    on:
      push:
        branches:
          - main

    jobs:
      release:
        runs-on: ubuntu-latest
        concurrency: release

        steps:
        - uses: actions/checkout@v3
          with:
            fetch-depth: 0

        # This action uses Python Semantic Release v7
        - name: Python Semantic Release
          uses: python-semantic-release/python-semantic-release@v7.33.5
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            repository_username: __token__
            repository_password: ${{ secrets.PYPI_TOKEN }}

The following workflow achieves the same result using Python Semantic Release v8, the upload-to-gh-release GitHub Action, and the pypa/gh-action-pypi-publish GitHub Action:

    ---
    name: Semantic Release

    on:
      push:
        branches:
          - main

    jobs:
      release:
        runs-on: ubuntu-latest
        concurrency: release
        permissions:
          id-token: write

        steps:
        - uses: actions/checkout@v3
          with:
            fetch-depth: 0

        # This action uses Python Semantic Release v8
        - name: Python Semantic Release
          id: release
          uses: python-semantic-release/python-semantic-release@v8.7.0
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}

        - name: Publish package distributions to PyPI
          uses: pypa/gh-action-pypi-publish@v1
          # NOTE: DO NOT wrap the conditional in ${{ }} as it will always evaluate to true.
          # See https://github.com/actions/runner/issues/1173
          if: steps.release.outputs.released == 'true'

        - name: Publish package distributions to GitHub Releases
          uses: python-semantic-release/upload-to-gh-release@v8.7.0
          if: steps.release.outputs.released == 'true'
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}

### Removal of `pypi_token`, `repository_username` and `repository_password` inputs

Since the library no longer supports publishing to PyPI, the `pypi_token`, `repository_username` and `repository_password` inputs of the GitHub action have all been removed. See the above section for how to publish to PyPI using the official GitHub Action from the Python Packaging Authority (PyPA).

### Rename `additional_options` to `root_options`

Because the purposes of the semantic-release version and semantic-release publish commands have changed, the GitHub action now performs both commands in sequence. For this reason, and because the usage of the CLI has changed, `additional_options` has been renamed to `root_options` to reflect the fact that the options are for the main semantic-release command group.

## Commands

### Repurposing of `version` and `publish` commands

Python Semantic Release’s primary purpose is to enable automation of correct semantic versioning for software projects. Over the years, this automation has been extended to include other actions such as building/publishing the project and its artifacts to artefact repositories, creating releases in remote version control systems, and writing changelogs.

In Python Semantic Release <8.0.0, the `publish` command was a one-stop-shop for performing every piece of automation provided. This has been changed - the `version` command now handles determining the next version, applying the changes to the project metadata according to the configuration, writing a changelog, and committing/pushing changes to the remote Git repository. It also handles creating a release in the remote VCS. It does not publish software artifacts to remote repositories such as PyPI; the rationale behind this decision is simply that under the hood, Python Semantic Release used twine to upload artifacts to package indexes such as PyPI, and it’s recommended to use twine directly via the command-line. From the twine documentation:

> Twine is a command-line tool for interacting with PyPI securely over HTTPS.

As a result Python Semantic Release no longer depends on twine internals.

The `publish` command now handles publishing software artifacts to releases in the remote version control system.

To achieve a similar flow of logic such as

> 1. Determine the next version

> 2. Write this version to the configured metadata locations

> 3. Write the changelog

> 4. Push the changes to the metadata and changelog to the remote repository

> 5. Create a release in the remote version control system

> 6. Build a wheel

> 7. Publish the wheel to PyPI

> 8. Publish the distribution artifacts to the release in the remote VCS

You should run:

    semantic-release version
    twine upload dist/*  # or whichever path your distributions are placed in
    semantic-release publish

With steps 1-6 being handled by the semantic-release version command, step 7 being left to the developer to handle, and lastly step 8 to be handled by the semantic-release publish command.

### Removal of `-D/--define` command-line option

It is no longer possible to override arbitrary configuration values using the `-D`/ `--define` option. You should provide the appropriate values via a configuration file using -c/--config [FILE] or via the available command-line options.

This simplifies the command-line option parsing significantly and is less error-prone, which has resulted in previous issues (e.g. #600) with overrides on the command-line. Some of the configuration values expected by Python Semantic Release use complex data types such as lists or nested structures, which would be tedious and error-prone to specify using just command-line options.

### Removal of CI verifications

Prior to v8, Python Semantic Release would perform some prerequisite verification of environment variables before performing any version changes using the `publish` command. It’s not feasible for Python Semantic Release to verify any possible CI environment fully, and these checks were only triggered if certain environment variables were set - they wouldn’t fail locally.

These checks previously raised :py:class:`semantic_release.CiVerificationError`, and were the only place in which this custom exception was used. Therefore, this exception has also been removed from Python Semantic Release in v8.

If you were relying on this functionality, it’s recommended that you add the following shell commands before invoking `semantic-release` to verify your environment:

Note

In the following, $RELEASE_BRANCH refers to the git branch against which you run your releases using Python Semantic Release. You will need to ensure it is set properly (e.g. via `export RELEASE_BRANCH=main` and/or replace the variable with the branch name you want to verify the CI environment for.

#### Travis

Condition: environment variable `TRAVIS=true`

Replacement:

    if ! [[
          $TRAVIS_BRANCH == $RELEASE_BRANCH  && \
          $TRAVIS_PULL_REQUEST == 'false'
        ]]; then
      exit 1
    fi

#### Semaphore

Condition: environment variable `SEMAPHORE=true`

Replacement:

    if ! [[
            $BRANCH_NAME == $RELEASE_BRANCH && \
            $SEMAPHORE_THREAD_RESULT != 'failed' && \
            -n $PULL_REQUEST_NUMBER
        ]]; then
      exit 1
    fi

#### Frigg

Condition: environment variable `FRIGG=true`

Replacement:

    if ! [[
          $FRIGG_BUILD_BRANCH == $RELEASE_BRANCH && \
          -n $FRIGG_PULL_REQUEST
        ]]; then
      exit 1
    fi

#### Circle CI

Condition: environment variable `CIRCLECI=true`

Replacement:

    if ! [[
          $CIRCLE_BRANCH == $RELEASE_BRANCH && \
          -n $CI_PULL_REQUEST
        ]]; then
      exit 1
    fi

#### GitLab CI

Condition: environment variable `GITLAB_CI=true`

Replacement:

    if ! [[ $CI_COMMIT_REF_NAME == $RELEASE_BRANCH ]]; then
      exit 1
    fi

Condition: environment variable `BITBUCKET_BUILD_NUMBER` is set

Replacement:

    if ! [[
          $BITBUCKET_BRANCH == $RELEASE_BRANCH && \
          -n $BITBUCKET_PR_ID
        ]]; then
      exit 1
    fi

#### Jenkins

Condition: environment variable `JENKINS_URL` is set

Replacement:

    if [[ -z $BRANCH_NAME ]]; then
      BRANCH_NAME=$BRANCH_NAME
    elif [[ -z $GIT_BRANCH ]]; then
      BRANCH_NAME=$GIT_BRANCH
    fi

    if ! [[
          $BRANCH_NAME == $RELEASE_BRANCH && \
          -n $CHANGE_ID
        ]]; then
      exit 1
    fi

### Removal of Build Status Checking

Prior to v8, Python Semantic Release contained a configuration option, `check_build_status`, which would attempt to prevent a release being made if it was possible to identify that a corresponding build pipeline was failing. For similar reasons to those motivating the removal of CI Checks, this feature has also been removed.

If you are leveraging this feature in Python Semantic Release v7, the following bash commands will replace the functionality, and you can add these to your pipeline. You will need to install `jq` and `curl` to run these commands; they can be easily installed through your system’s package manager, for example on Ubuntu:

    sudo apt update && sudo apt upgrade
    sudo apt install -y curl jq

On Windows, you can refer to the installation guide for jq, and if `curl` is not already installed, you can download it from the curl website

#### GitHub

    export RESP="$(
      curl \
         -H "Authorization: token $GITHUB_TOKEN" \
         -fSsL https://$GITHUB_API_DOMAIN/repos/$REPO_OWNER/$REPO_NAME/commits/$(git rev-parse HEAD)/status || exit 1
    )"

    if [ $(jq -r '.state' <<< "$RESP") != "success" ]; then
       echo "Build status is not success" >&2
       exit 1
    fi

Note that `$GITHUB_API_DOMAIN` is typically `api.github.com` unless you are using GitHub Enterprise with a custom domain name.

#### Gitea

    export RESP="$(
      curl \
         -H "Authorization: token $GITEA_TOKEN" \
         -fSsL https://$GITEA_DOMAIN/repos/$REPO_OWNER/$REPO_NAME/statuses/$(git rev-parse HEAD) || exit 1
    )"

    if [ $(jq -r '.state' <<< "$RESP") != "success" ]; then
       echo "Build status is not success" >&2
       exit 1
    fi

#### Gitlab

     export RESP="$(
       curl \
          -H "Authorization: token $GITLAB_TOKEN" \
          -fSsL https://$GITLAB_DOMAIN/api/v4/projects/$PROJECT_ID/repository/commits/$(git rev-parse HEAD)/statuses
     )"

     for line in $(jq -r '.[] | [.name, .status, .allow_failure] | join("|")' <<<"$RESP"); do
       IFS="|" read -r job_name job_status allow_failure <<<"$line"

       if [ "$job_status" == "pending" ]; then
          echo "job $job_name is pending" >&2
          exit 1
       elif [ "$job_status" == "failed" ] && [ ! "$allow_failure" == "true" ]; then
          echo "job $job_name failed" >&2
          exit 1
       fi
    done

### Multibranch releases

Prior to v8, Python Semantic Release would perform `git checkout` to switch to your configured release branch and determine if a release would need to be made. In v8 this has been changed - you must manually check out the branch which you would like to release against, and if you would like to create releases against this branch you must also ensure that it belongs to a release group.

### `changelog` command

A new option, --post-to-release-tag [TAG] has been added. If you omit this argument on the command line then the changelog rendering process, which is described in more detail at Custom Changelogs, will be triggered, but the new changelog will not be posted to any release. If you use this new command-line option, it should be set to a tag within the remote which has a corresponding release. For example, to update the changelog and post it to the release corresponding to the tag `v1.1.4`, you should run:

    semantic-release changelog --post-to-release-tag v1.1.4

### Changelog customization

A number of options relevant to customizing the changelog have been removed. This is because Python Semantic Release now supports authoring a completely custom Jinja template with the contents of your changelog. Historically, the number of options added to Python Semantic Release in order to allow this customization has grown significantly; it now uses templates in order to fully open up customizing the changelog’s appearance.

## Configuration

The configuration structure has been completely reworked, so you should read Configuration carefully during the process of upgrading to v8+. However, some common pitfalls and potential sources of confusion are summarized here.

### `setup.cfg` is no longer supported

Python Semantic Release no longer supports configuration via `setup.cfg`. This is because the Python ecosystem is centering around `pyproject.toml` as universal tool and project configuration file, and TOML allows expressions via configuration, such as the mechanism for declaring configuration via environment variables, which introduce much greater complexity to support in the otherwise equivalent `ini`-format configuration.

You can use semantic-release generate-config to generate new-format configuration that can be added to `pyproject.toml`, and adjust the default settings according to your needs.

Warning

If you don’t already have a `pyproject.toml` configuration file, `pip` can change its behavior once you add one, as a result of PEP-517. If you find that this breaks your packaging, you can add your Python Semantic Release configuration to a separate file such as `semantic-release.toml`, and use the –config option to reference this alternative configuration file.

More detail about this issue can be found in this pip issue.

### Commit parser options

Options such as `major_emoji`, `parser_angular_patch_types` or `parser_angular_default_level_bump` have been removed. Instead, these have been replaced with a single set of recognized commit parser options, `allowed_tags`, `major_tags`, `minor_tags`, and `patch_tags`, though the interpretation of these is up to the specific parsers in use. You can read more detail about using commit parser options in commit_parser_options, and if you need to parse multiple commit styles for a single project it’s recommended that you create a parser following Custom Parsers that is tailored to the specific needs of your project.

### `version_variable`

This option has been renamed to version_variables as it refers to a list of variables which can be updated.

### `version_pattern`

This option has been removed. It’s recommended to use an alternative tool to perform substitution using arbitrary regular expressions, such as `sed`. You can always use Python Semantic Release to identify the next version to be created for a project and store this in an environment variable like so:

    export VERSION=$(semantic-release version --print)

### `version_toml`

This option will no longer accept a string or comma-separated string of version locations to be updated in TOML files. Instead, you must supply a `List[str]`. For existing configurations using a single location in this option, you can simply wrap the value in `[]`:

    # Python Semantic Release v7 configuration
    [tool.semantic_release]
    version_toml = "pyproject.toml:tool.poetry.version"

    # Python Semantic Release v8 configuration
    [tool.semantic_release]
    version_toml = ["pyproject.toml:tool.poetry.version"]

### `tag_format`

This option has the same effect as it did in Python Semantic Release prior to v8, but Python Semantic Release will now verify that it has a `{version}` format key and raise an error if this is not the case.

### `upload_to_release`

This option has been renamed to upload_to_vcs_release.

## Custom Commit Parsers

Previously, a custom commit parser had to satisfy the following criteria:

> - It should be `import`-able from the virtual environment where the `semantic-release` is run

> - It should be a function which accepts the commit message as its only argument and returns a `semantic_release.history.parser_helpers.ParsedCommit` if the commit is parsed successfully, or raise a `semantic_release.UnknownCommitMessageStyleError` if parsing is unsuccessful.

It is still possible to implement custom commit parsers, but the interface for doing so has been modified with stronger support for Python type annotations and broader input provided to the parser to enable capturing more information from each commit, such as the commit’s date and author, if desired. A full guide to implementing a custom commit parser can be found at Custom Parsers.