Provided by: python3-semantic-release_9.8.5-1_all 
NAME
python-semantic-release - python-semantic-release Documentation
Automatic Semantic Versioning for Python projects. This is a Python implementation of semantic-release
for JS by Stephan Bönnemann. If you find this topic interesting you should check out his talk from JSConf
Budapest.
The general idea is to be able to detect what the next version of the project should be based on the
commits. This tool will use that to automate the whole release, upload to an artifact repository and post
changelogs to GitHub. You can run the tool on a CI service, or just run it locally.
INSTALLATION
python3 -m pip install python-semantic-release
semantic-release --help
Python Semantic Release is also available from conda-forge or as a GitHub Action. Read more about the
setup and configuration in our getting started guide.
DOCUMENTATION CONTENTS
Commands
All commands accept a -h/--help option, which displays the help text for the command and exits
immediately.
semantic-release does not allow interspersed arguments and options, which means that the options for
semantic-release are not necessarily accepted one of the subcommands. In particular, the --noop and
-v/--verbose flags must be given to the top-level semantic-release command, before the name of the
subcommand.
For example:
Incorrect:
semantic-release version --print --noop -vv
Correct:
semantic-release -vv --noop version --print
With the exception of semantic-release and semantic-release generate-config, all commands require that
you have set up your project's configuration. To help with this step, semantic-release generate-config
can create the default configuration for you, which will allow you to tweak it to your needs rather than
write it from scratch.
semantic-release
Options:
--version
Display the version of Python Semantic Release and exit
--noop
Use this flag to see what semantic-release intends to do without making changes to your project. When
using this option, semantic-release can be run as many times as you wish without any side-effects.
-v/--verbose
Can be supplied more than once. Controls the verbosity of semantic-releases logging output (default level
is WARNING, use -v for INFO and -vv for DEBUG).
-c/--config [FILE]
Specify the configuration file which Python Semantic Release should use. This can be any of the supported
formats valid for -f/--format [FORMAT]
Default: pyproject.toml
SEE ALSO:
• Configuration
--strict
Enable Strict Mode. This will cause a number of conditions to produce a non-zero exit code when passed,
where they would otherwise have produced an exit code of 0. Enabling this allows, for example, certain
conditions to cause failure of a CI pipeline, while omitting this flag would allow the pipeline to
continue to run.
SEE ALSO:
• Strict Mode
semantic-release version
Detect the semantically correct next version that should be applied to your project.
By default:
• Write this new version to the project metadata locations specified in the configuration file
• Build the project using build_command, if specified
• Create a new commit with these locations and any other assets configured to be included in a release
• Tag this commit according the configured format, with a tag that uniquely identifies the version
being released
• Push the new tag and commit to the remote for the repository
• Create a release (if supported) in the remote VCS for this tag
Changelog generation is done identically to the way it is done in semantic-release changelog, but this
command additionally ensures the updated changelog is included in the release commit that is made.
SEE ALSO:
• semantic-release changelog
• Changelog Templates
• tag_format
• assets
• version_toml
• version_variables
Options:
--print
Print the next version that will be applied, respecting the other command line options that are supplied,
and exit. This flag is useful if you just want to see what the next version will be. Note that instead
of printing nothing at all, if no release will be made, the current version is printed.
For example, you can experiment with which versions would be applied using the other command line
options:
semantic-release version --print
semantic-release version --patch --print
semantic-release version --prerelease --print
--print-tag
Same as the --print flag but prints the complete tag name (ex. v1.0.0 or py-v1.0.0) instead of the raw
version number (1.0.0).
--print-last-released
Print the last released version based on the Git tags. This flag is useful if you just want to see the
released version without determining what the next version will be. Note if the version can not be found
nothing will be printed.
--print-last-released-tag
Same as the --print-last-released flag but prints the complete tag name (ex. v1.0.0 or py-v1.0.0) instead
of the raw version number (1.0.0).
--major/--minor/--patch/--prerelease
Force the next version to increment the major, minor or patch digits, or the prerelease revision,
respectively. These flags are optional but mutually exclusive, so only one may be supplied, or none at
all. Using these flags overrides the usual calculation for the next version; this can be useful, say,
when a project wants to release its initial 1.0.0 version.
WARNING:
Using these flags will override the configured value of prerelease (configured in your Release Group),
regardless of your configuration or the current version.
To produce a prerelease with the appropriate digit incremented you should also supply the
--as-prerelease flag. If you do not, using these flags will force a full (non-prerelease) version to
be created.
For example, suppose your project's current version is 0.2.1-rc.1. The following shows how these options
can be combined with --as-prerelease to force different versions:
semantic-release version --prerelease --print
# 0.2.1-rc.2
semantic-release version --patch --print
# 0.2.2
semantic-release version --minor --print
# 0.3.0
semantic-release version --major --print
# 1.0.0
semantic-release version --minor --as-prerelease --print
# 0.3.0-rc.1
semantic-release version --prerelease --as-prerelease --print
# 0.2.1-rc.2
These options are forceful overrides, but there is no action required for subsequent releases performed
using the usual calculation algorithm.
Supplying --prerelease will cause Python Semantic Release to scan your project history for any previous
prereleases with the same major, minor and patch versions as the latest version and the same prerelease
token as the one passed by command-line or configuration. If one is not found, --prerelease will produce
the next version according to the following format:
f"{latest_version.major}.{latest_version.minor}.{latest_version.patch}-{prerelease_token}.1"
However, if Python Semantic Release identifies a previous prerelease version with the same major, minor
and patch digits as the latest version, and the same prerelease token as the one supplied by command-line
or configuration, then Python Semantic Release will increment the revision found on that previous
prerelease version in its new version.
For example, if "0.2.1-rc.1" and already exists as a previous version, and the latest version is "0.2.1",
invoking the following command will produce "0.2.1-rc.2":
semantic-release version --prerelease --prerelease-token "rc" --print
WARNING:
This is true irrespective of the branch from which "0.2.1-rc.1" was released from. The check for
previous prereleases "leading up to" this normal version is intended to help prevent collisions in git
tags to an extent, but isn't foolproof. As the example shows it is possible to release a prerelease
for a normal version that's already been released when using this flag, which would in turn be ignored
by tools selecting versions by SemVer precedence rules.
SEE ALSO:
• Configuration
• branches
--as-prerelease
After performing the normal calculation of the next version, convert the resulting next version to a
prerelease before applying it. As with --major/--minor/--patch/--prerelease, this option is a forceful
override, but no action is required to resume calculating versions as normal on the subsequent releases.
The main distinction between --prerelease and --as-prerelease is that the latter will not force a new
version if one would not have been released without supplying the flag.
This can be useful when making a single prerelease on a branch that would typically release normal
versions.
If not specified in --prerelease-token [VALUE], the prerelease token is idenitified using the Multibranch
Release Configuration
See the examples alongside --major/--minor/--patch/--prerelease for how to use this flag.
--prerelease-token [VALUE]
Force the next version to use the value as the prerelease token. This overrides the configured value if
one is present. If not used during a release producing a prerelease version, this option has no effect.
--build-metadata [VALUE]
If given, append the value to the newly calculated version. This can be used, for example, to attach a
run number from a CI service or a date to the version and tag that are created.
This value can also be set using the environment variable PSR_BUILD_METADATA
For example, assuming a project is currently at version 1.2.3:
$ semantic-release version --minor --print
1.3.0
$ semantic-release version --minor --print --build-metadata "run.12345"
1.3.0+run.12345
--commit/--no-commit
Whether or not to perform a git commit on modifications to source files made by semantic-release during
this command invocation, and to run git tag on this new commit with a tag corresponding to the new
version.
If --no-commit is supplied, it may disable other options derivatively; please see below.
Default: --commit
SEE ALSO:
• tag_format
--tag/--no-tag
Whether or not to perform a git tag to apply a tag of the corresponding to the new version during this
command invocation. This option manages the tag application separate from the commit handled by the
--commit option.
If --no-tag is supplied, it may disable other options derivatively; please see below.
Default: --tag
--changelog/--no-changelog
Whether or not to update the changelog file with changes introduced as part of the new version released.
Default: --changelog
SEE ALSO:
• changelog
• Changelog Templates
--push/--no-push
Whether or not to push new commits and/or tags to the remote repository.
Default: --no-push if --no-commit and --no-tag is also supplied, otherwise push is the default.
--vcs-release/--no-vcs-release
Whether or not to create a "release" in the remote VCS service, if supported. Currently releases in
GitHub and Gitea remotes are supported. If releases aren't supported in a remote VCS, this option will
not cause a command failure, but will produce a warning.
Default: --no-vcs-release if --no-push is supplied (including where this is implied by supplying only
--no-commit), otherwise --vcs-release
--skip-build
If passed, skip building the current project using build_command.
semantic-release publish
Publish a distribution to a VCS release. Uploads using publish
SEE ALSO:
• publish
• build_command
Options:
--tag
The tag associated with the release to publish to. If not given or set to "latest", then Python Semantic
Release will examine the Git tags in your repository to identify the latest version, and attempt to
publish to a Release corresponding to this version.
Default: "latest"
semantic-release generate-config
Generate default configuration for semantic-release, to help you get started quickly. You can inspect the
defaults, write to a file and then edit according to your needs. For example, to append the default
configuration to your pyproject.toml file, you can use the following command:
$ semantic-release generate-config -f toml --pyproject >> pyproject.toml
If your project doesn't already leverage TOML files for configuration, it might better suit your project
to use JSON instead:
$ semantic-release generate-config -f json
If you would like to add JSON configuration to a shared file, e.g. package.json, you can then simply add
the output from this command as a top-level key to the file.
Note: Because there is no "null" or "nil" concept in TOML (see the relevant GitHub issue), configuration
settings which are None by default are omitted from the default configuration.
SEE ALSO:
• Configuration
Options:
-f/--format [FORMAT]
The format that the default configuration should be generated in. Valid choices are toml and json
(case-insensitive).
Default: toml
--pyproject
If used alongside --format json, this option has no effect. When using --format=toml, if specified the
configuration will sit under a top-level key of tool.semantic_release to comply with PEP 518; otherwise,
the configuration will sit under a top-level key of semantic_release.
semantic-release changelog
Generate and optionally publish a changelog for your project. The changelog is generated based on a
template which can be customized.
Python Semantic Release uses Jinja as its templating engine; as a result templates need to be written
according to the Template Designer Documentation.
SEE ALSO:
• changelog
• environment
• Changelog Templates
Options:
--post-to-release-tag [TAG]
If supplied, attempt to find a release in the remote VCS corresponding to the Git tag TAG, and post the
generated changelog to that release. If the tag exists but no corresponding release is found in the
remote VCS, then Python Semantic Release will attempt to create one.
If using this option, the relevant authentication token must be supplied via the relevant environment
variable. For more information, see Creating VCS Releases.
Strict Mode
Strict Mode is enabled by use of the strict parameter to the main command for Python Semantic Release.
Strict Mode alters the behaviour of Python Semantic Release when certain conditions are encountered that
prevent Python Semantic Release from performing an action. Typically, this will result in a warning
becoming an error, or a different exit code (0 vs non-zero) being produced when Python Semantic Release
exits early.
For example:
#!/usr/bin/bash
set -euo pipefail
git checkout $NOT_A_RELEASE_BRANCH
pip install \
black \
isort \
twine \
pytest \
python-semantic-release
isort . # sort imports
black . # format the code
pytest # test the code
semantic-release --strict version # ERROR - not a release branch
twine upload dist/* # publish the code
Using Strict Mode with the --strict flag ensures this simple pipeline will fail while running
semantic-release, as the non-zero exit code will cause it to stop when combined with the -e option.
Without Strict Mode, the semantic-release command will exit with code 0, causing the above pipeline to
continue.
The specific effects of enabling Strict Mode are detailed below.
Non-Release Branches
When running in Strict Mode, invoking Python Semantic Release on a non-Release branch will cause an error
with a non-zero exit code. This means that you can prevent an automated script from running further
against branches you do not want to release from, for example in multibranch CI pipelines.
Running without Strict Mode will allow subsequent steps in the pipeline to also execute, but be aware
that certain actions that Python Semantic Release may perform for you will likely not have been carried
out, such as writing to files or creating a git commit in your repository.
SEE ALSO:
• Multibranch Releases
Version Already Released/No Release To Be Made
When Strict Mode is not enabled and Python Semantic Release identifies that no release needs to be made,
it will exit with code 0. You can cause Python Semantic Release to raise an error if no release needs to
be made by enabling Strict Mode.
Configuration
Configuration is read from a file which can be specified using the \\-\\-config option to ‐
semantic-release. Python Semantic Release currently supports a configuration in either TOML or JSON
format, and will attempt to auto-detect and parse either format.
When using a JSON-format configuration file, Python Semantic Release looks for its settings beneath a
top-level semantic_release key; when using a TOML-format configuration file, Python Semantic Release
first checks for its configuration under the table [tool.semantic_release] (in line with the convention
for Python tools to require their configuration under the top-level tool table in their pyproject.toml
file), followed by [semantic_release], which may be more desirable if using a file other than the default
pyproject.toml for configuration.
The examples on this page are given in TOML format, however there is no limitation on using JSON instead.
In fact, if you would like to convert any example below to its JSON equivalent, the following commands
will do this for you (in Bash):
export TEXT="<the TOML to convert>"
cat <<EOF | python3
import tomlkit, json
print(json.dumps(tomlkit.loads('''$TEXT'''), indent=4))
EOF
A note on null
In TOML, there is no such thing as a "null" or "nil" value, and this isn't planned as a language feature
according to the relevant GitHub issue. In Python Semantic Release, options which default to None are
inferred from the relevant configuration settings not being present at all in your configuration.
Because of this limitation, it's currently not possible to explicitly specify those settings as "null" in
TOML-format configuration. Technically it is possible in JSON-format configuration, but it's recommended
to keep consistency and just omit the relevant settings.
Environment Variables
Some settings are best pulled from environment variables rather than being stored in plaintext in your
configuration file. Python Semantic Release can be configured to look for an environment variable value
to use for a given setting, but this feature is not available for all settings. In order to use an
environment variable for a setting, you must indicate in your configuration file the name of the
environment variable to use.
The traditional and most common use case for environment variable use is for passing authentication
tokens to Python Semantic Release. You do NOT want to hard code your authentication token in your
configuration file, as this is a security risk. A plaintext token in your configuration file could be
exposed to anyone with access to your repository, including long after its deleted if a token is in your
git history. Instead, define the name of the environment variable which contains your remote.token, such
as GH_TOKEN, in your configuration file, and Python Semantic Release will do the rest, as seen below.
[semantic_release.remote.token]
env = "GH_TOKEN"
Given basic TOML syntax compatibility, this is equivalent to:
[semantic_release.remote]
token = { env = "GH_TOKEN" }
The general format for specifying that some configuration should be sourced from an environment variable
is:
[semantic_release.variable]
env = "ENV_VAR"
default_env = "FALLBACK_ENV_VAR"
default = "default value"
In this structure:
• env represents the environment variable that Python Semantic Release will search for
• default_env is a fallback environment variable to read in case the variable specified by env is
not set. This is optional - if not specified then no fallback will be used.
• default is a default value to use in case the environment variable specified by env is not set.
This is optional - if default is not specified then the environment variable specified by env is
considered required.
semantic_release settings
The following sections outline all the definitions and descriptions of each supported configuration
setting. If there are type mis-matches, PSR will throw validation errors upon load. If a setting is not
provided, than PSR will fill in the value with the default value.
Python Semantic Release expects a root level key to start the configuration definition. Make sure to use
the correct root key dependending on the configuration format you are using.
NOTE:
If you are using pyproject.toml, this heading should include the tool prefix as specified within PEP
517, resulting in [tool.semantic_release].
NOTE:
If you are using a releaserc.toml, use [semantic_release] as the root key
NOTE:
If you are using a releaserc.json, semantic_release must be the root key in the top level dictionary.
----
allow_zero_version
Type: bool
This flag controls whether or not Python Semantic Release will use version numbers aligning with the
0.x.x pattern.
If set to true and starting at 0.0.0, a minor bump would set the next version as 0.1.0 whereas a patch
bump would set the next version as 0.0.1. A breaking change (ie. major bump) would set the next version
as 1.0.0 unless the major_on_zero is set to false.
If set to false, Python Semantic Release will consider the first possible version to be 1.0.0, regardless
of patch, minor, or major change level. Additionally, when allow_zero_version is set to false, the
major_on_zero setting is ignored.
Default: true
----
assets
Type: list[str]
One or more paths to additional assets that should committed to the remote repository in addition to any
files modified by writing the new version.
Default: []
----
branches
This setting is discussed in more detail at Multibranch Releases
Default:
[semantic_release.branches.main]
match = "(main|master)"
prerelease_token = "rc"
prerelease = false
----
build_command
Type: Optional[str]
Command to use to build the current project during semantic-release version.
Python Semantic Release will execute the build command in the OS default shell with a subset of
environment variables. PSR provides the variable NEW_VERSION in the environment with the value of the
next determined version. The following table summarizes all the environment variables that are passed on
to the build_command runtime if they exist in the parent process.
If you would like to pass additional environment variables to your build command, see build_command_env.
────────────────────────────────────────────────────────────────────
Variable Name Description
────────────────────────────────────────────────────────────────────
CI Pass-through true if exists in
process env, unset otherwise
────────────────────────────────────────────────────────────────────
BITBUCKET_CI true if Bitbucket CI variables exist
in env, unset otherwise
────────────────────────────────────────────────────────────────────
GITHUB_ACTIONS Pass-through true if exists in
process env, unset otherwise
────────────────────────────────────────────────────────────────────
GITEA_ACTIONS Pass-through true if exists in
process env, unset otherwise
────────────────────────────────────────────────────────────────────
GITLAB_CI Pass-through true if exists in
process env, unset otherwise
────────────────────────────────────────────────────────────────────
HOME Pass-through HOME of parent process
────────────────────────────────────────────────────────────────────
NEW_VERSION Semantically determined next version
(ex. 1.2.3)
────────────────────────────────────────────────────────────────────
PATH Pass-through PATH of parent process
────────────────────────────────────────────────────────────────────
PSR_DOCKER_GITHUB_ACTION Pass-through true if exists in
process env, unset otherwise
────────────────────────────────────────────────────────────────────
VIRTUAL_ENV Pass-through VIRTUAL_ENV if exists in
process env, unset otherwise
┌──────────────────────────┬───────────────────────────────────────┐
│ │ │
--
GETTING STARTED
If you haven't done so already, install Python Semantic Release following the instructions above.
There is no strict requirement to have it installed locally if you intend on using a CI service, however
running with --noop can be useful to test your configuration.
Generating your configuration
Python Semantic Release ships with a command-line interface, semantic-release. You can inspect the
default configuration in your terminal by running
semantic-release generate-config
You can also use the -f/--format option to specify what format you would like this configuration to be.
The default is TOML, but JSON can also be used.
You can append the configuration to your existing pyproject.toml file using a standard redirect, for
example:
semantic-release generate-config --pyproject >> pyproject.toml
and then editing to your project's requirements.
SEE ALSO:
• semantic-release generate-config
• Configuration
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 can be configured using a TOML or JSON file; the default configuration file is
pyproject.toml, if you wish to use another file you will need to use the -c/--config option to specify
the file.
Set version_variables to a list, the only element of which should be the location of your version
variable inside any Python file, specified in standard module:attribute syntax:
pyproject.toml:
[tool.semantic_release]
version_variables = ["setup.py:__version__"]
SEE ALSO:
• Configuration - tailor Python Semantic Release to your project
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 in Commit Parsing.
SEE ALSO:
• branches - Adding configuration for releases from multiple branches.
• commit_parser - use a different parser for commit messages. For example, Python Semantic Release
also ships with emoji and scipy-style parsers.
• remote.type - specify the type of your remote VCS.
Setting up the changelog
SEE ALSO:
• Changelog - Customize the changelog generated by Python Semantic Release.
• Migrating an Existing Changelog
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.
GitHub (GH_TOKEN)
Use a personal access token from GitHub. See Configuring push to Github for usage. This token should be
stored in the GH_TOKEN environment variable
To generate a token go to https://github.com/settings/tokens and click on Personal access token.
GitLab (GITLAB_TOKEN)
A personal access token from GitLab. This is used for authenticating when pushing tags, publishing
releases etc. This token should be stored in the GITLAB_TOKEN environment variable.
Gitea (GITEA_TOKEN)
A personal access token from Gitea. This token should be stored in the GITEA_TOKEN environment variable.
Bitbucket (BITBUCKET_TOKEN)
Bitbucket does not support uploading releases but can still benefit from automated tags and changelogs.
The user has three options to push changes to the repository:
1. Use SSH keys.
2. Use an App Secret, store the secret in the BITBUCKET_TOKEN environment variable and the username in
BITBUCKET_USER.
3. Use an Access Token for the repository and store it in the BITBUCKET_TOKEN environment variable.
SEE ALSO:
• Changelog - customize your project's changelog.
• Customizing VCS Release Notes - customize the VCS release notes.
• upload_to_vcs_release - enable/disable uploading artefacts to VCS releases
• version --vcs-release/--no-vcs-release - enable/disable VCS release creation.
• upload-to-gh-release, a GitHub Action for running semantic-release publish
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
NOTE:
Only the version, publish, and changelog commands may be invoked from setup.py in this way.
Running on CI
Getting a fully automated setup with releases from CI can be helpful for some projects. See Automatic
Releases.
AUTHOR
Rolf Erik Lekang
COPYRIGHT
2024, Rolf Erik Lekang
9.8.5 Jul 18, 2024 PYTHON-SEMANTIC-RELEASE(1)