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.

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.

.. toctree::
   :maxdepth: 1

   commands
   Strict Mode <strict_mode>
   configuration
   commit_parsing
   Changelog Templates <changelog_templates>
   Multibranch Releases <multibranch_releases>
   automatic-releases/index
   troubleshooting
   contributing
   contributors
   Migrating from Python Semantic Release v7 <migrating_from_v7>
   Internal API <api/modules>
   Algorithm <algorithm>
   View on GitHub <https://github.com/python-semantic-release/python-semantic-release>

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 :ref:`using a CI service <automatic>`, however running with :ref:`cmd-main-option-noop` can be useful to test 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 :ref:`-f/--format <cmd-generate-config-option-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.

.. seealso::
   - :ref:`cmd-generate-config`
   - :ref:`configuration`

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 :ref:`version_variables <config-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__"]

.. seealso::
   - :ref:`configuration` - tailor Python Semantic Release to your project

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 :ref:`commit-parsing`.

.. seealso::
   - :ref:`config-branches` - Adding configuration for releases from multiple branches.
   - :ref:`commit_parser <config-commit_parser>` - use a different parser for commit messages.
     For example, Python Semantic Release also ships with emoji and scipy-style parsers.
   - :ref:`remote.type <config-remote-type>` - specify the type of your remote VCS.

.. seealso::
   - :ref:`Changelog <config-changelog>` - Customize the changelog generated by Python Semantic Release.
   - :ref:`changelog-templates-migrating-existing-changelog`

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.

For local publishing to GitHub, you should use a personal access token and store it in your environment variables. Specify the name of the environment variable in your configuration setting :ref:`remote.token <config-remote-token>`. The default is GH_TOKEN.

To generate a token go to https://github.com/settings/tokens and click on "Generate new token".

For Personal Access Token (classic), you will need the repo scope to write (ie. push) to the repository.

For fine-grained Personal Access Tokens, you will need the contents permission.

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.

A personal access token from Gitea. This token should be stored in the GITEA_TOKEN environment variable.

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.

.. seealso::
   - :ref:`Changelog <config-changelog>` - customize your project's changelog.
   - :ref:`changelog-templates-custom_release_notes` - customize the published release notes
   - :ref:`upload_to_vcs_release <config-publish-upload_to_vcs_release>` -
     enable/disable uploading artefacts to VCS releases
   - :ref:`version --vcs-release/--no-vcs-release <cmd-version-option-vcs-release>` - enable/disable VCS release
     creation.
   - `upload-to-gh-release`_, a GitHub Action for running ``semantic-release publish``

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

Getting a fully automated setup with releases from CI can be helpful for some projects. See :ref:`automatic`.