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