Skip to content

Latest commit

 

History

History
140 lines (100 loc) · 4.3 KB

index.rst

File metadata and controls

140 lines (100 loc) · 4.3 KB
Raw

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 <automatic>, however running with --noop can be useful to test your 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 is configured using setup.cfg or pyproject.toml. Set config-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__"

- config-version_toml - use tomlkit to read and update the version number in a TOML file. - config-version_pattern - use regular expressions to keep the version number in a different format. - config-version_source - store the version using Git tags.

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 commit-log-parsing.

- config-branch - change the default branch. - config-commit_parser - use a different parser for commit messages. For example, there is an emoji parser. - config-upload_to_repository - disable uploading the package to an artifact repository. - config-hvcs - change this if you are using GitLab.

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.

- config-changelog_file - use a file other than CHANGELOG.md. - config-changelog_placeholder - use a different placeholder.

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:

  • config-hvcs - change this if you are using GitLab.
  • env-gh_token - GitHub personal access token.
  • env-gl_token - GitLab personal access token.
  • env-gitea_token - Gitea personal access token.

Distributing release on PyPI or custom repository -----------------

Unless you disable config-upload_to_repository (or config-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.

  • config-repository - use repository and/or credentials from ~/.pypirc file
  • config-repository_url - set custom repository url
  • env-repository - provide credentials using environment variables
  • automatic-dist-upload - configuring CI distribution upload

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.

Documentation Contents

configuration envvars commands commit-log-parsing automatic-releases/index troubleshooting contributors Internal API <api/modules>