Setting up version numbering

Create a variable set to the current version number. This could be anywhere in your project, for example setup.py:

from setuptools import setup
__version__ = "0.0.0"
setup(


   name="my-package",


   version=__version__,


   # And so on...
)

Python Semantic Release is configured using setup.cfg or pyproject.toml. Set version_variable to the location of your version variable inside any Python file:

setup.cfg:

[semantic_release]
version_variable = setup.py:__version__

pyproject.toml:

[tool.semantic_release]
version_variable = "setup.py:__version__"

SEE ALSO:

Setting up commit parsing

We rely on commit messages to detect when a version bump is needed. By default, Python Semantic Release uses the Angular style. You can find out more about this on Parsing of commit logs.

SEE ALSO:

Setting up the changelog

If you already have a CHANGELOG.md, you will need to insert a placeholder tag so we know where to write new versions:

<!--next-version-placeholder-->

If you don't have a changelog file then one will be set up like this automatically.

SEE ALSO:

Releasing on GitHub / GitLab

Some options and environment variables need to be set in order to push release notes and new versions to GitHub / GitLab:

Distributing release on PyPI or custom repository

Unless you disable upload_to_repository (or upload_to_pypi), Python Semantic Release will publish new versions to Pypi. Customization is supported using a ~/.pypirc file or config setting and environment variables for username and password/token or a combination of both. Publishing is done using twine.

Commands

semantic-release changelog

Print the changelog to stdout.

If the option --post is used and there is an authentication token configured for your vcs provider (GH_TOKEN for GitHub, GL_TOKEN for GitLab, GITEA_TOKEN for Gitea), the changelog will be posted there too.

semantic-release version

Figure out the new version number, update and commit it, and create a tag.

This will not push anything to any remote. All changes are local.

semantic-release print-version

Print to standard output the new version number.

If the option --current is used, it will display the current version number.

It can be used to retrieve the next version number in a shell script during the build, before running the effective release, ie. to rename a distribution binary with the effective version:

VERSION=$(semantic-release print-version)

semantic-release publish

Publish will do a sequence of things:

Some of these steps may be disabled based on your configuration.

Common Options

Every command understands these flags:

--patch

Force a patch release, ignoring the version bump determined from commit messages.

--minor

Force a minor release, ignoring the version bump determined from commit messages.

--major

Force a major release, ignoring the version bump determined from commit messages.

--prerelease

Makes the next release a prerelease, version bumps are still determined or can be forced, but the prerelease_tag (see prerelease_tag) will be appended to version number.

--noop

No operations mode. Do not take any actions, only print what will be done.

--retry

Retry the same release, do not bump.

--define

Override a configuration value. Takes an argument of the format setting="value".

--verbosity

Change the verbosity of Python Semantic Release's logging. See Showing debug output.

Running from setup.py

Add the following hook to your setup.py and you will be able to run python setup.py <command> as you would semantic-release <command>:

try:


    from semantic_release import setup_hook


    setup_hook(sys.argv)
except ImportError:


    pass

Running on CI

Getting a fully automated setup with releases from CI can be helpful for some projects. See Automatic releases.

Configuration

Configuration options can be given in three ways:

semantic-release <command> -D <option_name>=<option_value>

Each location has priority over the ones listed above it.

Releases

branch

The branch to run releases from.

Default: master

version_variable

The file and variable name of where the version number is stored, for example:

semantic_release/__init__.py:__version__

You can specify multiple version variables (i.e. in different files) by providing comma-separated list of such strings:

semantic_release/__init__.py:__version__,docs/conf.py:version

In pyproject.toml specifically, you can also use the TOML list syntax to specify multiple versions:

[tool.semantic_release]
version_variable = [


    'semantic_release/__init__.py:__version__',


    'docs/conf.py:version',
]

version_toml

Similar to version_variable, but allows the version number to be identified safely in a toml file like pyproject.toml, using a dotted notation to the key path:

pyproject.toml:tool.poetry.version

version_pattern

Similar to version_variable, but allows the version number to be identified using an arbitrary regular expression:

README.rst:VERSION (\d+\.\d+\.\d+)

The regular expression must contain a parenthesized group that matches the version number itself. Anything outside that group is just context. For example, the above specifies that there is a version number in README.rst preceded by the string "VERSION".

If the pattern contains the string {version}, it will be replaced with the regular expression used internally by python-semantic-release to match semantic version numbers. So the above example would probably be better written as:

README.rst:VERSION {version}

As with version_variable, it is possible to specify multiple version patterns in pyproject.toml.

version_source

The way we get and set the new version. Can be commit or tag.

Default: commit

prerelease_tag

Defined the prerelease marker appended to the version when doing a prerelease.

Default: beta

tag_commit

Whether to create a tag for each new release.

Default: true

patch_without_tag

If this is set to true, semantic-release will create a new patch release even if there is no tag in any commits since the last release.

Default: false

major_on_zero

If this is set to false, semantic-release will create a new minor release instead of major release when current major version is zero.

Quote from Semantic Versioning Specification:

If you do not want to bump version to 1.0.0 from 0.y.z automatically, you can set this option to false.

Default: true.

pre_commit_command

If this command is provided, it will be run prior to the creation of the release commit.

include_additional_files

A comma-separated list of files to be included within the release commit. This can include any files created/modified by the pre_commit_command.

Commit Parsing

commit_parser

Import path of a Python function that can parse commit messages and return information about the commit as described in Parsing of commit logs.

The following parsers are built in to Python Semantic Release:

major_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create major releases.

Default: :boom:

minor_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create minor releases.

Default: :sparkles:, :children_crossing:, :lipstick:, :iphone:, :egg:, :chart_with_upwards_trend:

patch_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create patch releases.

Default: :ambulance:, :lock:, :bug:, :zap:, :goal_net:, :alien:, :wheelchair:, :speech_balloon:, :mag:, :apple:, :penguin:, :checkered_flag:, :robot:, :green_apple:

use_textual_changelog_sections

If this is set to true with using the semantic_release.history.emoji_parser(), semantic-release will use human readable ASCII section headings in the changelog instead of the configured emoji.

Default: false

scipy_parser

Parses commit messages using scipy tags of the form:

<tag>(<scope>): <subject>
<body>

The elements <tag>, <scope> and <body> are optional. If no tag is present, the commit will be added to the changelog section "None" and no version increment will be performed.

While <scope> is supported here it isn't actually part of the scipy style. If it is missing, parentheses around it are too. The commit should then be of the form:

<tag>: <subject>
<body>

To communicate a breaking change add "BREAKING CHANGE" into the body at the beginning of a paragraph. Fill this paragraph with information how to migrate from the broken behavior to the new behavior. It will be added to the "Breaking" section of the changelog.

Supported Tags:

API, DEP, ENH, REV, BUG, MAINT, BENCH, BLD,
DEV, DOC, STY, TST, REL, FEAT, TEST

Supported Changelog Sections:

breaking, feature, fix, Other, None

Commits

commit_version_number

Whether or not to commit changes when bumping version.

Default: True if version_source is commit, False for other values of version_source.

commit_subject

Git commit subject line. Accepts the following variables as format fields:

Default: {version}

commit_message

Git commit message body. Accepts the following variables as format fields:

Default: Automatically generated by python-semantic-release

commit_author

Author used in commits in the format name <email>.

Default: semantic-release <semantic-release>

NOTE:

Changelog

changelog_sections

Comma-separated list of sections to display in the changelog. They will be displayed in the order they are given.

The available options depend on the commit parser used.

Default: feature, fix, breaking, documentation, performance plus all the default emojis for semantic_release.history.emoji_parser.

changelog_components

A comma-separated list of the import paths of components to include in the changelog.

The following components are included in Python Semantic Release:

It is also possible to create your own components. Each component is simply a function which returns a string, or None if it should be skipped, and may take any of the following values as keyword arguments:

You can should use **kwargs to capture any arguments you don't need.

changelog_file

The name of the file where the changelog is kept, relative to the root of the repo.

If this file doesn't exist, it will be created.

Default: CHANGELOG.md.

changelog_placeholder

A placeholder used to inject the changelog of the current release in the changelog_file.

If the placeholder isn't present in the file, a warning will be logged and nothing will be updated.

Default: <!--next-version-placeholder-->.

changelog_scope

If set to false, **scope:** (when scope is set for a commit) will not be prepended to the description when generating the changelog.

Default: True.

changelog_capitalize

If set to false commit messages will not be automatically capitalized when generating the changelog.

Default: True.

Distributions

upload_to_pypi

Deprecated since version 7.20.0: Please use upload_to_repository instead

If set to false the pypi uploading will be disabled.

See Artifact Repository which must also be set for this to work.

Default: true

upload_to_repository

If set to false the artifact uploading to repository will be disabled.

See Artifact Repository which must also be set for this to work.

Default: true

upload_to_pypi_glob_patterns

Deprecated since version 7.20.0: Please use dist_glob_patterns instead

A comma , separated list of glob patterns to use when uploading to pypi.

Default: *

dist_glob_patterns

A comma , separated list of glob patterns to use when uploading dist files to artifact repository.

Default: *

repository

The repository (package index) name to upload to. Should be a section in ~/.pypirc. The repositories pypi and testpypi are preconfigured.

Default: pypi

SEE ALSO:

repository_url

The repository (package index) URL to upload the package to.

See Configuring distribution upload for more about uploads to custom repositories.

upload_to_release

If set to false, do not upload distributions to GitHub releases. If you are not using GitHub, this will be skipped regardless.

dist_path

The relative path to the folder for dists configured for setuptools. This allows for customized setuptools processes.

Default: dist/

remove_dist

Flag for whether the dist folder should be removed after a release.

Default: true

build_command

Command to build dists. Build output should be stored in the directory configured in dist_path. If necessary, multiple commands can be specified using &&, e.g. pip install -m flit && flit build. If set to false, build command is disabled and files should be placed manually in the directory configured in dist_path.

Default: python setup.py sdist bdist_wheel

HVCS

hvcs

The name of your hvcs. Currently only github and gitlab are supported.

Default: github

hvcs_domain

The domain url (without https://) of your custom vcs server.

hvcs_api_domain

The api url (without https://) of your custom vcs server.

check_build_status

If enabled, the status of the head commit will be checked and a release will only be created if the status is success.

Default: false

tag_format

Git tag format. Accepts the following variables as format fields:

Default: v{version}

ignore_token_for_push

Do not use the default auth token to push changes to the repository. Use the system configured method. This is useful if the auth token does not have permission to push, but the system method (an ssh deploy key for instance) does.

Default: false

Environment Variables

DEBUG

Set to * to get a lot of debug information. See Showing debug output for more.

CI

See Environment checks.

CIRCLECI

Used to check if this is a Circle CI environment.

FRIGG

Used to check if this is a Frigg environment.

SEMAPHORE

Used to check if this is a Semaphore environment.

TRAVIS

Used to check if this is a Travis CI environment.

GITLAB_CI

Used to check if this is a GitLab CI environment.

JENKINS_URL

Used to check if this is a Jenkins CI environment.

CI_SERVER_HOST

Host component of the GitLab instance URL, without protocol and port. Example: gitlab.example.com

NOTE:

HVCS Authentication

GH_TOKEN

A personal access token from GitHub. This is used for authenticating when pushing tags, publishing releases etc. See Configuring push to Github for usage.

To generate a token go to https://github.com/settings/tokens and click on Personal access token.

GL_TOKEN

A personal access token from GitLab. This is used for authenticating when pushing tags, publishing releases etc.

GITEA_TOKEN

A personal access token from Gitea. This is used for authenticating when pushing tags, publishing releases etc.

Artifact Repository

PYPI_TOKEN

Deprecated since version 7.20.0: Please use REPOSITORY_PASSWORD instead

Set an API token for publishing to https://pypi.org/.

PYPI_PASSWORD

Deprecated since version 7.20.0: Please use REPOSITORY_PASSWORD instead

Used together with PYPI_USERNAME when publishing to https://pypi.org/.

PYPI_USERNAME

Deprecated since version 7.20.0: Please use REPOSITORY_USERNAME instead

Used together with PYPI_PASSWORD when publishing to https://pypi.org/.

REPOSITORY_USERNAME

Used together with REPOSITORY_PASSWORD when publishing artifact.

NOTE:

REPOSITORY_PASSWORD

Used together with REPOSITORY_USERNAME when publishing artifact. Also used for token when using token authentication.

WARNING:

REPOSITORY_URL

Custom repository (package index) URL to upload the package to. Takes precedence over repository_url

See Configuring distribution upload for more about uploads to custom repositories.

Commands

semantic-release changelog

Print the changelog to stdout.

If the option --post is used and there is an authentication token configured for your vcs provider (GH_TOKEN for GitHub, GL_TOKEN for GitLab, GITEA_TOKEN for Gitea), the changelog will be posted there too.

semantic-release version

Figure out the new version number, update and commit it, and create a tag.

This will not push anything to any remote. All changes are local.

semantic-release print-version

Print to standard output the new version number.

If the option --current is used, it will display the current version number.

It can be used to retrieve the next version number in a shell script during the build, before running the effective release, ie. to rename a distribution binary with the effective version:

VERSION=$(semantic-release print-version)

semantic-release publish

Publish will do a sequence of things:

Some of these steps may be disabled based on your configuration.

Common Options

Every command understands these flags:

--patch

Force a patch release, ignoring the version bump determined from commit messages.

--minor

Force a minor release, ignoring the version bump determined from commit messages.

--major

Force a major release, ignoring the version bump determined from commit messages.

--prerelease

Makes the next release a prerelease, version bumps are still determined or can be forced, but the prerelease_tag (see prerelease_tag) will be appended to version number.

--noop

No operations mode. Do not take any actions, only print what will be done.

--retry

Retry the same release, do not bump.

--define

Override a configuration value. Takes an argument of the format setting="value".

--verbosity

Change the verbosity of Python Semantic Release's logging. See Showing debug output.

Parsing of commit logs

The semver level that should be bumped on a release is determined by the commit messages since the last release. In order to be able to decide the correct version and generate the changelog, the content of those commit messages must be parsed. By default this package uses a parser for the Angular commit message style:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The body or footer can begin with BREAKING CHANGE: followed by a short description to create a major release.

NOTE:

More information about the style can be found in the angular commit guidelines.

Available parsers

See commit_parser.

Writing your own parser

If you think this is all well and cool, but the angular style is not for you, no need to worry because custom parsers are supported.

A parser is basically a Python function that takes the commit message as the only argument and returns the information extracted from the commit. The format of the output should be a semantic_release.history.parser_helpers.ParsedCommit object with the following parameters:

ParsedCommit(


  version level to bump: major=3 minor=2 patch=1 none=0,


  changelog section (see: :ref:`config-changelog_sections`),


  scope of change: can be None,


  (subject, descriptions...),


  (breaking change descriptions...)
)

The breaking change descriptions will be added to the changelog in full. They can and should also be included within the regular list of description paragraphs. The presence of a breaking change description will not implicitly trigger a major release.

If your parser is unable to parse a commit then it should raise semantic_release.UnknownCommitMessageStyleError.

The parser can be set with the commit_parser configuration option.

Automatic releases

The key point with using this package is to automate your releases and stop worrying about version numbers. Different approaches to automatic releases and publishing with the help of this package can be found below. Using a CI is the recommended approach.

Environment checks

On publish, a few environment checks will run. Below are descriptions of what the different checks do and under what condition they will run.

frigg

Condition: Environment variable FRIGG is 'true'

Checks for frigg to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that frigg said it checked out, not the current branch.

semaphore

Condition: Environment variable SEMAPHORE is 'true'

Checks for semaphore to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that semaphore said it checked out, not the current branch. It also checks that the thread state is not failure.

travis

Condition: Environment variable TRAVIS is 'true'

Checks for travis to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that travis said it checked out, not the current branch.

CircleCI

Condition: Environment variable CIRCLECI is 'true'

Checks for circle-ci to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that circle-ci said it checked out, not the current branch.

GitLab CI

Condition: Environment variable GITLAB_CI is 'true'

Checks for gitlab-ci to ensure that the build is on the correct branch. The branch check, checks against the branch that gitlab-ci said it checked out, not the current branch.

Jenkins

Condition: Environment variable JENKINS_URL is set.

Determines the branch name from either the environment variable BRANCH_NAME or the environment variable GIT_BRANCH, and checks to ensure that the build is on the correct branch. Also, if CHANGE_ID is set, meaning it is a PR from a multi-branch pipeline, the build will not be automatically released.

Publish with CI

Add python setup.py publish or semantic-release publish as an after success task on your preferred Continuous Integration service. Ensure that you have configured the CI so that it can upload to an artifact repository and push to git and it should be ready to roll.

Configuring distribution upload

In order to upload to an artifact repository, Python Semantic Release needs credentials to access the project. You will need to set the environment variables REPOSITORY_USERNAME and REPOSITORY_PASSWORD. Use repository_url or REPOSITORY_URL to set a custom repository url. As an alternative the repository and/or credentials can be configured using the ~/.pypirc file.

WARNING:

SEE ALSO:

Configuring push to Github

In order to push to Github and post the changelog to Github the environment variable GH_TOKEN has to be set. It needs access to the public_repo scope for public repositories and repo for private repositories.

Guides

Publish with cronjobs

This is for you if for some reason you cannot publish from your CI or you would like releases to drop at a certain interval. Before you start, answer this: Are you sure you do not want a CI to release for you? (high version numbers are not a bad thing).

The guide below is for setting up scheduled publishing on a server. It requires that the user that runs the cronjob has push access to the repository and upload access to an artifact repository.

virtualenv semantic_release -p `which python3`

pip install python-semantic-release

3. Clone the repositories you want to have scheduled publishing. 3. Put the following in publish:

VENV=semantic_release/bin
$VENV/pip install -U pip python-semantic-release > /dev/null
publish() {


  cd $1


  git stash -u # ensures that there is no untracked files in the directory


  git fetch && git reset --hard origin/master


  $VENV/semantic-release publish


  cd ..
}
publish <package1>
publish <package2>

/bin/bash -c "cd <path> && source semantic_release/bin/activate && ./publish 2>&1 >> releases.log"

Troubleshooting

Things to check...

Showing debug output

If you are having trouble with semantic-release there is a way to get more information during it's work.

By setting the --verbosity option to DEBUG you can display information from the inner workings of semantic-release.

NOTE:

semantic-release changelog --verbosity=DEBUG

WARNING:

semantic-release changelog -v DEBUG

semantic_release

semantic_release package

Semantic Release

Subpackages

semantic_release.changelog package

Submodules

semantic_release.changelog.changelog module

semantic_release.changelog.compare module

semantic_release.history package

History

Submodules

semantic_release.history.logs module

Logs

semantic_release.history.parser_angular module

Angular commit style parser

https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines

semantic_release.history.parser_emoji module

Commit parser which looks for emojis to determine the type of commit

semantic_release.history.parser_helpers module

Commit parser helpers

semantic_release.history.parser_scipy module

Parses commit messages using scipy tags of the form:

<tag>(<scope>): <subject>
<body>

The elements <tag>, <scope> and <body> are optional. If no tag is present, the commit will be added to the changelog section "None" and no version increment will be performed.

While <scope> is supported here it isn't actually part of the scipy style. If it is missing, parentheses around it are too. The commit should then be of the form:

<tag>: <subject>
<body>

To communicate a breaking change add "BREAKING CHANGE" into the body at the beginning of a paragraph. Fill this paragraph with information how to migrate from the broken behavior to the new behavior. It will be added to the "Breaking" section of the changelog.

Supported Tags:

API, DEP, ENH, REV, BUG, MAINT, BENCH, BLD,
DEV, DOC, STY, TST, REL, FEAT, TEST

Supported Changelog Sections:

breaking, feature, fix, Other, None

semantic_release.history.parser_tag module

Legacy commit parser from Python Semantic Release 1.0

Submodules

semantic_release.ci_checks module

CI Checks

semantic_release.cli module

CLI

semantic_release.dist module

Build and manage distributions

semantic_release.errors module

Custom Errors

semantic_release.helpers module

semantic_release.hvcs module

HVCS

semantic_release.pre_commit module

Run commands prior to the release commit

semantic_release.repository module

Helper for using Twine to upload to an artifact repository.

semantic_release.settings module

Helpers to read settings from setup.cfg or pyproject.toml

semantic_release.vcs_helpers module

VCS Helpers