.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "PYTHON-SEMANTIC-RELEASE" "1" "Oct 23, 2022" "7.32.2" "python-semantic-release" .SH NAME python-semantic-release \- python-semantic-release Documentation .sp Automatic Semantic Versioning for Python projects. This is a Python implementation of \fI\%semantic\-release\fP for JS by Stephan Bönnemann. If you find this topic interesting you should check out his \fI\%talk from JSConf Budapest\fP\&. .sp 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. .SH INSTALLATION .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python3 \-m pip install python\-semantic\-release semantic\-release \-\-help .ft P .fi .UNINDENT .UNINDENT .sp Python Semantic Release is also available from \fI\%conda\-forge\fP or as a \fI\%GitHub Action\fP\&. Read more about the setup and configuration in our \fI\%getting started guide\fP\&. .SH GETTING STARTED .sp If you haven\(aqt done so already, install Python Semantic Release following the instructions above. .sp There is no strict requirement to have it installed locally if you intend on \fI\%using a CI service\fP, however running with \fB\-\-noop\fP can be useful to test your configuration. .SS Setting up version numbering .sp Create a variable set to the current version number. This could be anywhere in your project, for example \fBsetup.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from setuptools import setup __version__ = "0.0.0" setup( name="my\-package", version=__version__, # And so on... ) .ft P .fi .UNINDENT .UNINDENT .sp Python Semantic Release is configured using \fBsetup.cfg\fP or \fBpyproject.toml\fP\&. Set \fI\%version_variable\fP to the location of your version variable inside any Python file: .sp \fBsetup.cfg\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [semantic_release] version_variable = setup.py:__version__ .ft P .fi .UNINDENT .UNINDENT .sp \fBpyproject.toml\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [tool.semantic_release] version_variable = "setup.py:__version__" .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%version_toml\fP \- use \fI\%tomlkit\fP to read and update the version number in a TOML file. .IP \(bu 2 \fI\%version_pattern\fP \- use regular expressions to keep the version number in a different format. .IP \(bu 2 \fI\%version_source\fP \- store the version using Git tags. .UNINDENT .UNINDENT .UNINDENT .SS Setting up commit parsing .sp We rely on commit messages to detect when a version bump is needed. By default, Python Semantic Release uses the \fI\%Angular style\fP\&. You can find out more about this on \fI\%Parsing of commit logs\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%branch\fP \- change the default branch. .IP \(bu 2 \fI\%commit_parser\fP \- use a different parser for commit messages. For example, there is an emoji parser. .IP \(bu 2 \fI\%upload_to_repository\fP \- disable uploading the package to an artifact repository. .IP \(bu 2 \fI\%hvcs\fP \- change this if you are using GitLab. .UNINDENT .UNINDENT .UNINDENT .SS Setting up the changelog .sp If you already have a \fICHANGELOG.md\fP, you will need to insert a placeholder tag so we know where to write new versions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp If you don\(aqt have a changelog file then one will be set up like this automatically. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%changelog_file\fP \- use a file other than \fICHANGELOG.md\fP\&. .IP \(bu 2 config\-changelog_placeholder \- use a different placeholder. .UNINDENT .UNINDENT .UNINDENT .SS Releasing on GitHub / GitLab .sp Some options and environment variables need to be set in order to push release notes and new versions to GitHub / GitLab: .INDENT 0.0 .IP \(bu 2 \fI\%hvcs\fP \- change this if you are using GitLab. .IP \(bu 2 \fI\%GH_TOKEN\fP \- GitHub personal access token. .IP \(bu 2 \fI\%GL_TOKEN\fP \- GitLab personal access token. .IP \(bu 2 \fI\%GITEA_TOKEN\fP \- Gitea personal access token. .UNINDENT .SS Distributing release on PyPI or custom repository .sp Unless you disable \fI\%upload_to_repository\fP (or \fI\%upload_to_pypi\fP), Python Semantic Release will publish new versions to \fIPypi\fP\&. Customization is supported using a \fB~/.pypirc\fP file or config setting and environment variables for username and password/token or a combination of both. Publishing is done using \fI\%twine\fP\&. .INDENT 0.0 .IP \(bu 2 \fI\%repository\fP \- use repository and/or credentials from \fB~/.pypirc\fP file .IP \(bu 2 \fI\%repository_url\fP \- set custom repository url .IP \(bu 2 \fI\%Artifact Repository\fP \- provide credentials using environment variables .IP \(bu 2 \fI\%Configuring distribution upload\fP \- configuring CI distribution upload .UNINDENT .SS Commands .SS \fBsemantic\-release changelog\fP .sp Print the changelog to stdout. .sp If the option \fB\-\-post\fP is used and there is an authentication token configured for your vcs provider (\fI\%GH_TOKEN\fP for GitHub, \fI\%GL_TOKEN\fP for GitLab, \fI\%GITEA_TOKEN\fP for Gitea), the changelog will be posted there too. .SS \fBsemantic\-release version\fP .sp Figure out the new version number, update and commit it, and create a tag. .sp This will not push anything to any remote. All changes are local. .SS \fBsemantic\-release print\-version\fP .sp Print to standard output the new version number. .sp If the option \fB\-\-current\fP is used, it will display the current version number. .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C VERSION=$(semantic\-release print\-version) .ft P .fi .UNINDENT .UNINDENT .SS \fBsemantic\-release publish\fP .sp Publish will do a sequence of things: .INDENT 0.0 .IP 1. 3 Update changelog file. .IP 2. 3 Run \fI\%semantic\-release version\fP\&. .IP 3. 3 Push changes to git. .IP 4. 3 Run \fI\%build_command\fP and upload the distribution file to your repository. .IP 5. 3 Run \fI\%semantic\-release changelog\fP and post to your vcs provider. .IP 6. 3 Attach the files created by \fI\%build_command\fP to GitHub releases. .UNINDENT .sp Some of these steps may be disabled based on your configuration. .SS Common Options .sp Every command understands these flags: .SS \fB\-\-patch\fP .sp Force a patch release, ignoring the version bump determined from commit messages. .SS \fB\-\-minor\fP .sp Force a minor release, ignoring the version bump determined from commit messages. .SS \fB\-\-major\fP .sp Force a major release, ignoring the version bump determined from commit messages. .SS \fB\-\-prerelease\fP .sp Makes the next release a prerelease, version bumps are still determined or can be forced, but the \fIprerelease_tag\fP (see \fI\%prerelease_tag\fP) will be appended to version number. .SS \fB\-\-noop\fP .sp No operations mode. Do not take any actions, only print what will be done. .SS \fB\-\-retry\fP .sp Retry the same release, do not bump. .SS \fB\-\-define\fP .sp Override a configuration value. Takes an argument of the format \fBsetting="value"\fP\&. .SS \fB\-\-verbosity\fP .sp Change the verbosity of Python Semantic Release\(aqs logging. See \fI\%Showing debug output\fP\&. .SS Running from setup.py .sp Add the following hook to your \fBsetup.py\fP and you will be able to run \fBpython setup.py \fP as you would \fBsemantic\-release \fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C try: from semantic_release import setup_hook setup_hook(sys.argv) except ImportError: pass .ft P .fi .UNINDENT .UNINDENT .SS Running on CI .sp Getting a fully automated setup with releases from CI can be helpful for some projects. See \fI\%Automatic releases\fP\&. .SH DOCUMENTATION CONTENTS .SS Configuration .sp Configuration options can be given in three ways: .INDENT 0.0 .IP \(bu 2 \fBsetup.cfg\fP file in a \fB[semantic_release]\fP section .IP \(bu 2 \fBpyproject.toml\fP file in a \fB[tool.semantic_release]\fP section .IP \(bu 2 \fB\-D\fP option, like so: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C semantic\-release \-D = .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Each location has priority over the ones listed above it. .SS Releases .SS \fBbranch\fP .sp The branch to run releases from. .sp Default: \fImaster\fP .SS \fBversion_variable\fP .sp The file and variable name of where the version number is stored, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C semantic_release/__init__.py:__version__ .ft P .fi .UNINDENT .UNINDENT .sp You can specify multiple version variables (i.e. in different files) by providing comma\-separated list of such strings: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C semantic_release/__init__.py:__version__,docs/conf.py:version .ft P .fi .UNINDENT .UNINDENT .sp In \fBpyproject.toml\fP specifically, you can also use the TOML list syntax to specify multiple versions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [tool.semantic_release] version_variable = [ \(aqsemantic_release/__init__.py:__version__\(aq, \(aqdocs/conf.py:version\(aq, ] .ft P .fi .UNINDENT .UNINDENT .SS \fBversion_toml\fP .sp Similar to \fI\%version_variable\fP, but allows the version number to be identified safely in a toml file like \fBpyproject.toml\fP, using a dotted notation to the key path: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyproject.toml:tool.poetry.version .ft P .fi .UNINDENT .UNINDENT .SS \fBversion_pattern\fP .sp Similar to \fI\%version_variable\fP, but allows the version number to be identified using an arbitrary regular expression: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C README.rst:VERSION (\ed+\e.\ed+\e.\ed+) .ft P .fi .UNINDENT .UNINDENT .sp 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 \fBREADME.rst\fP preceded by the string "VERSION". .sp If the pattern contains the string \fB{version}\fP, it will be replaced with the regular expression used internally by \fBpython\-semantic\-release\fP to match semantic version numbers. So the above example would probably be better written as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C README.rst:VERSION {version} .ft P .fi .UNINDENT .UNINDENT .sp As with \fI\%version_variable\fP, it is possible to specify multiple version patterns in \fBpyproject.toml\fP\&. .SS \fBversion_source\fP .sp The way we get and set the new version. Can be \fIcommit\fP or \fItag\fP\&. .INDENT 0.0 .IP \(bu 2 If set to \fItag\fP, will get the current version from the latest tag matching \fBvX.Y.Z\fP\&. This won\(aqt change the source defined in \fI\%version_variable\fP\&. .IP \(bu 2 If set to \fIcommit\fP, will get the current version from the source defined in \fI\%version_variable\fP, edit the file and commit it. .IP \(bu 2 If set to \fItag_only\fP, then \fIversion_variable\fP is ignored and no changes are made or committed to local config files. The current version from the latest tag matching \fBvX.Y.Z\fP\&. This won\(aqt change the source defined in \fI\%version_variable\fP\&. .UNINDENT .sp Default: \fIcommit\fP .SS \fBprerelease_tag\fP .sp Defined the prerelease marker appended to the version when doing a prerelease. .INDENT 0.0 .IP \(bu 2 The format of a prerelease version will be \fI{tag_format}\-{prerelease_tag}.\fP, e.g. \fI1.0.0\-beta.0\fP or \fI1.1.0\-beta.1\fP .UNINDENT .sp Default: \fIbeta\fP .SS \fBtag_commit\fP .sp Whether to create a tag for each new release. .sp Default: \fItrue\fP .SS \fBpatch_without_tag\fP .sp If this is set to \fItrue\fP, semantic\-release will create a new patch release even if there is no tag in any commits since the last release. .sp Default: \fIfalse\fP .SS \fBmajor_on_zero\fP .sp If this is set to \fIfalse\fP, semantic\-release will create a new minor release instead of major release when current major version is zero. .sp Quote from \fI\%Semantic Versioning Specification\fP: .INDENT 0.0 .INDENT 3.5 Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. .UNINDENT .UNINDENT .sp If you do not want to bump version to 1.0.0 from 0.y.z automatically, you can set this option to \fIfalse\fP\&. .sp Default: \fItrue\fP\&. .SS \fBpre_commit_command\fP .sp If this command is provided, it will be run prior to the creation of the release commit. .SS \fBinclude_additional_files\fP .sp A comma\-separated list of files to be included within the release commit. This can include any files created/modified by the \fBpre_commit_command\fP\&. .SS Commit Parsing .SS \fBcommit_parser\fP .sp Import path of a Python function that can parse commit messages and return information about the commit as described in \fI\%Parsing of commit logs\fP\&. .sp The following parsers are built in to Python Semantic Release: .INDENT 0.0 .IP \(bu 2 \fBsemantic_release.history.angular_parser()\fP .sp The default parser, which uses the \fI\%Angular commit style\fP with the following differences: .INDENT 2.0 .IP \(bu 2 Multiple \fBBREAKING CHANGE:\fP paragraphs are supported .IP \(bu 2 \fBrevert\fP is not currently supported .UNINDENT .IP \(bu 2 \fBsemantic_release.history.emoji_parser()\fP .sp Parser for commits using one or more emojis as tags in the subject line. .sp If a commit contains multiple emojis, the one with the highest priority (major, minor, patch, none) or the one listed first is used as the changelog section for that commit. Commits containing no emojis go into an "Other" section. .sp See \fI\%major_emoji\fP, \fI\%minor_emoji\fP and \fI\%patch_emoji\fP\&. The default settings are for \fI\%Gitmoji\fP\&. .IP \(bu 2 \fBsemantic_release.history.tag_parser()\fP .sp The original parser from v1.0.0 of Python Semantic Release. Similar to the emoji parser above, but with less features. .IP \(bu 2 \fBsemantic_release.history.scipy_parser()\fP .sp A parser for \fI\%scipy\-style commits\fP with the following differences: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Beginning a paragraph inside the commit with \fBBREAKING CHANGE\fP declares a breaking change. Multiple \fBBREAKING CHANGE\fP paragraphs are supported. .IP \(bu 2 A scope (following the tag in parentheses) is supported .UNINDENT .UNINDENT .UNINDENT .sp See \fI\%scipy_parser\fP for details. .UNINDENT .SS \fBmajor_emoji\fP .sp Comma\-separated list of emojis used by \fBsemantic_release.history.emoji_parser()\fP to create major releases. .sp Default: \fI:boom:\fP .SS \fBminor_emoji\fP .sp Comma\-separated list of emojis used by \fBsemantic_release.history.emoji_parser()\fP to create minor releases. .sp Default: \fI:sparkles:, :children_crossing:, :lipstick:, :iphone:, :egg:, :chart_with_upwards_trend:\fP .SS \fBpatch_emoji\fP .sp Comma\-separated list of emojis used by \fBsemantic_release.history.emoji_parser()\fP to create patch releases. .sp Default: \fI:ambulance:, :lock:, :bug:, :zap:, :goal_net:, :alien:, :wheelchair:, :speech_balloon:, :mag:, :apple:, :penguin:, :checkered_flag:, :robot:, :green_apple:\fP .SS \fBuse_textual_changelog_sections\fP .sp If this is set to \fItrue\fP with using the \fBsemantic_release.history.emoji_parser()\fP, semantic\-release will use human readable ASCII section headings in the changelog instead of the configured emoji. .sp Default: \fIfalse\fP .SS \fBscipy_parser\fP .sp Parses commit messages using \fI\%scipy tags\fP of the form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C (): .ft P .fi .UNINDENT .UNINDENT .sp The elements , and are optional. If no tag is present, the commit will be added to the changelog section "None" and no version increment will be performed. .sp While is supported here it isn\(aqt actually part of the scipy style. If it is missing, parentheses around it are too. The commit should then be of the form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C : .ft P .fi .UNINDENT .UNINDENT .sp 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. .sp Supported Tags: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C API, DEP, ENH, REV, BUG, MAINT, BENCH, BLD, DEV, DOC, STY, TST, REL, FEAT, TEST .ft P .fi .UNINDENT .UNINDENT .sp Supported Changelog Sections: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C breaking, feature, fix, Other, None .ft P .fi .UNINDENT .UNINDENT .SS Commits .SS \fBcommit_version_number\fP .sp Whether or not to commit changes when bumping version. .sp Default: True if \fI\%version_source\fP is \fIcommit\fP, False for other values of \fI\%version_source\fP\&. .SS \fBcommit_subject\fP .sp Git commit subject line. Accepts the following variables as format fields: .TS center; |l|l|. _ T{ Variable T} T{ Contents T} _ T{ \fB{version}\fP T} T{ The new version number in the format \fBX.Y.Z\fP\&. T} _ .TE .sp Default: \fB{version}\fP .SS \fBcommit_message\fP .sp Git commit message body. Accepts the following variables as format fields: .TS center; |l|l|. _ T{ Variable T} T{ Contents T} _ T{ \fB{version}\fP T} T{ The new version number in the format \fBX.Y.Z\fP\&. T} _ .TE .sp Default: \fIAutomatically generated by python\-semantic\-release\fP .SS \fBcommit_author\fP .sp Author used in commits in the format \fBname \fP\&. .sp Default: \fBsemantic\-release \fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are using the built\-in GitHub Action, this is always set to \fBgithub\-actions \fP\&. .UNINDENT .UNINDENT .SS Changelog .SS \fBchangelog_sections\fP .sp Comma\-separated list of sections to display in the changelog. They will be displayed in the order they are given. .sp The available options depend on the commit parser used. .sp Default: \fIfeature, fix, breaking, documentation, performance\fP plus all the default emojis for \fBsemantic_release.history.emoji_parser\fP\&. .SS \fBchangelog_components\fP .sp A comma\-separated list of the import paths of components to include in the changelog. .sp The following components are included in Python Semantic Release: .INDENT 0.0 .IP \(bu 2 \fBsemantic_release.changelog.changelog_headers()\fP .sp \fBOnly component displayed by default.\fP .sp List of commits between this version and the previous one, with sections and headings for each type of change present in the release. .IP \(bu 2 \fBsemantic_release.changelog.changelog_table()\fP .sp List of commits between this version and the previous one, dsplayed in a table. .IP \(bu 2 \fBsemantic_release.changelog.compare_url()\fP .sp Link to view a comparison between this release and the previous one on GitHub. Only appears when running through \fI\%semantic\-release publish\fP\&. .sp If you are using a different HVCS, the link will not be included. .UNINDENT .sp It is also possible to create your own components. Each component is simply a function which returns a string, or \fBNone\fP if it should be skipped, and may take any of the following values as keyword arguments: .TS center; |l|l|. _ T{ \fBchangelog\fP T} T{ A dictionary with section names such as \fBfeature\fP as keys, and the values are lists of (SHA, message) tuples. There is a special section named \fBbreaking\fP for breaking changes, where the same commit can appear more than once with a different message. T} _ T{ \fBchangelog_sections\fP T} T{ A list of sections from \fBchangelog\fP which the user has set to be displayed. T} _ T{ \fBversion\fP T} T{ The current version number in the format \fBX.X.X\fP, or the new version number when publishing. T} _ T{ \fBprevious_version\fP T} T{ The previous version number. Only present when publishing, \fBNone\fP otherwise. T} _ .TE .sp You can should use \fB**kwargs\fP to capture any arguments you don\(aqt need. .SS \fBchangelog_file\fP .sp The name of the file where the changelog is kept, relative to the root of the repo. .sp If this file doesn\(aqt exist, it will be created. .sp Default: \fBCHANGELOG.md\fP\&. .SS \fBchangelog_placeholder\fP .sp A placeholder used to inject the changelog of the current release in the \fI\%changelog_file\fP\&. .sp If the placeholder isn\(aqt present in the file, a warning will be logged and nothing will be updated. .sp Default: \fB\fP\&. .SS \fBchangelog_scope\fP .sp If set to false, \fI**scope:**\fP (when scope is set for a commit) will not be prepended to the description when generating the changelog. .sp Default: \fBTrue\fP\&. .SS \fBchangelog_capitalize\fP .sp If set to false commit messages will not be automatically capitalized when generating the changelog. .sp Default: \fBTrue\fP\&. .SS Distributions .SS \fBupload_to_pypi\fP .sp Deprecated since version 7.20.0: Please use \fI\%upload_to_repository\fP instead .sp If set to false the pypi uploading will be disabled. .sp See \fI\%Artifact Repository\fP which must also be set for this to work. .sp Default: \fItrue\fP .SS \fBupload_to_repository\fP .sp If set to false the artifact uploading to repository will be disabled. .sp See \fI\%Artifact Repository\fP which must also be set for this to work. .sp Default: \fItrue\fP .SS \fBupload_to_pypi_glob_patterns\fP .sp Deprecated since version 7.20.0: Please use \fI\%dist_glob_patterns\fP instead .sp A comma \fI,\fP separated list of glob patterns to use when uploading to pypi. .sp Default: \fI*\fP .SS \fBdist_glob_patterns\fP .sp A comma \fI,\fP separated list of glob patterns to use when uploading dist files to artifact repository. .sp Default: \fI*\fP .SS \fBrepository\fP .sp The repository (package index) name to upload to. Should be a section in \fB~/.pypirc\fP\&. The repositories \fIpypi\fP and \fItestpypi\fP are preconfigured. .sp Default: \fIpypi\fP .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%The .pypirc file\fP \- \fB~/.pypirc\fP documentation .UNINDENT .UNINDENT .UNINDENT .SS \fBrepository_url\fP .sp The repository (package index) URL to upload the package to. .sp See \fI\%Configuring distribution upload\fP for more about uploads to custom repositories. .SS \fBupload_to_release\fP .sp If set to false, do not upload distributions to GitHub releases. If you are not using GitHub, this will be skipped regardless. .SS \fBdist_path\fP .sp The relative path to the folder for dists configured for setuptools. This allows for customized setuptools processes. .sp Default: \fIdist/\fP .SS \fBremove_dist\fP .sp Flag for whether the dist folder should be removed after a release. .sp Default: \fItrue\fP .SS \fBbuild_command\fP .sp Command to build dists. Build output should be stored in the directory configured in \fBdist_path\fP\&. If necessary, multiple commands can be specified using \fB&&\fP, e.g. \fBpip install \-m flit && flit build\fP\&. If set to false, build command is disabled and files should be placed manually in the directory configured in \fBdist_path\fP\&. .sp Default: \fBpython setup.py sdist bdist_wheel\fP .SS HVCS .SS \fBhvcs\fP .sp The name of your hvcs. Currently only \fBgithub\fP and \fBgitlab\fP are supported. .sp Default: \fIgithub\fP .SS \fBhvcs_domain\fP .sp The domain url (without \fI\%https://\fP) of your custom vcs server. .SS \fBhvcs_api_domain\fP .sp The api url (without \fI\%https://\fP) of your custom vcs server. .SS \fBcheck_build_status\fP .sp If enabled, the status of the head commit will be checked and a release will only be created if the status is success. .sp Default: \fIfalse\fP .SS \fBtag_format\fP .sp Git tag format. Accepts the following variables as format fields: .TS center; |l|l|. _ T{ Variable T} T{ Contents T} _ T{ \fB{version}\fP T} T{ The new version number in the format \fBX.Y.Z\fP\&. T} _ .TE .sp Default: \fBv{version}\fP .SS \fBignore_token_for_push\fP .sp 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. .sp Default: \fIfalse\fP .SS Environment Variables .SS \fBDEBUG\fP .sp Set to \fB*\fP to get a lot of debug information. See \fI\%Showing debug output\fP for more. .SS CI .sp See \fI\%Environment checks\fP\&. .SS \fBCIRCLECI\fP .sp Used to check if this is a Circle CI environment. .SS \fBFRIGG\fP .sp Used to check if this is a Frigg environment. .SS \fBSEMAPHORE\fP .sp Used to check if this is a Semaphore environment. .SS \fBTRAVIS\fP .sp Used to check if this is a Travis CI environment. .SS \fBGITLAB_CI\fP .sp Used to check if this is a GitLab CI environment. .SS \fBJENKINS_URL\fP .sp Used to check if this is a Jenkins CI environment. .SS \fBCI_SERVER_HOST\fP .sp Host component of the GitLab instance URL, without protocol and port. Example: \fIgitlab.example.com\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Automatically set in a GitLab CI environment from version 12.1. .UNINDENT .UNINDENT .SS HVCS Authentication .SS \fBGH_TOKEN\fP .sp A personal access token from GitHub. This is used for authenticating when pushing tags, publishing releases etc. See \fI\%Configuring push to Github\fP for usage. .sp To generate a token go to \fI\%https://github.com/settings/tokens\fP and click on \fIPersonal access token\fP\&. .SS \fBGL_TOKEN\fP .sp A personal access token from GitLab. This is used for authenticating when pushing tags, publishing releases etc. .SS \fBGITEA_TOKEN\fP .sp A personal access token from Gitea. This is used for authenticating when pushing tags, publishing releases etc. .SS Artifact Repository .SS \fBPYPI_TOKEN\fP .sp Deprecated since version 7.20.0: Please use \fI\%REPOSITORY_PASSWORD\fP instead .sp Set an API token for publishing to \fI\%https://pypi.org/\fP\&. .SS \fBPYPI_PASSWORD\fP .sp Deprecated since version 7.20.0: Please use \fI\%REPOSITORY_PASSWORD\fP instead .sp Used together with \fI\%PYPI_USERNAME\fP when publishing to \fI\%https://pypi.org/\fP\&. .SS \fBPYPI_USERNAME\fP .sp Deprecated since version 7.20.0: Please use \fI\%REPOSITORY_USERNAME\fP instead .sp Used together with \fI\%PYPI_PASSWORD\fP when publishing to \fI\%https://pypi.org/\fP\&. .SS \fBREPOSITORY_USERNAME\fP .sp Used together with \fI\%REPOSITORY_PASSWORD\fP when publishing artifact. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you use token authentication with \fIpypi\fP set this to \fI__token__\fP .UNINDENT .UNINDENT .SS \fBREPOSITORY_PASSWORD\fP .sp Used together with \fI\%REPOSITORY_USERNAME\fP when publishing artifact. Also used for token when using token authentication. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 You should use token authentication instead of username and password authentication for the following reasons: .INDENT 0.0 .IP \(bu 2 It is \fI\%strongly recommended by PyPI\fP\&. .IP \(bu 2 Tokens can be given access to only a single project, which reduces the possible damage if it is compromised. .IP \(bu 2 You can change your password without having to update it in CI settings. .IP \(bu 2 If your PyPI username is the same as your GitHub and you have it set as a secret in a CI service, they will likely scrub it from the build output. This can break things, for example repository links. .IP \(bu 2 Find more information on \fI\%how to obtain a token\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS \fBREPOSITORY_URL\fP .sp Custom repository (package index) URL to upload the package to. Takes precedence over \fI\%repository_url\fP .sp See \fI\%Configuring distribution upload\fP for more about uploads to custom repositories. .SS Commands .SS \fBsemantic\-release changelog\fP .sp Print the changelog to stdout. .sp If the option \fB\-\-post\fP is used and there is an authentication token configured for your vcs provider (\fI\%GH_TOKEN\fP for GitHub, \fI\%GL_TOKEN\fP for GitLab, \fI\%GITEA_TOKEN\fP for Gitea), the changelog will be posted there too. .SS \fBsemantic\-release version\fP .sp Figure out the new version number, update and commit it, and create a tag. .sp This will not push anything to any remote. All changes are local. .SS \fBsemantic\-release print\-version\fP .sp Print to standard output the new version number. .sp If the option \fB\-\-current\fP is used, it will display the current version number. .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C VERSION=$(semantic\-release print\-version) .ft P .fi .UNINDENT .UNINDENT .SS \fBsemantic\-release publish\fP .sp Publish will do a sequence of things: .INDENT 0.0 .IP 1. 3 Update changelog file. .IP 2. 3 Run \fI\%semantic\-release version\fP\&. .IP 3. 3 Push changes to git. .IP 4. 3 Run \fI\%build_command\fP and upload the distribution file to your repository. .IP 5. 3 Run \fI\%semantic\-release changelog\fP and post to your vcs provider. .IP 6. 3 Attach the files created by \fI\%build_command\fP to GitHub releases. .UNINDENT .sp Some of these steps may be disabled based on your configuration. .SS Common Options .sp Every command understands these flags: .SS \fB\-\-patch\fP .sp Force a patch release, ignoring the version bump determined from commit messages. .SS \fB\-\-minor\fP .sp Force a minor release, ignoring the version bump determined from commit messages. .SS \fB\-\-major\fP .sp Force a major release, ignoring the version bump determined from commit messages. .SS \fB\-\-prerelease\fP .sp Makes the next release a prerelease, version bumps are still determined or can be forced, but the \fIprerelease_tag\fP (see \fI\%prerelease_tag\fP) will be appended to version number. .SS \fB\-\-noop\fP .sp No operations mode. Do not take any actions, only print what will be done. .SS \fB\-\-retry\fP .sp Retry the same release, do not bump. .SS \fB\-\-define\fP .sp Override a configuration value. Takes an argument of the format \fBsetting="value"\fP\&. .SS \fB\-\-verbosity\fP .sp Change the verbosity of Python Semantic Release\(aqs logging. See \fI\%Showing debug output\fP\&. .SS Parsing of commit logs .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ():