PYTHON-SEMANTIC-RELEASE(1)

NAME
python-semantic-release - python-semantic-release Documentation

Python Semantic Release (PSR) provides an automated release mechanism determined by SemVer and Commit Message Conventions for your Git projects.

The purpose of this project is to detect what the next version of the project should be from parsing the latest commit messages. If the commit messages describe changes that would require a major, minor or patch version bump, PSR will automatically bump the version number accordingly. PSR, however, does not stop there but will help automate the whole release process. It will update the project code and distribution artifact, upload the artifact and post changelogs to a remotely hosted Version Control System (VCS).

The tool is designed to run inside of a CI/CD pipeline service, but it can also be run locally.

This project was originally inspired by the semantic-release <https://github.com/semantic-release/semantic-release> project for JavaScript by Stephan Bönnemann, but the codebases have significantly deviated since then, as PSR as driven towards the goal of providing flexible changelogs and simple initial setup.

INSTALLATION

            python3 -m pip install python-semantic-release
            semantic-release --help

Python Semantic Release is also available from conda-forge <https://anaconda.org/conda-forge/python-semantic-release> or as a GitHub Action <#gh-actions>.

Read more about the setup and configuration in our Getting Started Guide.

DOCUMENTATION CONTENTS

  CHANGELOG

  v10.5.3 (2025-12-14)

  🪲 Bug Fixes

    •   cmd-version: Resolve unauthenticated git repo issues for upstream verification, closes #1373 <https://github.com/python-semantic-release/python-semantic-release/issues/1373> (PR#1388 <https://github.com/python-semantic-release/python-semantic-release/pull/1388>, e164f68 <https://github.com/python-semantic-release/python-semantic-release/commit/e164f682bfa4ca1e7cbe77aa068202fd8094eec7>)

    •   github-action: Fix failed signing issue when ssh was missing from action environment, closes #1376 <https://github.com/python-semantic-release/python-semantic-release/issues/1376> (PR#1389 <https://github.com/python-semantic-release/python-semantic-release/pull/1389>, 18b7eda <https://github.com/python-semantic-release/python-semantic-release/commit/18b7edadd7e7dfe42ec43110acf5e1bd8bcd7eb3>)

    •   parser-conventional-monorepo: Fix parser opts validator for outside dir path matches, closes #1380 <https://github.com/python-semantic-release/python-semantic-release/issues/1380> (PR#1382 <https://github.com/python-semantic-release/python-semantic-release/pull/1382>, a51eadd <https://github.com/python-semantic-release/python-semantic-release/commit/a51eadd8414a7e9cbfa66837ee5a840a6331dfa1>)

  v10.5.2 (2025-11-10)

  🪲 Bug Fixes

    •   cmd-version: Toggle verify upstream off when no version commit is made (PR#1370 <https://github.com/python-semantic-release/python-semantic-release/pull/1370>, e0b3b70 <https://github.com/python-semantic-release/python-semantic-release/commit/e0b3b7075a4c98cd7af97e0b8470872c11e7aeb9>)

  v10.5.1 (2025-11-10)

  🪲 Bug Fixes

    •   cmd-version: Fix upstream change detection to succeed without branch tracking (PR#1369 <https://github.com/python-semantic-release/python-semantic-release/pull/1369>, 7086257 <https://github.com/python-semantic-release/python-semantic-release/commit/7086257b641e241dc9a8d742bd62e3698a8b8173>)

  v10.5.0 (2025-11-09)

  ✨ Features

    •   cmd-version: Add automatic repository un-shallowing to version workflow (PR#1366 <https://github.com/python-semantic-release/python-semantic-release/pull/1366>, 90a1ffa <https://github.com/python-semantic-release/python-semantic-release/commit/90a1ffa55c5a1605c59cb26a1797f9a37fdfa784>)

    •   cmd-version: Add functionality to create & update partial version tags (PR#1115 <https://github.com/python-semantic-release/python-semantic-release/pull/1115>, a28f940 <https://github.com/python-semantic-release/python-semantic-release/commit/a28f9401c4b285aa1007b72eb051d42567f33f93>)

    •   cmd-version: Adds c-macro style version definition support to version_variables, closes #1348 <https://github.com/python-semantic-release/python-semantic-release/issues/1348> (PR#1349 <https://github.com/python-semantic-release/python-semantic-release/pull/1349>, 4ce1fca <https://github.com/python-semantic-release/python-semantic-release/commit/4ce1fcac60ac73657a4aaaaa3cb7c4afc7eac2c1>)

    •   cmd-version: Adds upstream check into workflow to prevent commit push collisions (PR#1360 <https://github.com/python-semantic-release/python-semantic-release/pull/1360>, d77193e <https://github.com/python-semantic-release/python-semantic-release/commit/d77193e30807968ba6a26bd356a868db62dc1098>)

  🪲 Bug Fixes

    •   cmd-version: Prevent regular expression errors on tag_format (PR#1367 <https://github.com/python-semantic-release/python-semantic-release/pull/1367>, e7d7aa7 <https://github.com/python-semantic-release/python-semantic-release/commit/e7d7aa74a216cd2fdd78afc1e0e8b6b8044954ec>)

  📖 Documentation

    •   commands: Add description of automated upstream version checking upon version creation (PR#1360 <https://github.com/python-semantic-release/python-semantic-release/pull/1360>, d77193e <https://github.com/python-semantic-release/python-semantic-release/commit/d77193e30807968ba6a26bd356a868db62dc1098>)

    •   configuration: Add description for add_partial_tags setting & usage examples (PR#1115 <https://github.com/python-semantic-release/python-semantic-release/pull/1115>, a28f940 <https://github.com/python-semantic-release/python-semantic-release/commit/a28f9401c4b285aa1007b72eb051d42567f33f93>)

    •   configuration: Fix tag_format definition (PR#1367 <https://github.com/python-semantic-release/python-semantic-release/pull/1367>, e7d7aa7 <https://github.com/python-semantic-release/python-semantic-release/commit/e7d7aa74a216cd2fdd78afc1e0e8b6b8044954ec>)

    •   configuration: Update version_variables examples with a c-macro style replacement (PR#1349 <https://github.com/python-semantic-release/python-semantic-release/pull/1349>, 4ce1fca <https://github.com/python-semantic-release/python-semantic-release/commit/4ce1fcac60ac73657a4aaaaa3cb7c4afc7eac2c1>)

    •   github-actions: Adds release job outputs definition to example (PR#1344 <https://github.com/python-semantic-release/python-semantic-release/pull/1344>, 0fb4875 <https://github.com/python-semantic-release/python-semantic-release/commit/0fb4875fa24ed283ed2d97ff6ab1879669a787ca>)

    •   github-actions: Removed verify upstream status step from example workflow (PR#1360 <https://github.com/python-semantic-release/python-semantic-release/pull/1360>, d77193e <https://github.com/python-semantic-release/python-semantic-release/commit/d77193e30807968ba6a26bd356a868db62dc1098>)

    •   github-actions: Update example to remove need to specify repo checkout's fetch depth (PR#1366 <https://github.com/python-semantic-release/python-semantic-release/pull/1366>, 90a1ffa <https://github.com/python-semantic-release/python-semantic-release/commit/90a1ffa55c5a1605c59cb26a1797f9a37fdfa784>)

    •   uv-integration: Remove verify upstream check from uv integration example (PR#1360 <https://github.com/python-semantic-release/python-semantic-release/pull/1360>, d77193e <https://github.com/python-semantic-release/python-semantic-release/commit/d77193e30807968ba6a26bd356a868db62dc1098>)

    •   uv-integration: Update example to remove need to specify repo checkout's fetch depth (PR#1366 <https://github.com/python-semantic-release/python-semantic-release/pull/1366>, 90a1ffa <https://github.com/python-semantic-release/python-semantic-release/commit/90a1ffa55c5a1605c59cb26a1797f9a37fdfa784>)

  ⚙️ Build System

    •   deps: Bump tomlkit dependency from ~=0.11.0 to ~=0.13.0 (PR#1355 <https://github.com/python-semantic-release/python-semantic-release/pull/1355>, 55c94ec <https://github.com/python-semantic-release/python-semantic-release/commit/55c94ecde1aec47b88aa172d031ab33afa7f795d>)

    •   deps: Change github-actions container image to python:3.14-slim-trixie (PR#1346 <https://github.com/python-semantic-release/python-semantic-release/pull/1346>, 1a23712 <https://github.com/python-semantic-release/python-semantic-release/commit/1a237125badcb597ae7a92db4e01c2ff3293bce8>)

  💡 Additional Release Information

    •   cmd-version: If you were previously handling the unshallowing of a repository clone in your CI/CD pipelines, you may now remove that step from your workflow. PSR will now detect a shallow repository and unshallow it before evaluating the commit history.

  v10.4.1 (2025-09-13)

  🪲 Bug Fixes

    •   cmd-version: Fix error where --no-tag is not respected, closes #1304 <https://github.com/python-semantic-release/python-semantic-release/issues/1304> (PR#1329 <https://github.com/python-semantic-release/python-semantic-release/pull/1329>, b090fa2 <https://github.com/python-semantic-release/python-semantic-release/commit/b090fa2efc0ebfb40bdc572fea307d356af95a3f>)

  📖 Documentation

    •   CHANGELOG: Update hyperlink in v10.4.0's additional info paragraph (PR#1323 <https://github.com/python-semantic-release/python-semantic-release/pull/1323>, 98ef722 <https://github.com/python-semantic-release/python-semantic-release/commit/98ef722b65bd6a37492cf7ec8b0425800f719114>)

    •   getting-started-guide: Remove notice about lack of monorepo support, closes #1326 <https://github.com/python-semantic-release/python-semantic-release/issues/1326> (PR#1327 <https://github.com/python-semantic-release/python-semantic-release/pull/1327>, 3f21f3f <https://github.com/python-semantic-release/python-semantic-release/commit/3f21f3fc47a0dacc11ec95feb2a23f8cf132e77b>)

    •   github-actions: Fix recommended upstream detection script's upstream name parsing (PR#1328 <https://github.com/python-semantic-release/python-semantic-release/pull/1328>, ccc91c0 <https://github.com/python-semantic-release/python-semantic-release/commit/ccc91c09fab45358c7e52b42e6c0607c68c9d8f3>)

  v10.4.0 (2025-09-08)

  ✨ Features

    •   config: Add conventional-monorepo as valid commit_parser type (PR#1143 <https://github.com/python-semantic-release/python-semantic-release/pull/1143>, e18f866 <https://github.com/python-semantic-release/python-semantic-release/commit/e18f86640a78b374a327848b9e2ba868003d1a43>)

    •   parser: Add new conventional-commits standard parser for monorepos, closes #614 <https://github.com/python-semantic-release/python-semantic-release/issues/614> (PR#1143 <https://github.com/python-semantic-release/python-semantic-release/pull/1143>, e18f866 <https://github.com/python-semantic-release/python-semantic-release/commit/e18f86640a78b374a327848b9e2ba868003d1a43>)

  📖 Documentation

    •   Add configuration guide for monorepo use with PSR (PR#1143 <https://github.com/python-semantic-release/python-semantic-release/pull/1143>, e18f866 <https://github.com/python-semantic-release/python-semantic-release/commit/e18f86640a78b374a327848b9e2ba868003d1a43>)

    •   commit-parsers: Introduce conventional commit monorepo parser options & features (PR#1143 <https://github.com/python-semantic-release/python-semantic-release/pull/1143>, e18f866 <https://github.com/python-semantic-release/python-semantic-release/commit/e18f86640a78b374a327848b9e2ba868003d1a43>)

    •   configuration: Update commit_parser option with new conventional-monorepo value (PR#1143 <https://github.com/python-semantic-release/python-semantic-release/pull/1143>, e18f866 <https://github.com/python-semantic-release/python-semantic-release/commit/e18f86640a78b374a327848b9e2ba868003d1a43>)

  💡 Additional Release Information

    •   config: This release introduces a new built-in parser type that can be utilized for monorepo projects. The type value is conventional-monorepo and when specified it will apply the conventional commit parser to a monorepo environment. This parser has specialized options to help handle monorepo projects as well. For more information, please refer to the Monorepo Docs </configuration/configuration-guides/monorepos.html>.

  v10.3.2 (2025-09-06)

  🪲 Bug Fixes

    •   cmd-version: Prevent errors when PSR is executed in non-GitHub CI environments, closes #1315 <https://github.com/python-semantic-release/python-semantic-release/issues/1315> (PR#1322 <https://github.com/python-semantic-release/python-semantic-release/pull/1322>, 4df4be4 <https://github.com/python-semantic-release/python-semantic-release/commit/4df4be465710e3b31ba65487069eccef1eeb8be1>)

  ⚡ Performance Improvements

    •   cmd-version: Re-order operations for faster parsing in version determination (PR#1310 <https://github.com/python-semantic-release/python-semantic-release/pull/1310>, 63e435b <https://github.com/python-semantic-release/python-semantic-release/commit/63e435ba466e1e980b9680d0f759950e5e598a61>)

  📖 Documentation

    •   uv-integration: Add --no-changelog to build step to increase job speed (PR#1316 <https://github.com/python-semantic-release/python-semantic-release/pull/1316>, e1aece1 <https://github.com/python-semantic-release/python-semantic-release/commit/e1aece18ae1998b1523be65b1e569837a7054251>)

  💡 Additional Release Information

    •   cmd-version: Unfortunately, PSR introduced a bug in 10.3.0 when attempting to provide more CI outputs for GitHub Actions. It required our GitHub client interface to be loaded and even if it was not using GitHub CI to be run. This caused errors in Gitea and likely GitLab/Bitbucket environments. This change prevents that from happening but if any users pipelines were intentionally presenting the environment variable "GITHUB_OUTPUT" to enable action output to enable passing along internal outputs of PSR then their hack will no longer work after this change.

  v10.3.1 (2025-08-06)

  🪲 Bug Fixes

    •   github-actions: Refactor the action output error checking for non-release executions, closes #1307 <https://github.com/python-semantic-release/python-semantic-release/issues/1307> (PR#1308 <https://github.com/python-semantic-release/python-semantic-release/pull/1308>, 5385724 <https://github.com/python-semantic-release/python-semantic-release/commit/538572426cb30dd4d8c99cea660e290b56361f75>)

  📖 Documentation

    •   github-actions: Adjust docs for direct links to action example workflows, closes #1303 <https://github.com/python-semantic-release/python-semantic-release/issues/1303> (PR#1309 <https://github.com/python-semantic-release/python-semantic-release/pull/1309>, 8efebe2 <https://github.com/python-semantic-release/python-semantic-release/commit/8efebe281be2deab1b203cd01d9aedf1542c4ad4>)

  v10.3.0 (2025-08-04)

  ✨ Features

    •   github-actions: Add commit_sha as a GitHub Actions output value, closes #717 <https://github.com/python-semantic-release/python-semantic-release/issues/717> (PR#1289 <https://github.com/python-semantic-release/python-semantic-release/pull/1289>, 39b647b <https://github.com/python-semantic-release/python-semantic-release/commit/39b647ba62e242342ef5a0d07cb0cfdfa7769865>)

    •   github-actions: Add previous_version as a GitHub Actions output value (PR#1302 <https://github.com/python-semantic-release/python-semantic-release/pull/1302>, c0197b7 <https://github.com/python-semantic-release/python-semantic-release/commit/c0197b711cfa83f5b13f9ae4f37e555b26f544d9>)

    •   github-actions: Add release_notes as a GitHub Actions output value (PR#1300 <https://github.com/python-semantic-release/python-semantic-release/pull/1300>, a3fd23c <https://github.com/python-semantic-release/python-semantic-release/commit/a3fd23cb0e49f74cb4a345048609d3643a665782>)

    •   github-actions: Add release link as a GitHub Actions output value (PR#1301 <https://github.com/python-semantic-release/python-semantic-release/pull/1301>, 888aea1 <https://github.com/python-semantic-release/python-semantic-release/commit/888aea1e450513ac7339c72d8b50fabdb4ac177b>)

  🪲 Bug Fixes

    •   github-actions: Fix variable output newlines (PR#1300 <https://github.com/python-semantic-release/python-semantic-release/pull/1300>, a3fd23c <https://github.com/python-semantic-release/python-semantic-release/commit/a3fd23cb0e49f74cb4a345048609d3643a665782>)

    •   util: Fixes no-op log output when commit message contains square-brackets, closes #1251 <https://github.com/python-semantic-release/python-semantic-release/issues/1251> (PR#1287 <https://github.com/python-semantic-release/python-semantic-release/pull/1287>, f25883f <https://github.com/python-semantic-release/python-semantic-release/commit/f25883f8403365b787e7c3e86d2d982906804621>)

  📖 Documentation

    •   getting-started: Fixes changelog.exclude_commit_patterns example in startup guide, closes #1291 <https://github.com/python-semantic-release/python-semantic-release/issues/1291> (PR#1292 <https://github.com/python-semantic-release/python-semantic-release/pull/1292>, 2ce2e94 <https://github.com/python-semantic-release/python-semantic-release/commit/2ce2e94e1930987a88c0a5e3d59baa7cb717f557>)

    •   github-actions: Add description of commit_sha GitHub Action output in docs (PR#1289 <https://github.com/python-semantic-release/python-semantic-release/pull/1289>, 39b647b <https://github.com/python-semantic-release/python-semantic-release/commit/39b647ba62e242342ef5a0d07cb0cfdfa7769865>)

    •   github-actions: Add description of previous_release GitHub Action output (PR#1302 <https://github.com/python-semantic-release/python-semantic-release/pull/1302>, c0197b7 <https://github.com/python-semantic-release/python-semantic-release/commit/c0197b711cfa83f5b13f9ae4f37e555b26f544d9>)

    •   github-actions: Add description of release_notes GitHub Action output (PR#1300 <https://github.com/python-semantic-release/python-semantic-release/pull/1300>, a3fd23c <https://github.com/python-semantic-release/python-semantic-release/commit/a3fd23cb0e49f74cb4a345048609d3643a665782>)

    •   github-actions: Add description of release link GitHub Action output (PR#1301 <https://github.com/python-semantic-release/python-semantic-release/pull/1301>, 888aea1 <https://github.com/python-semantic-release/python-semantic-release/commit/888aea1e450513ac7339c72d8b50fabdb4ac177b>)

    •   README: Update broken links to match re-located destinations (PR#1285 <https://github.com/python-semantic-release/python-semantic-release/pull/1285>, f4ec792 <https://github.com/python-semantic-release/python-semantic-release/commit/f4ec792d73acb34b8f5183ec044a301b593f16f0>)

  v10.2.0 (2025-06-29)

  ✨ Features

    •   cmd-version: Adds PACKAGE_NAME value into build command environment (db9bc13 <https://github.com/python-semantic-release/python-semantic-release/commit/db9bc132c8a0398f2cce647730c69a32ca35ba51>)

  📖 Documentation

    •   configuration: Update build command environment definition to include PACKAGE_NAME variable (4aa3805 <https://github.com/python-semantic-release/python-semantic-release/commit/4aa38059ce6b33ca23a547473e9fb8a19d3ffbe1>)

    •   uv-integration: Fix configuration guide for uv usage to ensure lock file update (5390145 <https://github.com/python-semantic-release/python-semantic-release/commit/5390145503b4d5dcca8f323e1ba6c5bec0bd079b>)

  v10.1.0 (2025-06-12)

  ✨ Features

    •   cmd-version: Always stage version stamped files & changelog even with --no-commit, closes #1211 <https://github.com/python-semantic-release/python-semantic-release/issues/1211> (PR#1214 <https://github.com/python-semantic-release/python-semantic-release/pull/1214>, de62334 <https://github.com/python-semantic-release/python-semantic-release/commit/de623344cd18b3dbe05823eb90fdd010c5505c92>)

  📖 Documentation

    •   cmd-version: Improve command description & include common uses (PR#1214 <https://github.com/python-semantic-release/python-semantic-release/pull/1214>, de62334 <https://github.com/python-semantic-release/python-semantic-release/commit/de623344cd18b3dbe05823eb90fdd010c5505c92>)

    •   configuration-guide: Add how-to guide for uv integration (PR#1214 <https://github.com/python-semantic-release/python-semantic-release/pull/1214>, de62334 <https://github.com/python-semantic-release/python-semantic-release/commit/de623344cd18b3dbe05823eb90fdd010c5505c92>)

    •   github-actions: Clarify with examples of the root_options v10 migration change (PR#1271 <https://github.com/python-semantic-release/python-semantic-release/pull/1271>, fbb63ec <https://github.com/python-semantic-release/python-semantic-release/commit/fbb63ec76142ea903d8a0401369ec251abbec0fe>)

  ⚙️ Build System

    •   deps: Expand python-gitlab dependency to include v6.0.0 (PR#1273 <https://github.com/python-semantic-release/python-semantic-release/pull/1273>, 99fc9cc <https://github.com/python-semantic-release/python-semantic-release/commit/99fc9ccabbae9adf5646731591080366eacbe03c>)

  v10.0.2 (2025-05-26)

  🪲 Bug Fixes

    •   github-actions: Add filesystem UID/GID fixer after action workspace modification (PR#1262 <https://github.com/python-semantic-release/python-semantic-release/pull/1262>, 93e23c8 <https://github.com/python-semantic-release/python-semantic-release/commit/93e23c8993fe6f113095bfcd5089684f403cc6b9>)

  v10.0.1 (2025-05-25)

  🪲 Bug Fixes

    •   github-actions: Bump the github-actions dependency to v10.0.0 (PR#1255 <https://github.com/python-semantic-release/python-semantic-release/pull/1255>, 2803676 <https://github.com/python-semantic-release/python-semantic-release/commit/2803676cf26c52177fa98d9144934853744a22bb>)

  v10.0.0 (2025-05-25)

  ✨ Features

    •   cmd-version: Enable version_variables version stamp of vars with double-equals (PR#1244 <https://github.com/python-semantic-release/python-semantic-release/pull/1244>, 080e4bc <https://github.com/python-semantic-release/python-semantic-release/commit/080e4bcb14048a2dd10445546a7ee3159b3ab85c>)

    •   parser-conventional: Set parser to evaluate all squashed commits by default (6fcdc99 <https://github.com/python-semantic-release/python-semantic-release/commit/6fcdc99e9462b1186ea9488fc14e4e18f8c7fdb3>)

    •   parser-conventional: Set parser to ignore merge commits by default (59bf084 <https://github.com/python-semantic-release/python-semantic-release/commit/59bf08440a15269afaac81d78dd03ee418f9fd6b>)

    •   parser-emoji: Set parser to evaluate all squashed commits by default (514a922 <https://github.com/python-semantic-release/python-semantic-release/commit/514a922fa87721e2500062dcae841bedd84dc1fe>)

    •   parser-emoji: Set parser to ignore merge commits by default (8a51525 <https://github.com/python-semantic-release/python-semantic-release/commit/8a5152573b9175f01be06d0c4531ea0ca4de8dd4>)

    •   parser-scipy: Set parser to evaluate all squashed commits by default (634fffe <https://github.com/python-semantic-release/python-semantic-release/commit/634fffea29157e9b6305b21802c78ac245454265>)

    •   parser-scipy: Set parser to ignore merge commits by default (d4f128e <https://github.com/python-semantic-release/python-semantic-release/commit/d4f128e75e33256c0163fbb475c7c41e18f65147>)

  🪲 Bug Fixes

    •   changelog-md: Change to 1-line descriptions in markdown template, closes #733 <https://github.com/python-semantic-release/python-semantic-release/issues/733> (e7ac155 <https://github.com/python-semantic-release/python-semantic-release/commit/e7ac155a91fc2e735d3cbf9b66fb4e5ff40a1466>)

    •   changelog-rst: Change to 1-line descriptions in the default ReStructuredText template, closes #733 <https://github.com/python-semantic-release/python-semantic-release/issues/733> (731466f <https://github.com/python-semantic-release/python-semantic-release/commit/731466fec4e06fe71f6c4addd4ae2ec2182ae9c1>)

    •   cli: Adjust verbosity parameter to enable silly-level logging (bd3e7bf <https://github.com/python-semantic-release/python-semantic-release/commit/bd3e7bfa86d53a03f03ac419399847712c523b02>)

    •   github-action: Resolve command injection vulnerability in action script (fb3da27 <https://github.com/python-semantic-release/python-semantic-release/commit/fb3da27650ff15bcdb3b7badc919bd8a9a73238d>)

    •   parser-conventional: Remove breaking change footer messages from commit descriptions (b271cbb <https://github.com/python-semantic-release/python-semantic-release/commit/b271cbb2d3e8b86d07d1358b2e7424ccff6ae186>)

    •   parser-conventional: Remove issue footer messages from commit descriptions (b1bb0e5 <https://github.com/python-semantic-release/python-semantic-release/commit/b1bb0e55910715754eebef6cb5b21ebed5ee8d68>)

    •   parser-conventional: Remove PR/MR references from commit subject line (eed63fa <https://github.com/python-semantic-release/python-semantic-release/commit/eed63fa9f6e762f55700fc85ef3ebdc0d3144f21>)

    •   parser-conventional: Remove release notice footer messages from commit descriptions (7e8dc13 <https://github.com/python-semantic-release/python-semantic-release/commit/7e8dc13c0b048a95d01f7aecfbe4eeedcddec9a4>)

    •   parser-emoji: Remove issue footer messages from commit descriptions (b757603 <https://github.com/python-semantic-release/python-semantic-release/commit/b757603e77ebe26d8a14758d78fd21163a9059b2>)

    •   parser-emoji: Remove PR/MR references from commit subject line (16465f1 <https://github.com/python-semantic-release/python-semantic-release/commit/16465f133386b09627d311727a6f8d24dd8f174f>)

    •   parser-emoji: Remove release notice footer messages from commit descriptions (b6307cb <https://github.com/python-semantic-release/python-semantic-release/commit/b6307cb649043bbcc7ad9f15ac5ac6728914f443>)

    •   parser-scipy: Remove issue footer messages from commit descriptions (3cfee76 <https://github.com/python-semantic-release/python-semantic-release/commit/3cfee76032662bda6fbdd7e2585193213e4f9da2>)

    •   parser-scipy: Remove PR/MR references from commit subject line (da4140f <https://github.com/python-semantic-release/python-semantic-release/commit/da4140f3e3a2ed03c05064f35561b4584f517105>)

    •   parser-scipy: Remove release notice footer messages from commit descriptions (58308e3 <https://github.com/python-semantic-release/python-semantic-release/commit/58308e31bb6306aac3a985af01eb779dc923d3f0>)

  📖 Documentation

    •   Refactor documentation page navigation (4e52f4b <https://github.com/python-semantic-release/python-semantic-release/commit/4e52f4bba46e96a4762f97d306f15ae52c5cea1b>)

    •   algorithm: Remove out-of-date algorithm description (6cd0fbe <https://github.com/python-semantic-release/python-semantic-release/commit/6cd0fbeb44e16d394c210216c7099afa51f5a4a3>)

    •   commit-parsing: Define limitation of revert commits with the scipy parser (5310d0c <https://github.com/python-semantic-release/python-semantic-release/commit/5310d0c700840538f27874394b9964bf09cd69b1>)

    •   configuration: Change default value for allow_zero_version in the description (203d29d <https://github.com/python-semantic-release/python-semantic-release/commit/203d29d9d6b8e862eabe2f99dbd27eabf04e75e2>)

    •   configuration: Change the default for the base changelog's mask_initial_release value (5fb02ab <https://github.com/python-semantic-release/python-semantic-release/commit/5fb02ab6e3b8278ecbf92ed35083ffb595bc19b8>)

    •   configuration: Change the default value for changelog.mode in the setting description (0bed906 <https://github.com/python-semantic-release/python-semantic-release/commit/0bed9069df67ae806ad0a15f8434ac4efcc6ba31>)

    •   configuration: Update version_variables section to include double-equals operand support (PR#1244 <https://github.com/python-semantic-release/python-semantic-release/pull/1244>, 080e4bc <https://github.com/python-semantic-release/python-semantic-release/commit/080e4bcb14048a2dd10445546a7ee3159b3ab85c>)

    •   contributing: Refactor contributing & contributors layout (8bed5bc <https://github.com/python-semantic-release/python-semantic-release/commit/8bed5bcca4a5759af0e3fb24eadf14aa4e4f53c9>)

    •   github-actions: Add reference to manual release workflow example (6aad7f1 <https://github.com/python-semantic-release/python-semantic-release/commit/6aad7f17e64fb4717ddd7a9e94d2a730be6a3bd9>)

    •   github-actions: Change recommended workflow to separate release from deploy (67b2ae0 <https://github.com/python-semantic-release/python-semantic-release/commit/67b2ae0050cce540a4126fe280cca6dc4bcf5d3f>)

    •   github-actions: Update python-semantic-release/publish-action parameter notes (c4d45ec <https://github.com/python-semantic-release/python-semantic-release/commit/c4d45ec46dfa81f645c25ea18ffffe9635922603>)

    •   github-actions: Update PSR action parameter documentation (a082896 <https://github.com/python-semantic-release/python-semantic-release/commit/a08289693085153effdafe3c6ff235a1777bb1fa>)

    •   upgrading: Re-locate version upgrade guides into Upgrading PSR (a5f5e04 <https://github.com/python-semantic-release/python-semantic-release/commit/a5f5e042ae9af909ee9e3ddf57c78adbc92ce378>)

    •   upgrading-v10: Added migration guide for v9 to v10 (4ea92ec <https://github.com/python-semantic-release/python-semantic-release/commit/4ea92ec34dcd45d8cbab24e38e55289617b2d728>)

  ⚙️ Build System

    •   deps: Prevent update to click@8.2.0 (PR#1245 <https://github.com/python-semantic-release/python-semantic-release/pull/1245>, 4aa6a6e <https://github.com/python-semantic-release/python-semantic-release/commit/4aa6a6edbff75889e09f32f7cba52cb90c9fb626>)

  ♻️ Refactoring

    •   config: Change allow_zero_version default to false (c6b6eab <https://github.com/python-semantic-release/python-semantic-release/commit/c6b6eabbfe100d2c741620eb3fa12a382531fa94>)

    •   config: Change changelog.default_templates.mask_initial_release default to true (0e114c3 <https://github.com/python-semantic-release/python-semantic-release/commit/0e114c3458a24b87bfd2d6b0cd3f5cfdc9497084>)

    •   config: Change changelog.mode default to update (7d39e76 <https://github.com/python-semantic-release/python-semantic-release/commit/7d39e7675f859463b54751d59957b869d5d8395c>)

  💥 Breaking Changes

See also:
        For a summarized walkthrough, check out our v10 migration guide <../upgrading/10-upgrade.html> as well.

    •   changelog-md: The default Markdown changelog template and release notes template will no longer print out the entire commit message contents, instead, it will only print the commit subject line. This comes to meet the high demand of better formatted changelogs and requests for subject line only. Originally, it was a decision to not hide commit subjects that were included in the commit body via the git merge --squash command and PSR did not have another alternative. At this point, all the built-in parsers have the ability to parse squashed commits and separate them out into their own entry on the changelog. Therefore, the default template no longer needs to write out the full commit body. See the commit parser options if you want to enable/disable parsing squash commits.

    •   changelog-rst: The default ReStructured changelog template will no longer print out the entire commit message contents, instead, it will only print the commit subject line. This comes to meet the high demand of better formatted changelogs and requests for subject line only. Originally, it was a decision to not hide commit subjects that were included in the commit body via the git merge --squash command and PSR did not have another alternative. At this point, all the built-in parsers have the ability to parse squashed commits and separate them out into their own entry on the changelog. Therefore, the default template no longer needs to write out the full commit body. See the commit parser options if you want to enable/disable parsing squash commits.

    •   config: This release switches the allow_zero_version default to false. This change is to encourage less 0.x releases as the default but rather allow the experienced developer to choose when 0.x is appropriate. There are way too many projects in the ecosystems that never leave 0.x and that is problematic for the industry tools that help auto-update based on SemVer. We should strive for publishing usable tools and maintaining good forethought for when compatibility must break. If your configuration already sets the allow_zero_version value, this change will have no effect on your project. If you want to use 0.x versions, from the start then change allow_zero_version to true in your configuration.

    •   config: This release switches the changelog.default_templates.mask_initial_release default to true. This change is intended to toggle better recommended outputs of the default changelog. Conceptually, the very first release is hard to describe--one can only provide new features as nothing exists yet for the end user. No changelog should be written as there is no start point to compare the "changes" to. The recommendation instead is to only list a simple message as Initial Release. This is now the default for PSR when providing the very first release (no pre-existing tags) in the changelog and release notes. If your configuration already sets the changelog.default_templates.mask_initial_release value, then this change will have no effect on your project. If you do NOT want to mask the first release information, then set changelog.default_templates.mask_initial_release to false in your configuration.

    •   config: This release switches the changelog.mode default to update. In this mode, if a changelog exists, PSR will update the changelog IF AND ONLY IF the configured insertion flag exists in the changelog. The Changelog output will remain unchanged if no insertion flag exists. The insertion flag may be configured with the changelog.insertion_flag setting. When upgrading to v10, you must add the insertion flag manually or you can just delete the changelog file and run PSR's changelog generation and it will rebuild the changelog (similar to init mode) but it will add the insertion flag. If your configuration already sets the changelog.mode value, then this change will have no effect on your project. If you would rather the changelog be generated from scratch every release, than set the changelog.mode value to init in your configuration.

    •   github-action: The root_options action input parameter has been removed because it created a command injection vulnerability for arbitrary code to execute within the container context of the GitHub action if a command injection code was provided as part of the root_options parameter string. To eliminate the vulnerability, each relevant option that can be provided to semantic-release has been individually added as its own parameter and will be processed individually to prevent command injection. Please review our Github Actions Configuration <https://github.com/python-semantic-release/python-semantic-release/blob/v10.0.0/docs/configuration/automatic-releases/github-actions.rst> page to review the newly available configuration options that replace the root_options parameter.

    •   parser-conventional: Any breaking change footer messages that the conventional commit parser detects will now be removed from the commit.descriptions[] list but maintained in and only in the commit.breaking_descriptions[] list. Previously, the descriptions included all text from the commit message but that was redundant as the default changelog now handles breaking change footers in its own section.

    •   parser-conventional, parser-emoji, parser-scipy: Any issue resolution footers that the parser detects will now be removed from the commit.descriptions[] list. Previously, the descriptions included all text from the commit message but now that the parser pulls out the issue numbers the numbers will be included in the commit.linked_issues tuple for user extraction in any changelog generation.

    •   parser-conventional, parser-emoji, parser-scipy: Any release notice footer messages that the commit parser detects will now be removed from the commit.descriptions[] list but maintained in and only in the commit.notices[] list. Previously, the descriptions included all text from the commit message but that was redundant as the default changelog now handles release notice footers in its own section.

    •   parser-conventional, parser-emoji, parser-scipy: Generally, a pull request or merge request number reference is included in the subject line at the end within parentheses on some common VCS's like GitHub. PSR now looks for this reference and extracts it into the commit.linked_merge_request and the commit.linked_pull_request attributes of a commit object. Since this is now pulled out individually, it is cleaner to remove this from the first line of the commit.descriptions list (ie. the subject line) so that changelog macros do not have to replace the text but instead only append a PR/MR link to the end of the line. The reference does maintain the PR/MR prefix indicator (# or !).

    •   parser-conventional, parser-emoji, parser-scipy: The configuration setting commit_parser_options.ignore_merge_commits is now set to true by default. The feature to ignore squash commits was introduced in v9.18.0 and was originally set to false to prevent unexpected results on a non-breaking update. The ignore merge commits feature prevents additional unnecessary processing on a commit message that likely will not match a commit message syntax. Most merge commits are syntactically pre-defined by Git or Remote Version Control System (ex. GitHub, etc.) and do not follow a commit convention (nor should they). The larger issue with merge commits is that they ultimately are a full copy of all the changes that were previously created and committed. The merge commit itself ensures that the previous commit tree is maintained in history, therefore the commit message always exists. If merge commits are parsed, it generally creates duplicate messages that will end up in your changelog, which is less than desired in most cases. If you have previously used the changelog.exclude_commit_patterns functionality to ignore merge commit messages then you will want this setting set to true to improve parsing speed. You can also now remove the merge commit exclude pattern from the list as well to improve parsing speed. If this functionality is not desired, you will need to update your configuration to change the new setting to false.

    •   parser-conventional, parser-emoji, parser-scipy: The configuration setting commit_parser_options.parse_squash_commits is now set to true by default. The feature to parse squash commits was introduced in v9.17.0 and was originally set to false to prevent unexpected results on a non-breaking update. The parse squash commits feature attempts to find additional commits of the same commit type within the body of a single commit message. When squash commits are found, Python Semantic Release will separate out each commit into its own artificial commit object and parse them individually. This potentially can change the resulting version bump if a larger bump was detected within the squashed components. It also allows for the changelog and release notes to separately order and display each commit as originally written. If this is not desired, you will need to update your configuration to change the new setting to false.

  v9.21.1 (2025-05-05)

  🪲 Bug Fixes

    •   changelog-filters: Fixes url resolution when prefix & path share letters, closes #1204 <https://github.com/python-semantic-release/python-semantic-release/issues/1204> (PR#1239 <https://github.com/python-semantic-release/python-semantic-release/pull/1239>, f61f8a3 <https://github.com/python-semantic-release/python-semantic-release/commit/f61f8a38a1a3f44a7a56cf9dcb7dde748f90ca1e>)

  📖 Documentation

    •   github-actions: Expound on monorepo example to include publishing actions (PR#1229 <https://github.com/python-semantic-release/python-semantic-release/pull/1229>, 550e85f <https://github.com/python-semantic-release/python-semantic-release/commit/550e85f5ec2695d5aa680014127846d58c680e31>)

  ⚙️ Build System

    •   deps: Bump rich dependency from 13.0 to 14.0 (PR#1224 <https://github.com/python-semantic-release/python-semantic-release/pull/1224>, 691536e <https://github.com/python-semantic-release/python-semantic-release/commit/691536e98f311d0fc6d29a72c41ce5a65f1f4b6c>)

    •   deps: Expand python-gitlab dependency to include v5.0.0 (PR#1228 <https://github.com/python-semantic-release/python-semantic-release/pull/1228>, a0cd1be <https://github.com/python-semantic-release/python-semantic-release/commit/a0cd1be4e3aa283cbdc544785e5f895c8391dfb8>)

  v9.21.0 (2025-02-23)

  ✨ Features

    •   Add package name variant, python-semantic-release, project script, closes #1195 <https://github.com/python-semantic-release/python-semantic-release/issues/1195> (PR#1199 <https://github.com/python-semantic-release/python-semantic-release/pull/1199>, 1ac97bc <https://github.com/python-semantic-release/python-semantic-release/commit/1ac97bc74c69ce61cec98242c19bf8adc1d37fb9>)

  📖 Documentation

    •   github-actions: Update example workflow to handle rapid merges (PR#1200 <https://github.com/python-semantic-release/python-semantic-release/pull/1200>, 1a4116a <https://github.com/python-semantic-release/python-semantic-release/commit/1a4116af4b999144998cf94cf84c9c23ff2e352f>)

  v9.20.0 (2025-02-17)

  ✨ Features

    •   cmd-version: Enable stamping of tag formatted versions into files, closes #846 <https://github.com/python-semantic-release/python-semantic-release/issues/846> (PR#1190 <https://github.com/python-semantic-release/python-semantic-release/pull/1190>, 8906d8e <https://github.com/python-semantic-release/python-semantic-release/commit/8906d8e70467af1489d797ec8cb09b1f95e5d409>)

    •   cmd-version: Extend version_variables to stamp versions with @ symbol separator, closes #1156 <https://github.com/python-semantic-release/python-semantic-release/issues/1156> (PR#1185 <https://github.com/python-semantic-release/python-semantic-release/pull/1185>, 23f69b6 <https://github.com/python-semantic-release/python-semantic-release/commit/23f69b6ac206d111b1e566367f9b2f033df5c87a>)

  📖 Documentation

    •   configuration: Add usage information for tag format version stamping (PR#1190 <https://github.com/python-semantic-release/python-semantic-release/pull/1190>, 8906d8e <https://github.com/python-semantic-release/python-semantic-release/commit/8906d8e70467af1489d797ec8cb09b1f95e5d409>)

    •   configuration: Clarify version_variables config description & @ separator usage (PR#1185 <https://github.com/python-semantic-release/python-semantic-release/pull/1185>, 23f69b6 <https://github.com/python-semantic-release/python-semantic-release/commit/23f69b6ac206d111b1e566367f9b2f033df5c87a>)

  ⚙️ Build System

    •   deps: Add deprecated~=1.2 for deprecation notices & sphinx documentation (PR#1190 <https://github.com/python-semantic-release/python-semantic-release/pull/1190>, 8906d8e <https://github.com/python-semantic-release/python-semantic-release/commit/8906d8e70467af1489d797ec8cb09b1f95e5d409>)

  v9.19.1 (2025-02-11)

  🪲 Bug Fixes

    •   changelog: Standardize heading format for across all version sections (PR#1182 <https://github.com/python-semantic-release/python-semantic-release/pull/1182>, 81f9e80 <https://github.com/python-semantic-release/python-semantic-release/commit/81f9e80c3df185ef5e553e024b903ce153e14304>)

    •   changelog-md: Standardize heading format for extra release information (PR#1182 <https://github.com/python-semantic-release/python-semantic-release/pull/1182>, 81f9e80 <https://github.com/python-semantic-release/python-semantic-release/commit/81f9e80c3df185ef5e553e024b903ce153e14304>)

    •   changelog-rst: Standardize heading format for extra release information (PR#1182 <https://github.com/python-semantic-release/python-semantic-release/pull/1182>, 81f9e80 <https://github.com/python-semantic-release/python-semantic-release/commit/81f9e80c3df185ef5e553e024b903ce153e14304>)

    •   config: Handle invalid commit_parser type gracefully (PR#1180 <https://github.com/python-semantic-release/python-semantic-release/pull/1180>, 903c8ba <https://github.com/python-semantic-release/python-semantic-release/commit/903c8ba68d797f7cd9e5025c9a3a3ad471c805ae>)

    •   release-notes: Standardize heading format for extra release information (PR#1182 <https://github.com/python-semantic-release/python-semantic-release/pull/1182>, 81f9e80 <https://github.com/python-semantic-release/python-semantic-release/commit/81f9e80c3df185ef5e553e024b903ce153e14304>)

  📖 Documentation

    •   Fix spelling errors & inaccurate descriptions (55d4a05 <https://github.com/python-semantic-release/python-semantic-release/commit/55d4a05ff56321cf9874f8f302fbe7e5163ad4f7>)

    •   automatic-releases: Declutter the table of contents for automatic release guides (e8343ee <https://github.com/python-semantic-release/python-semantic-release/commit/e8343eeb38d3b4e18953ac0f97538df396d22b76>)

    •   commit-parsing: Update reference to section name of additional release info (PR#1182 <https://github.com/python-semantic-release/python-semantic-release/pull/1182>, 81f9e80 <https://github.com/python-semantic-release/python-semantic-release/commit/81f9e80c3df185ef5e553e024b903ce153e14304>)

  v9.19.0 (2025-02-10)

  ✨ Features

    •   parser-conventional: Add official conventional-commits parser (PR#1177 <https://github.com/python-semantic-release/python-semantic-release/pull/1177>, 27ddf84 <https://github.com/python-semantic-release/python-semantic-release/commit/27ddf840f8c812361c60bac9cf0b110d401f33d6>)

  📖 Documentation

    •   Update references to Angular parser to Conventional Commit Parser (PR#1177 <https://github.com/python-semantic-release/python-semantic-release/pull/1177>, 27ddf84 <https://github.com/python-semantic-release/python-semantic-release/commit/27ddf840f8c812361c60bac9cf0b110d401f33d6>)

  💡 Additional Release Information

    •   parser-conventional: The 'angular' commit parser has been renamed to 'conventional' to match the official conventional-commits standard for which the 'angular' parser has evolved into. Please update your configurations to specify 'conventional' as the 'commit_parser' value in place of 'angular'. The 'angular' type will be removed in v11.

  v9.18.1 (2025-02-08)

  🪲 Bug Fixes

    •   config: Refactors default token resolution to prevent pre-mature insecure URL error, closes #1074 <https://github.com/python-semantic-release/python-semantic-release/issues/1074>, #1169 <https://github.com/python-semantic-release/python-semantic-release/issues/1169> (PR#1173 <https://github.com/python-semantic-release/python-semantic-release/pull/1173>, 37db258 <https://github.com/python-semantic-release/python-semantic-release/commit/37db2581620ad02e66716a4b3b365aa28abe65f8>)

  v9.18.0 (2025-02-06)

  ✨ Features

    •   Add create_release_url & format_w_official_vcs_name filters (PR#1161 <https://github.com/python-semantic-release/python-semantic-release/pull/1161>, f853cf0 <https://github.com/python-semantic-release/python-semantic-release/commit/f853cf059b3323d7888b06fde09142184e7964e8>)

    •   changelog: Add create_pypi_url filter to jinja template render context (PR#1160 <https://github.com/python-semantic-release/python-semantic-release/pull/1160>, 45d49c3 <https://github.com/python-semantic-release/python-semantic-release/commit/45d49c3da75a7f08c86fc9bab5d232a9b37d9e72>)

    •   changelog: Add additional release info to changeling from commit NOTICE's (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   changelog-md: Add additional release info section to default markdown template, closes #223 <https://github.com/python-semantic-release/python-semantic-release/issues/223> (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   changelog-rst: Add additional release info section to default ReStructuredText template, closes #223 <https://github.com/python-semantic-release/python-semantic-release/issues/223> (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   commit-parser: Enable parsers to identify additional release notices from commit msgs (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   parser-angular: Add a ignore_merge_commits option to discard parsing merge commits (PR#1164 <https://github.com/python-semantic-release/python-semantic-release/pull/1164>, 463e43b <https://github.com/python-semantic-release/python-semantic-release/commit/463e43b897ee80dfaf7ce9d88d22ea8e652bcf55>)

    •   parser-angular: Add functionality to parse out NOTICE: prefixed statements in commits, closes #223 <https://github.com/python-semantic-release/python-semantic-release/issues/223> (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   parser-emoji: Add a ignore_merge_commits option to discard parsing merge commits (PR#1164 <https://github.com/python-semantic-release/python-semantic-release/pull/1164>, 463e43b <https://github.com/python-semantic-release/python-semantic-release/commit/463e43b897ee80dfaf7ce9d88d22ea8e652bcf55>)

    •   parser-emoji: Add functionality to parse out NOTICE: prefixed statements in commits, closes #223 <https://github.com/python-semantic-release/python-semantic-release/issues/223> (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   parsers: Add option ignore_merge_commits to discard parsing merge commits (PR#1164 <https://github.com/python-semantic-release/python-semantic-release/pull/1164>, 463e43b <https://github.com/python-semantic-release/python-semantic-release/commit/463e43b897ee80dfaf7ce9d88d22ea8e652bcf55>)

    •   release-notes: Add license information to default release notes template, closes #228 <https://github.com/python-semantic-release/python-semantic-release/issues/228> (PR#1167 <https://github.com/python-semantic-release/python-semantic-release/pull/1167>, 41172c1 <https://github.com/python-semantic-release/python-semantic-release/commit/41172c1272a402e94e3c68571d013cbdcb5b9023>)

    •   vcs-bitbucket: Add format_w_official_vcs_name filter function (PR#1161 <https://github.com/python-semantic-release/python-semantic-release/pull/1161>, f853cf0 <https://github.com/python-semantic-release/python-semantic-release/commit/f853cf059b3323d7888b06fde09142184e7964e8>)

    •   vcs-gitea: Add create_release_url & format_w_official_vcs_name filter functions (PR#1161 <https://github.com/python-semantic-release/python-semantic-release/pull/1161>, f853cf0 <https://github.com/python-semantic-release/python-semantic-release/commit/f853cf059b3323d7888b06fde09142184e7964e8>)

    •   vcs-github: Add create_release_url & format_w_official_vcs_name filter functions (PR#1161 <https://github.com/python-semantic-release/python-semantic-release/pull/1161>, f853cf0 <https://github.com/python-semantic-release/python-semantic-release/commit/f853cf059b3323d7888b06fde09142184e7964e8>)

    •   vcs-gitlab: Add create_release_url & format_w_official_vcs_name filter functions (PR#1161 <https://github.com/python-semantic-release/python-semantic-release/pull/1161>, f853cf0 <https://github.com/python-semantic-release/python-semantic-release/commit/f853cf059b3323d7888b06fde09142184e7964e8>)

  🪲 Bug Fixes

    •   Refactor parsing compatibility function to support older custom parsers (PR#1165 <https://github.com/python-semantic-release/python-semantic-release/pull/1165>, cf340c5 <https://github.com/python-semantic-release/python-semantic-release/commit/cf340c5256dea58aedad71a6bdf50b17eee53d2f>)

    •   changelog: Fix parsing compatibility w/ custom parsers, closes #1162 <https://github.com/python-semantic-release/python-semantic-release/issues/1162> (PR#1165 <https://github.com/python-semantic-release/python-semantic-release/pull/1165>, cf340c5 <https://github.com/python-semantic-release/python-semantic-release/commit/cf340c5256dea58aedad71a6bdf50b17eee53d2f>)

    •   changelog-templates: Adjust default templates to avoid empty version sections (PR#1164 <https://github.com/python-semantic-release/python-semantic-release/pull/1164>, 463e43b <https://github.com/python-semantic-release/python-semantic-release/commit/463e43b897ee80dfaf7ce9d88d22ea8e652bcf55>)

    •   parser-angular: Adjust parser to prevent empty message extractions (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   parser-emoji: Adjust parser to prevent empty message extractions (PR#1166 <https://github.com/python-semantic-release/python-semantic-release/pull/1166>, 834ce32 <https://github.com/python-semantic-release/python-semantic-release/commit/834ce323007c58229abf115ef2016a348de9ee66>)

    •   version: Fix parsing compatibility w/ custom parsers, closes #1162 <https://github.com/python-semantic-release/python-semantic-release/issues/1162> (PR#1165 <https://github.com/python-semantic-release/python-semantic-release/pull/1165>, cf340c5 <https://github.com/python-semantic-release/python-semantic-release/commit/cf340c5256dea58aedad71a6bdf50b17eee53d2f>)

  📖 Documentation

    •   changelog: Add formatted changelog into hosted documentation (PR#1155 <https://github.com/python-semantic-release/python-semantic-release/pull/1155>, 2f18a6d <https://github.com/python-semantic-release/python-semantic-release/commit/2f18a6debfa6ef3afcc5611a3e09262998f2d4bf>)

    •   changelog-templates: Add description for new create_pypi_url filter function (PR#1160 <https://github.com/python-semantic-release/python-semantic-release/pull/1160>, 45d49c3 <https://github.com/python-semantic-release/python-semantic-release/commit/45d49c3da75a7f08c86fc9bab5d232a9b37d9e72>)

    •   changelog-templates: Add details about license specification in the release notes (PR#1167 <https://github.com/python-semantic-release/python-semantic-release/pull/1167>, 41172c1 <https://github.com/python-semantic-release/python-semantic-release/commit/41172c1272a402e94e3c68571d013cbdcb5b9023>)

    •   changelog-templates: Define create_release_url & format_w_official_vcs_name filters (PR#1161 <https://github.com/python-semantic-release/python-semantic-release/pull/1161>, f853cf0 <https://github.com/python-semantic-release/python-semantic-release/commit/f853cf059b3323d7888b06fde09142184e7964e8>)

    •   changelog-templates: Document special separate sections of commit descriptions (ebb4c67 <https://github.com/python-semantic-release/python-semantic-release/commit/ebb4c67d46b86fdf79e32edf744a2ec2b09d6a93>)

    •   commit-parsing: Document new release notice footer detection feature of built-in parsers (cd14e92 <https://github.com/python-semantic-release/python-semantic-release/commit/cd14e9209d4e54f0876e737d1f802dded294a48c>)

  v9.17.0 (2025-01-26)

  ✨ Features

    •   changelog: Add sort_numerically filter function to template environment (PR#1146 <https://github.com/python-semantic-release/python-semantic-release/pull/1146>, 7792388 <https://github.com/python-semantic-release/python-semantic-release/commit/77923885c585171e8888aacde989837ecbabf3fc>)

    •   changelog: Parse squashed commits individually (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   config: Extend support of remote urls aliased using git insteadOf configurations, closes #1150 <https://github.com/python-semantic-release/python-semantic-release/issues/1150> (PR#1151 <https://github.com/python-semantic-release/python-semantic-release/pull/1151>, 4045037 <https://github.com/python-semantic-release/python-semantic-release/commit/40450375c7951dafddb09bef8001db7180d95f3a>)

    •   parsers: Parse squashed commits individually (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   parser-angular: Apply PR/MR numbers to all parsed commits from a squash merge (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   parser-angular: Upgrade angular parser to parse squashed commits individually, closes #1085 <https://github.com/python-semantic-release/python-semantic-release/issues/1085> (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   parser-emoji: Add functionality to interpret scopes from gitmoji commit messages (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   parser-emoji: Upgrade emoji parser to parse squashed commits individually (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   version: Parse squashed commits individually (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

  🪲 Bug Fixes

    •   github-action: Disable writing python bytecode in action execution (PR#1152 <https://github.com/python-semantic-release/python-semantic-release/pull/1152>, 315ae21 <https://github.com/python-semantic-release/python-semantic-release/commit/315ae2176e211b00b13374560d81e127a3065d1a>)

  ⚡ Performance Improvements

    •   logging: Remove irrelevant debug logging statements (PR#1147 <https://github.com/python-semantic-release/python-semantic-release/pull/1147>, f1ef4ec <https://github.com/python-semantic-release/python-semantic-release/commit/f1ef4ecf5f22684a870b958f87d1ca2650e612db>)

  📖 Documentation

    •   changelog-templates: Add description for new sort_numerically filter function (PR#1146 <https://github.com/python-semantic-release/python-semantic-release/pull/1146>, 7792388 <https://github.com/python-semantic-release/python-semantic-release/commit/77923885c585171e8888aacde989837ecbabf3fc>)

    •   commit-parsing: Add description for squash commit evaluation option of default parsers (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

    •   configuration: Update the commit_parser_options setting description (PR#1112 <https://github.com/python-semantic-release/python-semantic-release/pull/1112>, cf785ca <https://github.com/python-semantic-release/python-semantic-release/commit/cf785ca79a49eb4ee95c148e0ae6a19e230e915c>)

  v9.16.1 (2025-01-12)

  🪲 Bug Fixes

    •   parser-custom: Handle relative parent directory paths to module file better (PR#1142 <https://github.com/python-semantic-release/python-semantic-release/pull/1142>, c4056fc <https://github.com/python-semantic-release/python-semantic-release/commit/c4056fc2e1fb3bddb78728793716ac6fb8522b1a>)

  📖 Documentation

    •   github-actions: Update PSR versions in github workflow examples (PR#1140 <https://github.com/python-semantic-release/python-semantic-release/pull/1140>, 9bdd626 <https://github.com/python-semantic-release/python-semantic-release/commit/9bdd626bf8f8359d35725cebe803931063260cac>)

  v9.16.0 (2025-01-12)

  ✨ Features

    •   config: Expand dynamic parser import to handle a filepath to module (PR#1135 <https://github.com/python-semantic-release/python-semantic-release/pull/1135>, 0418fd8 <https://github.com/python-semantic-release/python-semantic-release/commit/0418fd8d27aac14925aafa50912e751e3aeff2f7>)

  🪲 Bug Fixes

    •   changelog: Fixes PSR release commit exclusions for customized commit messages (PR#1139 <https://github.com/python-semantic-release/python-semantic-release/pull/1139>, f9a2078 <https://github.com/python-semantic-release/python-semantic-release/commit/f9a20787437d0f26074fe2121bf0a29576a96df0>)

    •   cmd-version: Fixes --print-tag result to match configured tag format (PR#1134 <https://github.com/python-semantic-release/python-semantic-release/pull/1134>, a990aa7 <https://github.com/python-semantic-release/python-semantic-release/commit/a990aa7ab0a9d52d295c04d54d20e9c9f2db2ca5>)

    •   cmd-version: Fixes tag format on default version when force bump for initial release, closes #1137 <https://github.com/python-semantic-release/python-semantic-release/issues/1137> (PR#1138 <https://github.com/python-semantic-release/python-semantic-release/pull/1138>, 007fd00 <https://github.com/python-semantic-release/python-semantic-release/commit/007fd00a3945ed211ece4baab0b79ad93dc018f5>)

    •   config-changelog: Validate changelog.exclude_commit_patterns on config load (PR#1139 <https://github.com/python-semantic-release/python-semantic-release/pull/1139>, f9a2078 <https://github.com/python-semantic-release/python-semantic-release/commit/f9a20787437d0f26074fe2121bf0a29576a96df0>)

  📖 Documentation

    •   commit-parsing: Add the new custom parser import spec description for direct path imports, closes #687 <https://github.com/python-semantic-release/python-semantic-release/issues/687> (PR#1135 <https://github.com/python-semantic-release/python-semantic-release/pull/1135>, 0418fd8 <https://github.com/python-semantic-release/python-semantic-release/commit/0418fd8d27aac14925aafa50912e751e3aeff2f7>)

    •   configuration: Adjust commit_parser option definition for direct path imports (PR#1135 <https://github.com/python-semantic-release/python-semantic-release/pull/1135>, 0418fd8 <https://github.com/python-semantic-release/python-semantic-release/commit/0418fd8d27aac14925aafa50912e751e3aeff2f7>)

  v9.15.2 (2024-12-16)

  🪲 Bug Fixes

    •   changelog: Ensures user rendered files are trimmed to end with a single newline (PR#1118 <https://github.com/python-semantic-release/python-semantic-release/pull/1118>, 6dfbbb0 <https://github.com/python-semantic-release/python-semantic-release/commit/6dfbbb0371aef6b125cbcbf89b80dc343ed97360>)

    •   cli: Add error message of how to gather full error output (PR#1116 <https://github.com/python-semantic-release/python-semantic-release/pull/1116>, ba85532 <https://github.com/python-semantic-release/python-semantic-release/commit/ba85532ddd6fcf1a2205f7ce0b88ea5be76cb621>)

    •   cmd-version: Enable maintenance prereleases (PR#864 <https://github.com/python-semantic-release/python-semantic-release/pull/864>, b88108e <https://github.com/python-semantic-release/python-semantic-release/commit/b88108e189e1894e36ae4fdf8ad8a382b5c8c90a>)

    •   cmd-version: Fix handling of multiple prerelease token variants & git flow merges (PR#1120 <https://github.com/python-semantic-release/python-semantic-release/pull/1120>, 8784b9a <https://github.com/python-semantic-release/python-semantic-release/commit/8784b9ad4bc59384f855b5af8f1b8fb294397595>)

    •   cmd-version: Fix version determination algorithm to capture commits across merged branches (PR#1120 <https://github.com/python-semantic-release/python-semantic-release/pull/1120>, 8784b9a <https://github.com/python-semantic-release/python-semantic-release/commit/8784b9ad4bc59384f855b5af8f1b8fb294397595>)

    •   cmd-version: Forces tag timestamp to be same time as release commit (PR#1117 <https://github.com/python-semantic-release/python-semantic-release/pull/1117>, 7898b11 <https://github.com/python-semantic-release/python-semantic-release/commit/7898b1185fc1ad10e96bf3f5e48d9473b45d2b51>)

    •   cmd-version: Handle multiple prerelease token variants properly, closes #789 <https://github.com/python-semantic-release/python-semantic-release/issues/789> (PR#1120 <https://github.com/python-semantic-release/python-semantic-release/pull/1120>, 8784b9a <https://github.com/python-semantic-release/python-semantic-release/commit/8784b9ad4bc59384f855b5af8f1b8fb294397595>)

    •   config: Ensure default config loads on network mounted windows environments, closes #1123 <https://github.com/python-semantic-release/python-semantic-release/issues/1123> (PR#1124 <https://github.com/python-semantic-release/python-semantic-release/pull/1124>, a64cbc9 <https://github.com/python-semantic-release/python-semantic-release/commit/a64cbc96c110e32f1ec5d1a7b61e950472491b87>)

    •   version: Remove some excessive log msgs from debug to silly level (PR#1120 <https://github.com/python-semantic-release/python-semantic-release/pull/1120>, 8784b9a <https://github.com/python-semantic-release/python-semantic-release/commit/8784b9ad4bc59384f855b5af8f1b8fb294397595>)

    •   version-bump: Increment based on current commit's history only, closes #861 <https://github.com/python-semantic-release/python-semantic-release/issues/861> (PR#864 <https://github.com/python-semantic-release/python-semantic-release/pull/864>, b88108e <https://github.com/python-semantic-release/python-semantic-release/commit/b88108e189e1894e36ae4fdf8ad8a382b5c8c90a>)

  ⚡ Performance Improvements

    •   cmd-version: Refactor version determination algorithm for accuracy & speed (PR#1120 <https://github.com/python-semantic-release/python-semantic-release/pull/1120>, 8784b9a <https://github.com/python-semantic-release/python-semantic-release/commit/8784b9ad4bc59384f855b5af8f1b8fb294397595>)

  v9.15.1 (2024-12-03)

  🪲 Bug Fixes

    •   changelog-md: Fix commit sort of breaking descriptions section (75b342e <https://github.com/python-semantic-release/python-semantic-release/commit/75b342e6259412cb82d8b7663e5ee4536d14f407>)

    •   parser-angular: Ensure issues are sorted by numeric value rather than text sorted (3858add <https://github.com/python-semantic-release/python-semantic-release/commit/3858add582fe758dc2ae967d0cd051d43418ecd0>)

    •   parser-emoji: Ensure issues are sorted by numeric value rather than text sorted (7b8d2d9 <https://github.com/python-semantic-release/python-semantic-release/commit/7b8d2d92e135ab46d1be477073ccccc8c576f121>)

  v9.15.0 (2024-12-02)

  ✨ Features

    •   changelog-md: Add a breaking changes section to default Markdown template, closes #244 <https://github.com/python-semantic-release/python-semantic-release/issues/244> (PR#1110 <https://github.com/python-semantic-release/python-semantic-release/pull/1110>, 4fde30e <https://github.com/python-semantic-release/python-semantic-release/commit/4fde30e0936ecd186e448f1caf18d9ba377c55ad>)

    •   changelog-md: Alphabetize breaking change descriptions in markdown changelog template (PR#1110 <https://github.com/python-semantic-release/python-semantic-release/pull/1110>, 4fde30e <https://github.com/python-semantic-release/python-semantic-release/commit/4fde30e0936ecd186e448f1caf18d9ba377c55ad>)

    •   changelog-md: Alphabetize commit summaries & scopes in markdown changelog template (PR#1111 <https://github.com/python-semantic-release/python-semantic-release/pull/1111>, 8327068 <https://github.com/python-semantic-release/python-semantic-release/commit/83270683fd02b626ed32179d94fa1e3c7175d113>)

    •   changelog-rst: Add a breaking changes section to default reStructuredText template, closes #244 <https://github.com/python-semantic-release/python-semantic-release/issues/244> (PR#1110 <https://github.com/python-semantic-release/python-semantic-release/pull/1110>, 4fde30e <https://github.com/python-semantic-release/python-semantic-release/commit/4fde30e0936ecd186e448f1caf18d9ba377c55ad>)

    •   changelog-rst: Alphabetize breaking change descriptions in ReStructuredText template (PR#1110 <https://github.com/python-semantic-release/python-semantic-release/pull/1110>, 4fde30e <https://github.com/python-semantic-release/python-semantic-release/commit/4fde30e0936ecd186e448f1caf18d9ba377c55ad>)

    •   changelog-rst: Alphabetize commit summaries & scopes in ReStructuredText template (PR#1111 <https://github.com/python-semantic-release/python-semantic-release/pull/1111>, 8327068 <https://github.com/python-semantic-release/python-semantic-release/commit/83270683fd02b626ed32179d94fa1e3c7175d113>)

    •   commit-parser: Enable parsers to flag commit to be ignored for changelog, closes #778 <https://github.com/python-semantic-release/python-semantic-release/issues/778> (PR#1108 <https://github.com/python-semantic-release/python-semantic-release/pull/1108>, 0cc668c <https://github.com/python-semantic-release/python-semantic-release/commit/0cc668c36490401dff26bb2c3141f6120a2c47d0>)

    •   default-changelog: Add a separate formatted breaking changes section, closes #244 <https://github.com/python-semantic-release/python-semantic-release/issues/244> (PR#1110 <https://github.com/python-semantic-release/python-semantic-release/pull/1110>, 4fde30e <https://github.com/python-semantic-release/python-semantic-release/commit/4fde30e0936ecd186e448f1caf18d9ba377c55ad>)

    •   default-changelog: Alphabetize commit summaries & scopes in change sections (PR#1111 <https://github.com/python-semantic-release/python-semantic-release/pull/1111>, 8327068 <https://github.com/python-semantic-release/python-semantic-release/commit/83270683fd02b626ed32179d94fa1e3c7175d113>)

    •   parsers: Add other_allowed_tags option for commit parser options (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   parsers: Enable parsers to identify linked issues on a commit (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   parser-angular: Automatically parse angular issue footers from commit messages (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   parser-custom: Enable custom parsers to identify linked issues on a commit (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   parser-emoji: Parse issue reference footers from commit messages (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   release-notes: Add tag comparison link to release notes when supported (PR#1107 <https://github.com/python-semantic-release/python-semantic-release/pull/1107>, 9073344 <https://github.com/python-semantic-release/python-semantic-release/commit/9073344164294360843ef5522e7e4c529985984d>)

  🪲 Bug Fixes

    •   cmd-version: Ensure release utilizes a timezone aware datetime (ca817ed <https://github.com/python-semantic-release/python-semantic-release/commit/ca817ed9024cf84b306a047675534cc36dc116b2>)

    •   default-changelog: Alphabetically sort commit descriptions in version type sections (bdaaf5a <https://github.com/python-semantic-release/python-semantic-release/commit/bdaaf5a460ca77edc40070ee799430122132dc45>)

    •   util: Prevent git footers from being collapsed during parse (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

  📖 Documentation

    •   api-parsers: Add option documentation to parser options (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   changelog-templates: Update examples using new commit.linked_issues attribute (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

    •   commit-parsing: Improve & expand commit parsing w/ parser descriptions (PR#1109 <https://github.com/python-semantic-release/python-semantic-release/pull/1109>, f90b8dc <https://github.com/python-semantic-release/python-semantic-release/commit/f90b8dc6ce9f112ef2c98539d155f9de24398301>)

  v9.14.0 (2024-11-11)

  ✨ Features

    •   changelog: Add md to rst conversion for markdown inline links (cb2af1f <https://github.com/python-semantic-release/python-semantic-release/commit/cb2af1f17cf6c8ae037c6cd8bb8b4d9c019bb47e>)

    •   changelog: Define first release w/o change descriptions for default MD template (fa89dec <https://github.com/python-semantic-release/python-semantic-release/commit/fa89dec239efbae7544b187f624a998fa9ecc309>)

    •   changelog: Define first release w/o change descriptions for default RST template (e30c94b <https://github.com/python-semantic-release/python-semantic-release/commit/e30c94bffe62b42e8dc6ed4fed6260e57b4d532b>)

    •   changelog: Prefix scopes on commit descriptions in default template (PR#1093 <https://github.com/python-semantic-release/python-semantic-release/pull/1093>, 560fd2c <https://github.com/python-semantic-release/python-semantic-release/commit/560fd2c0d58c97318377cb83af899a336d24cfcc>)

    •   changelog-md: Add markdown inline link format macro (c6d8211 <https://github.com/python-semantic-release/python-semantic-release/commit/c6d8211c859442df17cb41d2ff19fdb7a81cdb76>)

    •   changelog-md: Prefix scopes on commit descriptions in Markdown changelog template (PR#1093 <https://github.com/python-semantic-release/python-semantic-release/pull/1093>, 560fd2c <https://github.com/python-semantic-release/python-semantic-release/commit/560fd2c0d58c97318377cb83af899a336d24cfcc>)

    •   changelog-rst: Prefix scopes on commit descriptions in ReStructuredText template (PR#1093 <https://github.com/python-semantic-release/python-semantic-release/pull/1093>, 560fd2c <https://github.com/python-semantic-release/python-semantic-release/commit/560fd2c0d58c97318377cb83af899a336d24cfcc>)

    •   configuration: Add changelog.default_templates.mask_initial_release option (595a70b <https://github.com/python-semantic-release/python-semantic-release/commit/595a70bcbc8fea1f8ccf6c5069c41c35ec4efb8d>)

    •   context: Add mask_initial_release setting to changelog context (6f2ee39 <https://github.com/python-semantic-release/python-semantic-release/commit/6f2ee39414b3cf75c0b67dee4db0146bbc1041bb>)

    •   release-notes: Define first release w/o change descriptions in default template (83167a3 <https://github.com/python-semantic-release/python-semantic-release/commit/83167a3dcceb7db16b790e1b0efd5fc75fee8942>)

  🪲 Bug Fixes

    •   release-notes: Override default word-wrap to non-wrap for in default template (99ab99b <https://github.com/python-semantic-release/python-semantic-release/commit/99ab99bb0ba350ca1913a2bde9696f4242278972>)

  📖 Documentation

    •   changelog-templates: Document new mask_initial_release changelog context variable (f294957 <https://github.com/python-semantic-release/python-semantic-release/commit/f2949577dfb2dbf9c2ac952c1bbcc4ab84da080b>)

    •   configuration: Document new mask_initial_release option usage & effect (3cabcdc <https://github.com/python-semantic-release/python-semantic-release/commit/3cabcdcd9473e008604e74cc2d304595317e921d>)

    •   homepage: Fix reference to new ci workflow for test status badge (6760069 <https://github.com/python-semantic-release/python-semantic-release/commit/6760069e7489f50635beb5aedbbeb2cb82b7c584>)

  v9.13.0 (2024-11-10)

  ✨ Features

    •   changelog: Add PR/MR url linking to default Markdown changelog, closes #924 <https://github.com/python-semantic-release/python-semantic-release/issues/924>, #953 <https://github.com/python-semantic-release/python-semantic-release/issues/953> (cd8d131 <https://github.com/python-semantic-release/python-semantic-release/commit/cd8d1310a4000cc79b529fbbdc58933f4c6373c6>)

    •   changelog: Add PR/MR url linking to default reStructuredText template, closes #924 <https://github.com/python-semantic-release/python-semantic-release/issues/924>, #953 <https://github.com/python-semantic-release/python-semantic-release/issues/953> (5f018d6 <https://github.com/python-semantic-release/python-semantic-release/commit/5f018d630b4c625bdf6d329b27fd966eba75b017>)

    •   parsed-commit: Add linked merge requests list to the ParsedCommit object (9a91062 <https://github.com/python-semantic-release/python-semantic-release/commit/9a9106212d6c240e9d3358e139b4c4694eaf9c4b>)

    •   parser-angular: Automatically parse PR/MR numbers from subject lines in commits (2ac798f <https://github.com/python-semantic-release/python-semantic-release/commit/2ac798f92e0c13c1db668747f7e35a65b99ae7ce>)

    •   parser-emoji: Automatically parse PR/MR numbers from subject lines in commits (bca9909 <https://github.com/python-semantic-release/python-semantic-release/commit/bca9909c1b61fdb1f9ccf823fceb6951cd059820>)

    •   parser-scipy: Automatically parse PR/MR numbers from subject lines in commits (2b3f738 <https://github.com/python-semantic-release/python-semantic-release/commit/2b3f73801f5760bac29acd93db3ffb2bc790cda0>)

  🪲 Bug Fixes

    •   changelog-rst: Ignore unknown parsed commit types in default RST changelog (77609b1 <https://github.com/python-semantic-release/python-semantic-release/commit/77609b1917a00b106ce254e6f6d5edcd1feebba7>)

    •   parser-angular: Drop the breaking category but still maintain a major level bump (f1ffa54 <https://github.com/python-semantic-release/python-semantic-release/commit/f1ffa5411892de34cdc842fd55c460a24b6685c6>)

    •   parsers: Improve reliability of descriptions after reverse word-wrap (436374b <https://github.com/python-semantic-release/python-semantic-release/commit/436374b04128d1550467ae97ba90253f1d1b3878>)

  ⚡ Performance Improvements

    •   parser-angular: Simplify commit parsing type pre-calculation (a86a28c <https://github.com/python-semantic-release/python-semantic-release/commit/a86a28c5e26ed766cda71d26b9382c392e377c61>)

    •   parser-emoji: Increase speed of commit parsing (2c9c468 <https://github.com/python-semantic-release/python-semantic-release/commit/2c9c4685a66feb35cd78571cf05f76344dd6d66a>)

    •   parser-scipy: Increase speed & decrease complexity of commit parsing (2b661ed <https://github.com/python-semantic-release/python-semantic-release/commit/2b661ed122a6f0357a6b92233ac1351c54c7794e>)

  📖 Documentation

    •   changelog-templates: Add linked_merge_request field to examples (d4376bc <https://github.com/python-semantic-release/python-semantic-release/commit/d4376bc2ae4d3708d501d91211ec3ee3a923e9b5>)

    •   changelog-templates: Fix api class reference links (7a5bdf2 <https://github.com/python-semantic-release/python-semantic-release/commit/7a5bdf29b3df0f9a1346ea5301d2a7fee953667b>)

    •   commit-parsing: Add linked_merge_request field to Parsed Commit definition (ca61889 <https://github.com/python-semantic-release/python-semantic-release/commit/ca61889d4ac73e9864fbf637fb87ab2d5bc053ea>)

  v9.12.2 (2024-11-07)

  🪲 Bug Fixes

    •   bitbucket: Fix pull_request_url filter to ignore an PR prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   cli: Gracefully capture all exceptions unless in very verbose debug mode (PR#1088 <https://github.com/python-semantic-release/python-semantic-release/pull/1088>, 13ca44f <https://github.com/python-semantic-release/python-semantic-release/commit/13ca44f4434098331f70e6937684679cf1b4106a>)

    •   gitea: Fix issue_url filter to ignore an issue prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   gitea: Fix pull_request_url filter to ignore an PR prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   github: Fix issue_url filter to ignore an issue prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   github: Fix pull_request_url filter to ignore an PR prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   gitlab: Fix issue_url filter to ignore an issue prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   gitlab: Fix merge_request_url filter to ignore an PR prefix gracefully (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

    •   hvcs: Add flexibility to issue & MR/PR url jinja filters (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

  📖 Documentation

    •   changelog-templates: Update descriptions of issue & MR/PR url jinja filters (PR#1089 <https://github.com/python-semantic-release/python-semantic-release/pull/1089>, 275ec88 <https://github.com/python-semantic-release/python-semantic-release/commit/275ec88e6d1637c47065bb752a60017ceba9876c>)

  v9.12.1 (2024-11-06)

  🪲 Bug Fixes

    •   changelog: Fix raw-inline pattern replacement in convert_md_to_rst filter (2dc70a6 <https://github.com/python-semantic-release/python-semantic-release/commit/2dc70a6106776106b0fba474b0029071317d639f>)

    •   cmd-version: Fix --as-prerelease when no commit change from last full release (PR#1076 <https://github.com/python-semantic-release/python-semantic-release/pull/1076>, 3b7b772 <https://github.com/python-semantic-release/python-semantic-release/commit/3b7b77246100cedd8cc8f289395f7641187ffdec>)

    •   release-notes: Add context variable shorthand ctx like docs claim & changelog has (d618d83 <https://github.com/python-semantic-release/python-semantic-release/commit/d618d83360c4409fc149f70b97c5fe338fa89968>)

  📖 Documentation

    •   contributing: Update local testing instructions (74f03d4 <https://github.com/python-semantic-release/python-semantic-release/commit/74f03d44684b7b2d84f9f5e471425b02f8bf91c3>)

  v9.12.0 (2024-10-18)

  ✨ Features

    •   changelog: Add autofit_text_width filter to template environment (PR#1062 <https://github.com/python-semantic-release/python-semantic-release/pull/1062>, 83e4b86 <https://github.com/python-semantic-release/python-semantic-release/commit/83e4b86abd4754c2f95ec2e674f04deb74b9a1e6>)

  🪲 Bug Fixes

    •   changelog: Ignore commit exclusion when a commit causes a version bump (e8f886e <https://github.com/python-semantic-release/python-semantic-release/commit/e8f886ef2abe8ceaea0a24a0112b92a167abd6a9>)

    •   parser-angular: Change Fixes commit type heading to Bug Fixes (PR#1064 <https://github.com/python-semantic-release/python-semantic-release/pull/1064>, 09e3a4d <https://github.com/python-semantic-release/python-semantic-release/commit/09e3a4da6237740de8e9932d742b18d990e9d079>)

    •   parser-emoji: Enable the default bump level option (bc27995 <https://github.com/python-semantic-release/python-semantic-release/commit/bc27995255a96b9d6cc743186e7c35098822a7f6>)

  📖 Documentation

    •   changelog-templates: Add definition & usage of autofit_text_width template filter (PR#1062 <https://github.com/python-semantic-release/python-semantic-release/pull/1062>, 83e4b86 <https://github.com/python-semantic-release/python-semantic-release/commit/83e4b86abd4754c2f95ec2e674f04deb74b9a1e6>)

    •   commit-parsers: Add deprecation message for the tag parser (af94540 <https://github.com/python-semantic-release/python-semantic-release/commit/af94540f2b1c63bf8a4dc977d5d0f66176962b64>)

    •   configuration: Add deprecation message for the tag parser (a83b7e4 <https://github.com/python-semantic-release/python-semantic-release/commit/a83b7e43e4eaa99790969a6c85f44e01cde80d0a>)

  v9.11.1 (2024-10-15)

  🪲 Bug Fixes

    •   changelog: Prevent custom template errors when components are in hidden folders (PR#1060 <https://github.com/python-semantic-release/python-semantic-release/pull/1060>, a7614b0 <https://github.com/python-semantic-release/python-semantic-release/commit/a7614b0db8ce791e4252209e66f42b5b5275dffd>)

  v9.11.0 (2024-10-12)

  ✨ Features

    •   changelog: Add convert_md_to_rst filter to changelog environment (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   changelog: Add default changelog in re-structured text format, closes #399 <https://github.com/python-semantic-release/python-semantic-release/issues/399> (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   changelog: Add default changelog template in reStructuredText format (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   config: Enable default changelog.insertion_flag based on output format (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   config: Enable target changelog filename to trigger RST output format, closes #399 <https://github.com/python-semantic-release/python-semantic-release/issues/399> (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

  🪲 Bug Fixes

    •   changelog: Correct spacing for default markdown template during updates (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

  📖 Documentation

    •   changelog: Clarify the convert_md_to_rst filter added to the template environment (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   changelog: Increase detail about configuration options of default changelog creation (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   configuration: Update changelog_file with deprecation notice of setting relocation (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   configuration: Update output_format description for reStructuredText support (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

    •   configuration: Update details of insertion_flag's dynamic defaults with rst (PR#1055 <https://github.com/python-semantic-release/python-semantic-release/pull/1055>, c2e8831 <https://github.com/python-semantic-release/python-semantic-release/commit/c2e883104d3c11e56f229638e988d8b571f86e34>)

  v9.10.1 (2024-10-10)

  🪲 Bug Fixes

    •   config: Handle branch match regex errors gracefully (PR#1054 <https://github.com/python-semantic-release/python-semantic-release/pull/1054>, 4d12251 <https://github.com/python-semantic-release/python-semantic-release/commit/4d12251c678a38de6b71cac5b9c1390eb9dd8ad6>)

  v9.10.0 (2024-10-08)

  ✨ Features

    •   changelog: Add changelog_insertion_flag to changelog template context (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Add changelog_mode to changelog template context (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Add prev_changelog_file to changelog template context (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Add read_file function to changelog template context (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Add shorthand ctx variable to changelog template env (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Modify changelog template to support changelog updates, closes #858 <https://github.com/python-semantic-release/python-semantic-release/issues/858> (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   config: Add changelog.default_templates.output_format config option (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   config: Add changelog.insertion_flag as configuration option (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   config: Add changelog.mode as configuration option (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   github-actions: Add an action build directive to toggle the --skip-build option (PR#1044 <https://github.com/python-semantic-release/python-semantic-release/pull/1044>, 26597e2 <https://github.com/python-semantic-release/python-semantic-release/commit/26597e24a80a37500264aa95a908ba366699099e>)

  🪲 Bug Fixes

    •   changelog: Adjust angular heading names for readability (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Ensure changelog templates can handle complex directory includes (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   changelog: Only render user templates when files exist (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   config: Prevent jinja from autoescaping markdown content by default (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

  📖 Documentation

    •   changelog-templates: Improve detail & describe new changelog.mode="update" (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   commands: Update definition of the version commands --skip-build option (PR#1044 <https://github.com/python-semantic-release/python-semantic-release/pull/1044>, 26597e2 <https://github.com/python-semantic-release/python-semantic-release/commit/26597e24a80a37500264aa95a908ba366699099e>)

    •   configuration: Add changelog.mode and changelog.insertion_flag config definitions (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   configuration: Define the new changelog.default_templates.output_format option (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   configuration: Mark version of configuration setting introduction (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   configuration: Standardize all true/false to lowercase ensuring toml-compatibility (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   configuration: Update changelog.environment.autoescape default to false to match code (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

    •   github-actions: Add description of the build input directive (PR#1044 <https://github.com/python-semantic-release/python-semantic-release/pull/1044>, 26597e2 <https://github.com/python-semantic-release/python-semantic-release/commit/26597e24a80a37500264aa95a908ba366699099e>)

    •   github-actions: Update primary example with workflow sha controlled pipeline (14f04df <https://github.com/python-semantic-release/python-semantic-release/commit/14f04dffc7366142faecebb162d4449501cbf1fd>)

    •   homepage: Update custom changelog reference (PR#1045 <https://github.com/python-semantic-release/python-semantic-release/pull/1045>, c18c245 <https://github.com/python-semantic-release/python-semantic-release/commit/c18c245df51a9778af09b9dc7a315e3f11cdcda0>)

  v9.9.0 (2024-09-28)

  ✨ Features

    •   github-actions: Add is_prerelease output to the version action (PR#1038 <https://github.com/python-semantic-release/python-semantic-release/pull/1038>, 6a5d35d <https://github.com/python-semantic-release/python-semantic-release/commit/6a5d35d0d9124d6a6ee7910711b4154b006b8773>)

  📖 Documentation

    •   automatic-releases: Drop extraneous github push configuration (PR#1011 <https://github.com/python-semantic-release/python-semantic-release/pull/1011>, 2135c68 <https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3>)

    •   github-actions: Add configuration & description of publish action (PR#1011 <https://github.com/python-semantic-release/python-semantic-release/pull/1011>, 2135c68 <https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3>)

    •   github-actions: Add description of new is_prerelease output for version action (PR#1038 <https://github.com/python-semantic-release/python-semantic-release/pull/1038>, 6a5d35d <https://github.com/python-semantic-release/python-semantic-release/commit/6a5d35d0d9124d6a6ee7910711b4154b006b8773>)

    •   github-actions: Clarify & consolidate GitHub Actions usage docs, closes #907 <https://github.com/python-semantic-release/python-semantic-release/issues/907> (PR#1011 <https://github.com/python-semantic-release/python-semantic-release/pull/1011>, 2135c68 <https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3>)

    •   github-actions: Expand descriptions & clarity of actions configs (PR#1011 <https://github.com/python-semantic-release/python-semantic-release/pull/1011>, 2135c68 <https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3>)

    •   github-actions: Revert removal of namespace prefix from examples (PR#1011 <https://github.com/python-semantic-release/python-semantic-release/pull/1011>, 2135c68 <https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3>)

    •   homepage: Remove link to old github config & update token scope config (PR#1011 <https://github.com/python-semantic-release/python-semantic-release/pull/1011>, 2135c68 <https://github.com/python-semantic-release/python-semantic-release/commit/2135c68ccbdad94378809902b52fcad546efd5b3>)

  v9.8.9 (2024-09-27)

  🪲 Bug Fixes

    •   version-cmd: Ensure version_variables do not match partial variable names (PR#1028 <https://github.com/python-semantic-release/python-semantic-release/pull/1028>, 156915c <https://github.com/python-semantic-release/python-semantic-release/commit/156915c7d759098f65cf9de7c4e980b40b38d5f1>)

    •   version-cmd: Improve version_variables flexibility w/ quotes (ie. json, yaml, etc) (PR#1028 <https://github.com/python-semantic-release/python-semantic-release/pull/1028>, 156915c <https://github.com/python-semantic-release/python-semantic-release/commit/156915c7d759098f65cf9de7c4e980b40b38d5f1>)

    •   version-cmd: Increase version_variable flexibility with quotations (ie. json, yaml, etc), closes #601 <https://github.com/python-semantic-release/python-semantic-release/issues/601>, #706 <https://github.com/python-semantic-release/python-semantic-release/issues/706>, #962 <https://github.com/python-semantic-release/python-semantic-release/issues/962>, #1026 <https://github.com/python-semantic-release/python-semantic-release/issues/1026> (PR#1028 <https://github.com/python-semantic-release/python-semantic-release/pull/1028>, 156915c <https://github.com/python-semantic-release/python-semantic-release/commit/156915c7d759098f65cf9de7c4e980b40b38d5f1>)

  📖 Documentation

    •   Update docstrings to resolve sphinx failures, closes #1029 <https://github.com/python-semantic-release/python-semantic-release/issues/1029> (PR#1030 <https://github.com/python-semantic-release/python-semantic-release/pull/1030>, d84efc7 <https://github.com/python-semantic-release/python-semantic-release/commit/d84efc7719a8679e6979d513d1c8c60904af7384>)

    •   configuration: Add clarity to version_variables usage & limitations (PR#1028 <https://github.com/python-semantic-release/python-semantic-release/pull/1028>, 156915c <https://github.com/python-semantic-release/python-semantic-release/commit/156915c7d759098f65cf9de7c4e980b40b38d5f1>)

    •   homepage: Re-structure homepage to be separate from project readme (PR#1032 <https://github.com/python-semantic-release/python-semantic-release/pull/1032>, 2307ed2 <https://github.com/python-semantic-release/python-semantic-release/commit/2307ed29d9990bf1b6821403a4b8db3365ef8bb5>)

    •   README: Simplify README to point at official docs (PR#1032 <https://github.com/python-semantic-release/python-semantic-release/pull/1032>, 2307ed2 <https://github.com/python-semantic-release/python-semantic-release/commit/2307ed29d9990bf1b6821403a4b8db3365ef8bb5>)

  v9.8.8 (2024-09-01)

  🪲 Bug Fixes

    •   config: Fix path traversal detection for windows compatibility, closes #994 <https://github.com/python-semantic-release/python-semantic-release/issues/994> (PR#1014 <https://github.com/python-semantic-release/python-semantic-release/pull/1014>, 16e6daa <https://github.com/python-semantic-release/python-semantic-release/commit/16e6daaf851ce1eabf5fbd5aa9fe310a8b0f22b3>)

  📖 Documentation

    •   configuration: Update build_command env table for windows to use all capital vars (0e8451c <https://github.com/python-semantic-release/python-semantic-release/commit/0e8451cf9003c6a3bdcae6878039d7d9a23d6d5b>)

    •   github-actions: Update version in examples to latest version (3c894ea <https://github.com/python-semantic-release/python-semantic-release/commit/3c894ea8a555d20b454ebf34785e772959bbb4fe>)

  v9.8.7 (2024-08-20)

  🪲 Bug Fixes

    •   Provide context.history global in release notes templates (PR#1005 <https://github.com/python-semantic-release/python-semantic-release/pull/1005>, 5bd91b4 <https://github.com/python-semantic-release/python-semantic-release/commit/5bd91b4d7ac33ddf10446f3e66d7d11e0724aeb2>)

    •   release-notes: Fix noop-changelog to print raw release notes (PR#1005 <https://github.com/python-semantic-release/python-semantic-release/pull/1005>, 5bd91b4 <https://github.com/python-semantic-release/python-semantic-release/commit/5bd91b4d7ac33ddf10446f3e66d7d11e0724aeb2>)

    •   release-notes: Provide context.history global in release note templates, closes #984 <https://github.com/python-semantic-release/python-semantic-release/issues/984> (PR#1005 <https://github.com/python-semantic-release/python-semantic-release/pull/1005>, 5bd91b4 <https://github.com/python-semantic-release/python-semantic-release/commit/5bd91b4d7ac33ddf10446f3e66d7d11e0724aeb2>)

  📖 Documentation

    •   Use pinned version for GHA examples (PR#1004 <https://github.com/python-semantic-release/python-semantic-release/pull/1004>, 5fdf761 <https://github.com/python-semantic-release/python-semantic-release/commit/5fdf7614c036a77ffb051cd30f57d0a63c062c0d>)

    •   changelog: Clarify description of the default changelog generation process (399fa65 <https://github.com/python-semantic-release/python-semantic-release/commit/399fa6521d5c6c4397b1d6e9b13ea7945ae92543>)

    •   configuration: Clarify changelog_file vs template_dir option usage, closes #983 <https://github.com/python-semantic-release/python-semantic-release/issues/983> (a7199c8 <https://github.com/python-semantic-release/python-semantic-release/commit/a7199c8cd6041a9de017694302e49b139bbcb034>)

    •   configuration: Fix build_command_env table rendering (PR#996 <https://github.com/python-semantic-release/python-semantic-release/pull/996>, a5eff0b <https://github.com/python-semantic-release/python-semantic-release/commit/a5eff0bfe41d2fd5d9ead152a132010b718b7772>)

    •   github-actions: Adjust formatting & version warning in code snippets (PR#1004 <https://github.com/python-semantic-release/python-semantic-release/pull/1004>, 5fdf761 <https://github.com/python-semantic-release/python-semantic-release/commit/5fdf7614c036a77ffb051cd30f57d0a63c062c0d>)

    •   github-actions: Use pinned version for GHA examples, closes #1003 <https://github.com/python-semantic-release/python-semantic-release/issues/1003> (PR#1004 <https://github.com/python-semantic-release/python-semantic-release/pull/1004>, 5fdf761 <https://github.com/python-semantic-release/python-semantic-release/commit/5fdf7614c036a77ffb051cd30f57d0a63c062c0d>)

  v9.8.6 (2024-07-20)

  🪲 Bug Fixes

    •   version-cmd: Resolve build command execution in powershell (PR#980 <https://github.com/python-semantic-release/python-semantic-release/pull/980>, 32c8e70 <https://github.com/python-semantic-release/python-semantic-release/commit/32c8e70915634d8e560b470c3cf38c27cebd7ae0>)

  📖 Documentation

    •   configuration: Correct GHA parameter name for commit email (PR#981 <https://github.com/python-semantic-release/python-semantic-release/pull/981>, ce9ffdb <https://github.com/python-semantic-release/python-semantic-release/commit/ce9ffdb82c2358184b288fa18e83a4075f333277>)

  v9.8.5 (2024-07-06)

  🪲 Bug Fixes

    •   Enable --print-last-released* when in detached head or non-release branch (PR#926 <https://github.com/python-semantic-release/python-semantic-release/pull/926>, 782c0a6 <https://github.com/python-semantic-release/python-semantic-release/commit/782c0a6109fb49e168c37f279928c0a4959f8ac6>)

    •   changelog: Resolve commit ordering issue when dates are similar (PR#972 <https://github.com/python-semantic-release/python-semantic-release/pull/972>, bfda159 <https://github.com/python-semantic-release/python-semantic-release/commit/bfda1593af59e9e728c584dd88d7927fc52c879f>)

    •   version-cmd: Drop branch restriction for --print-last-released* opts, closes #900 <https://github.com/python-semantic-release/python-semantic-release/issues/900> (PR#926 <https://github.com/python-semantic-release/python-semantic-release/pull/926>, 782c0a6 <https://github.com/python-semantic-release/python-semantic-release/commit/782c0a6109fb49e168c37f279928c0a4959f8ac6>)

  ⚡ Performance Improvements

    •   Improve git history processing for changelog generation (PR#972 <https://github.com/python-semantic-release/python-semantic-release/pull/972>, bfda159 <https://github.com/python-semantic-release/python-semantic-release/commit/bfda1593af59e9e728c584dd88d7927fc52c879f>)

    •   changelog: Improve git history parser changelog generation (PR#972 <https://github.com/python-semantic-release/python-semantic-release/pull/972>, bfda159 <https://github.com/python-semantic-release/python-semantic-release/commit/bfda1593af59e9e728c584dd88d7927fc52c879f>)

  v9.8.4 (2024-07-04)

  🪲 Bug Fixes

    •   changelog-cmd: Remove usage strings when error occurred, closes #810 <https://github.com/python-semantic-release/python-semantic-release/issues/810> (348a51d <https://github.com/python-semantic-release/python-semantic-release/commit/348a51db8a837d951966aff3789aa0c93d473829>)

    •   changelog-cmd: Render default changelog when user template directory exist but is empty (bded8de <https://github.com/python-semantic-release/python-semantic-release/commit/bded8deae6c92f6dde9774802d9f3716a5cb5705>)

    •   config: Prevent path traversal manipulation of target changelog location (43e35d0 <https://github.com/python-semantic-release/python-semantic-release/commit/43e35d0972e8a29239d18ed079d1e2013342fcbd>)

    •   config: Prevent path traversal manipulation of target changelog location (3eb3dba <https://github.com/python-semantic-release/python-semantic-release/commit/3eb3dbafec4223ee463b90e927e551639c69426b>)

    •   publish-cmd: Prevent error when provided tag does not exist locally (16afbbb <https://github.com/python-semantic-release/python-semantic-release/commit/16afbbb8fbc3a97243e96d7573f4ad2eba09aab9>)

    •   publish-cmd: Remove usage strings when error occurred, closes #810 <https://github.com/python-semantic-release/python-semantic-release/issues/810> (afbb187 <https://github.com/python-semantic-release/python-semantic-release/commit/afbb187d6d405fdf6765082e2a1cecdcd7d357df>)

    •   version-cmd: Remove usage strings when error occurred, closes #810 <https://github.com/python-semantic-release/python-semantic-release/issues/810> (a7c17c7 <https://github.com/python-semantic-release/python-semantic-release/commit/a7c17c73fd7becb6d0e042e45ff6765605187e2a>)

  v9.8.3 (2024-06-18)

  🪲 Bug Fixes

    •   parser: Strip DOS carriage-returns in commits, closes #955 <https://github.com/python-semantic-release/python-semantic-release/issues/955> (PR#956 <https://github.com/python-semantic-release/python-semantic-release/pull/956>, 0b005df <https://github.com/python-semantic-release/python-semantic-release/commit/0b005df0a8c7730ee0c71453c9992d7b5d2400a4>)

  v9.8.2 (2024-06-17)

  🪲 Bug Fixes

    •   templates: Suppress extra newlines in default changelog (PR#954 <https://github.com/python-semantic-release/python-semantic-release/pull/954>, 7b0079b <https://github.com/python-semantic-release/python-semantic-release/commit/7b0079bf3e17c0f476bff520b77a571aeac469d0>)

  v9.8.1 (2024-06-05)

  🪲 Bug Fixes

    •   Improve build cmd env on windows (PR#942 <https://github.com/python-semantic-release/python-semantic-release/pull/942>, d911fae <https://github.com/python-semantic-release/python-semantic-release/commit/d911fae993d41a8cb1497fa8b2a7e823576e0f22>)

    •   version-cmd: Pass windows specific env vars to build cmd when on windows (PR#942 <https://github.com/python-semantic-release/python-semantic-release/pull/942>, d911fae <https://github.com/python-semantic-release/python-semantic-release/commit/d911fae993d41a8cb1497fa8b2a7e823576e0f22>)

  📖 Documentation

    •   configuration: Define windows specific env vars for build cmd (PR#942 <https://github.com/python-semantic-release/python-semantic-release/pull/942>, d911fae <https://github.com/python-semantic-release/python-semantic-release/commit/d911fae993d41a8cb1497fa8b2a7e823576e0f22>)

  v9.8.0 (2024-05-27)

  ✨ Features

    •   Extend gitlab to edit a previous release if exists (PR#934 <https://github.com/python-semantic-release/python-semantic-release/pull/934>, 23e02b9 <https://github.com/python-semantic-release/python-semantic-release/commit/23e02b96dfb2a58f6b4ecf7b7812e4c1bc50573d>)

    •   gha: Configure ssh signed tags in GitHub Action, closes #936 <https://github.com/python-semantic-release/python-semantic-release/issues/936> (PR#937 <https://github.com/python-semantic-release/python-semantic-release/pull/937>, dfb76b9 <https://github.com/python-semantic-release/python-semantic-release/commit/dfb76b94b859a7f3fa3ad778eec7a86de2874d68>)

    •   hvcs-gitlab: Enable gitlab to edit a previous release if found (PR#934 <https://github.com/python-semantic-release/python-semantic-release/pull/934>, 23e02b9 <https://github.com/python-semantic-release/python-semantic-release/commit/23e02b96dfb2a58f6b4ecf7b7812e4c1bc50573d>)

    •   version-cmd: Add toggle of --no-verify option to git commit (PR#927 <https://github.com/python-semantic-release/python-semantic-release/pull/927>, 1de6f78 <https://github.com/python-semantic-release/python-semantic-release/commit/1de6f7834c6d37a74bc53f91609d40793556b52d>)

  🪲 Bug Fixes

    •   gitlab: Adjust release name to mirror other hvcs release names (PR#934 <https://github.com/python-semantic-release/python-semantic-release/pull/934>, 23e02b9 <https://github.com/python-semantic-release/python-semantic-release/commit/23e02b96dfb2a58f6b4ecf7b7812e4c1bc50573d>)

    •   hvcs-gitlab: Add tag message to release creation (PR#934 <https://github.com/python-semantic-release/python-semantic-release/pull/934>, 23e02b9 <https://github.com/python-semantic-release/python-semantic-release/commit/23e02b96dfb2a58f6b4ecf7b7812e4c1bc50573d>)

  📖 Documentation

    •   configuration: Add no_git_verify description to the configuration page (PR#927 <https://github.com/python-semantic-release/python-semantic-release/pull/927>, 1de6f78 <https://github.com/python-semantic-release/python-semantic-release/commit/1de6f7834c6d37a74bc53f91609d40793556b52d>)

    •   migration-v8: Update version references in migration instructions (PR#938 <https://github.com/python-semantic-release/python-semantic-release/pull/938>, d6ba16a <https://github.com/python-semantic-release/python-semantic-release/commit/d6ba16aa8e01bae1a022a9b06cd0b9162c51c345>)

  v9.7.3 (2024-05-15)

  🪲 Bug Fixes

    •   Enabled prerelease-token parameter in github action (PR#929 <https://github.com/python-semantic-release/python-semantic-release/pull/929>, 1bb26b0 <https://github.com/python-semantic-release/python-semantic-release/commit/1bb26b0762d94efd97c06a3f1b6b10fb76901f6d>)

  v9.7.2 (2024-05-13)

  🪲 Bug Fixes

    •   Enable user configuration of build_command env vars (PR#925 <https://github.com/python-semantic-release/python-semantic-release/pull/925>, 6b5b271 <https://github.com/python-semantic-release/python-semantic-release/commit/6b5b271453874b982fbf2827ec1f6be6db1c2cc7>)

    •   version: Enable user config of build_command env variables, closes #922 <https://github.com/python-semantic-release/python-semantic-release/issues/922> (PR#925 <https://github.com/python-semantic-release/python-semantic-release/pull/925>, 6b5b271 <https://github.com/python-semantic-release/python-semantic-release/commit/6b5b271453874b982fbf2827ec1f6be6db1c2cc7>)

  📖 Documentation

    •   configuration: Clarify TOC & alphabetize configuration descriptions (19add16 <https://github.com/python-semantic-release/python-semantic-release/commit/19add16dcfdfdb812efafe2d492a933d0856df1d>)

    •   configuration: Clarify TOC & standardize heading links (3a41995 <https://github.com/python-semantic-release/python-semantic-release/commit/3a4199542d0ea4dbf88fa35e11bec41d0c27dd17>)

    •   configuration: Document build_command_env configuration option (PR#925 <https://github.com/python-semantic-release/python-semantic-release/pull/925>, 6b5b271 <https://github.com/python-semantic-release/python-semantic-release/commit/6b5b271453874b982fbf2827ec1f6be6db1c2cc7>)

    •   CONTRIBUTING: Update build command definition for developers (PR#921 <https://github.com/python-semantic-release/python-semantic-release/pull/921>, b573c4d <https://github.com/python-semantic-release/python-semantic-release/commit/b573c4d4a2c212be9bdee918501bb5e046c6a806>)

  v9.7.1 (2024-05-07)

  🪲 Bug Fixes

    •   gha: Fix missing git_committer_* definition in action, closes #918 <https://github.com/python-semantic-release/python-semantic-release/issues/918> (PR#919 <https://github.com/python-semantic-release/python-semantic-release/pull/919>, ccef9d8 <https://github.com/python-semantic-release/python-semantic-release/commit/ccef9d8521be12c0640369b3c3a80b81a7832662>)

  v9.7.0 (2024-05-06)

  ✨ Features

    •   version-cmd: Pass NEW_VERSION & useful env vars to build command (ee6b246 <https://github.com/python-semantic-release/python-semantic-release/commit/ee6b246df3bb211ab49c8bce075a4c3f6a68ed77>)

  🪲 Bug Fixes

    •   gha: Add missing tag option to GitHub Action definition, closes #906 <https://github.com/python-semantic-release/python-semantic-release/issues/906> (PR#908 <https://github.com/python-semantic-release/python-semantic-release/pull/908>, 6b24288 <https://github.com/python-semantic-release/python-semantic-release/commit/6b24288a96302cd6982260e46fad128ec4940da9>)

    •   gha: Correct use of prerelease option for GitHub Action (PR#914 <https://github.com/python-semantic-release/python-semantic-release/pull/914>, 85e27b7 <https://github.com/python-semantic-release/python-semantic-release/commit/85e27b7f486e6b0e6cc9e85e101a97e676bc3d60>)

  📖 Documentation

    •   configuration: Add description of build command available env variables (c882dc6 <https://github.com/python-semantic-release/python-semantic-release/commit/c882dc62b860b2aeaa925c21d1524f4ae25ef567>)

    •   gha: Update GitHub Actions doc with all available options (PR#914 <https://github.com/python-semantic-release/python-semantic-release/pull/914>, 85e27b7 <https://github.com/python-semantic-release/python-semantic-release/commit/85e27b7f486e6b0e6cc9e85e101a97e676bc3d60>)

  ⚙️ Build System

    •   deps: Bump GitHub Action container to use python3.12, closes #801 <https://github.com/python-semantic-release/python-semantic-release/issues/801> (PR#914 <https://github.com/python-semantic-release/python-semantic-release/pull/914>, 85e27b7 <https://github.com/python-semantic-release/python-semantic-release/commit/85e27b7f486e6b0e6cc9e85e101a97e676bc3d60>)

  v9.6.0 (2024-04-29)

  ✨ Features

    •   Changelog filters are specialized per vcs type (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   changelog: Changelog filters are hvcs focused (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   changelog-context: Add flag to jinja env for which hvcs is available (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   changelog-gitea: Add issue url filter to changelog context (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   changelog-github: Add issue url filter to changelog context (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   version-cmd: Add --as-prerelease option to force the next version to be a prerelease, closes #639 <https://github.com/python-semantic-release/python-semantic-release/issues/639> (PR#647 <https://github.com/python-semantic-release/python-semantic-release/pull/647>, 2acb5ac <https://github.com/python-semantic-release/python-semantic-release/commit/2acb5ac35ae79d7ae25ca9a03fb5c6a4a68b3673>)

  🪲 Bug Fixes

    •   Correct version --prerelease use & enable --as-prerelease (PR#647 <https://github.com/python-semantic-release/python-semantic-release/pull/647>, 2acb5ac <https://github.com/python-semantic-release/python-semantic-release/commit/2acb5ac35ae79d7ae25ca9a03fb5c6a4a68b3673>)

    •   github: Correct changelog filter for pull request urls (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   parser-custom: Gracefully handle custom parser import errors (67f6038 <https://github.com/python-semantic-release/python-semantic-release/commit/67f60389e3f6e93443ea108c0e1b4d30126b8e06>)

    •   version-cmd: Correct --prerelease use, closes #639 <https://github.com/python-semantic-release/python-semantic-release/issues/639> (PR#647 <https://github.com/python-semantic-release/python-semantic-release/pull/647>, 2acb5ac <https://github.com/python-semantic-release/python-semantic-release/commit/2acb5ac35ae79d7ae25ca9a03fb5c6a4a68b3673>)

  📖 Documentation

    •   changelog-context: Explain new hvcs specific context filters (PR#890 <https://github.com/python-semantic-release/python-semantic-release/pull/890>, 76ed593 <https://github.com/python-semantic-release/python-semantic-release/commit/76ed593ea33c851005994f0d1a6a33cc890fb908>)

    •   commands: Update version command options definition about prereleases (PR#647 <https://github.com/python-semantic-release/python-semantic-release/pull/647>, 2acb5ac <https://github.com/python-semantic-release/python-semantic-release/commit/2acb5ac35ae79d7ae25ca9a03fb5c6a4a68b3673>)

  v9.5.0 (2024-04-23)

  ✨ Features

    •   Extend support to on-prem GitHub Enterprise Server (PR#896 <https://github.com/python-semantic-release/python-semantic-release/pull/896>, 4fcb737 <https://github.com/python-semantic-release/python-semantic-release/commit/4fcb737958d95d1a3be24db7427e137b46f5075f>)

    •   github: Extend support to on-prem GitHub Enterprise Server, closes #895 <https://github.com/python-semantic-release/python-semantic-release/issues/895> (PR#896 <https://github.com/python-semantic-release/python-semantic-release/pull/896>, 4fcb737 <https://github.com/python-semantic-release/python-semantic-release/commit/4fcb737958d95d1a3be24db7427e137b46f5075f>)

  v9.4.2 (2024-04-14)

  🪲 Bug Fixes

    •   bitbucket: Allow insecure http connections if configured (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

    •   bitbucket: Correct url parsing & prevent double url schemes (PR#676 <https://github.com/python-semantic-release/python-semantic-release/pull/676>, 5cfdb24 <https://github.com/python-semantic-release/python-semantic-release/commit/5cfdb248c003a2d2be5fe65fb61d41b0d4c45db5>)

    •   config: Add flag to allow insecure connections (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

    •   gitea: Allow insecure http connections if configured (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

    •   gitea: Correct url parsing & prevent double url schemes (PR#676 <https://github.com/python-semantic-release/python-semantic-release/pull/676>, 5cfdb24 <https://github.com/python-semantic-release/python-semantic-release/commit/5cfdb248c003a2d2be5fe65fb61d41b0d4c45db5>)

    •   github: Allow insecure http connections if configured (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

    •   github: Correct url parsing & prevent double url schemes (PR#676 <https://github.com/python-semantic-release/python-semantic-release/pull/676>, 5cfdb24 <https://github.com/python-semantic-release/python-semantic-release/commit/5cfdb248c003a2d2be5fe65fb61d41b0d4c45db5>)

    •   gitlab: Allow insecure http connections if configured (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

    •   gitlab: Correct url parsing & prevent double url schemes (PR#676 <https://github.com/python-semantic-release/python-semantic-release/pull/676>, 5cfdb24 <https://github.com/python-semantic-release/python-semantic-release/commit/5cfdb248c003a2d2be5fe65fb61d41b0d4c45db5>)

    •   hvcs: Allow insecure http connections if configured (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

    •   hvcs: Prevent double protocol scheme urls in changelogs (PR#676 <https://github.com/python-semantic-release/python-semantic-release/pull/676>, 5cfdb24 <https://github.com/python-semantic-release/python-semantic-release/commit/5cfdb248c003a2d2be5fe65fb61d41b0d4c45db5>)

    •   version-cmd: Handle HTTP exceptions more gracefully (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

  📖 Documentation

    •   configuration: Update remote settings section with missing values, closes #868 <https://github.com/python-semantic-release/python-semantic-release/issues/868> (PR#886 <https://github.com/python-semantic-release/python-semantic-release/pull/886>, db13438 <https://github.com/python-semantic-release/python-semantic-release/commit/db1343890f7e0644bc8457f995f2bd62087513d3>)

  ⚙️ Build System

    •   deps: Update rich requirement from ~=12.5 to ~=13.0, closes #888 <https://github.com/python-semantic-release/python-semantic-release/issues/888> (PR#877 <https://github.com/python-semantic-release/python-semantic-release/pull/877>, 4a22a8c <https://github.com/python-semantic-release/python-semantic-release/commit/4a22a8c1a69bcf7b1ddd6db56e6883c617a892b3>)

  v9.4.1 (2024-04-06)

  🪲 Bug Fixes

    •   gh-actions-output: Fixed trailing newline to match GITHUB_OUTPUT format (PR#885 <https://github.com/python-semantic-release/python-semantic-release/pull/885>, 2c7b6ec <https://github.com/python-semantic-release/python-semantic-release/commit/2c7b6ec85b6e3182463d7b695ee48e9669a25b3b>)

    •   gh-actions-output: Fixed trailing newline to match GITHUB_OUTPUT format, closes #884 <https://github.com/python-semantic-release/python-semantic-release/issues/884> (PR#885 <https://github.com/python-semantic-release/python-semantic-release/pull/885>, 2c7b6ec <https://github.com/python-semantic-release/python-semantic-release/commit/2c7b6ec85b6e3182463d7b695ee48e9669a25b3b>)

  v9.4.0 (2024-03-31)

  ✨ Features

    •   gitea: Derives gitea api domain from base domain when unspecified (PR#675 <https://github.com/python-semantic-release/python-semantic-release/pull/675>, 2ee3f8a <https://github.com/python-semantic-release/python-semantic-release/commit/2ee3f8a918d2e5ea9ab64df88f52e62a1f589c38>)

  v9.3.1 (2024-03-24)

  🪲 Bug Fixes

    •   algorithm: Handle merge-base errors gracefully, closes #724 <https://github.com/python-semantic-release/python-semantic-release/issues/724> (4c998b7 <https://github.com/python-semantic-release/python-semantic-release/commit/4c998b77a3fe5e12783d1ab2d47789a10b83f247>)

    •   cli-version: Change implementation to only push the tag we generated, closes #803 <https://github.com/python-semantic-release/python-semantic-release/issues/803> (8a9da4f <https://github.com/python-semantic-release/python-semantic-release/commit/8a9da4feb8753e3ab9ea752afa25decd2047675a>)

  ⚡ Performance Improvements

    •   algorithm: Simplify logs & use lookup when searching for commit & tag match (3690b95 <https://github.com/python-semantic-release/python-semantic-release/commit/3690b9511de633ab38083de4d2505b6d05853346>)

  v9.3.0 (2024-03-21)

  ✨ Features

    •   cmd-version: Changelog available to bundle (PR#779 <https://github.com/python-semantic-release/python-semantic-release/pull/779>, 37fdb28 <https://github.com/python-semantic-release/python-semantic-release/commit/37fdb28e0eb886d682b5dea4cc83a7c98a099422>)

    •   cmd-version: Create changelog prior to build enabling doc bundling (PR#779 <https://github.com/python-semantic-release/python-semantic-release/pull/779>, 37fdb28 <https://github.com/python-semantic-release/python-semantic-release/commit/37fdb28e0eb886d682b5dea4cc83a7c98a099422>)

  v9.2.2 (2024-03-19)

  🪲 Bug Fixes

    •   cli: Enable subcommand help even if config is invalid, closes #840 <https://github.com/python-semantic-release/python-semantic-release/issues/840> (91d221a <https://github.com/python-semantic-release/python-semantic-release/commit/91d221a01266e5ca6de5c73296b0a90987847494>)

  v9.2.1 (2024-03-19)

  🪲 Bug Fixes

    •   parse-git-url: Handle urls with url-safe special characters (27cd93a <https://github.com/python-semantic-release/python-semantic-release/commit/27cd93a0a65ee3787ca51be4c91c48f6ddb4269c>)

  v9.2.0 (2024-03-18)

  ✨ Features

    •   version: Add new version print flags to display the last released version and tag (814240c <https://github.com/python-semantic-release/python-semantic-release/commit/814240c7355df95e9be9a6ed31d004b800584bc0>)

    •   version-config: Add option to disable 0.x.x versions (dedb3b7 <https://github.com/python-semantic-release/python-semantic-release/commit/dedb3b765c8530379af61d3046c3bb9c160d54e5>)

  🪲 Bug Fixes

    •   changelog: Make sure default templates render ending in 1 newline (0b4a45e <https://github.com/python-semantic-release/python-semantic-release/commit/0b4a45e3673d0408016dc8e7b0dce98007a763e3>)

    •   changelog-generation: Fix incorrect release timezone determination (f802446 <https://github.com/python-semantic-release/python-semantic-release/commit/f802446bd0693c4c9f6bdfdceae8b89c447827d2>)

  📖 Documentation

    •   configuration: Add description of allow-zero-version configuration option (4028f83 <https://github.com/python-semantic-release/python-semantic-release/commit/4028f8384a0181c8d58c81ae81cf0b241a02a710>)

    •   configuration: Clarify the major_on_zero configuration option (f7753cd <https://github.com/python-semantic-release/python-semantic-release/commit/f7753cdabd07e276bc001478d605fca9a4b37ec4>)

  ⚙️ Build System

    •   deps: Add click-option-group for grouping exclusive flags (bd892b8 <https://github.com/python-semantic-release/python-semantic-release/commit/bd892b89c26df9fccc9335c84e2b3217e3e02a37>)

  v9.1.1 (2024-02-25)

  🪲 Bug Fixes

    •   parse_git_url: Fix bad url with dash (1c25b8e <https://github.com/python-semantic-release/python-semantic-release/commit/1c25b8e6f1e43c15ca7d5a59dca0a13767f9bc33>)

  v9.1.0 (2024-02-14)

  ✨ Features

    •   Add bitbucket hvcs (bbbbfeb <https://github.com/python-semantic-release/python-semantic-release/commit/bbbbfebff33dd24b8aed2d894de958d532eac596>)

  🪲 Bug Fixes

    •   Remove unofficial environment variables (a5168e4 <https://github.com/python-semantic-release/python-semantic-release/commit/a5168e40b9a14dbd022f62964f382b39faf1e0df>)

  📖 Documentation

    •   Add bitbucket authentication (b78a387 <https://github.com/python-semantic-release/python-semantic-release/commit/b78a387d8eccbc1a6a424a183254fc576126199c>)

    •   Add bitbucket to token table (56f146d <https://github.com/python-semantic-release/python-semantic-release/commit/56f146d9f4c0fc7f2a84ad11b21c8c45e9221782>)

    •   Fix typo (b240e12 <https://github.com/python-semantic-release/python-semantic-release/commit/b240e129b180d45c1d63d464283b7dfbcb641d0c>)

  ⚙️ Build System

    •   deps: Bump minimum required tomlkit to >=0.11.0, closes #834 <https://github.com/python-semantic-release/python-semantic-release/issues/834> (291aace <https://github.com/python-semantic-release/python-semantic-release/commit/291aacea1d0429a3b27e92b0a20b598f43f6ea6b>)

  v9.0.3 (2024-02-08)

  🪲 Bug Fixes

    •   algorithm: Correct bfs to not abort on previously visited node (02df305 <https://github.com/python-semantic-release/python-semantic-release/commit/02df305db43abfc3a1f160a4a52cc2afae5d854f>)

  ⚡ Performance Improvements

    •   algorithm: Refactor bfs search to use queue rather than recursion (8b742d3 <https://github.com/python-semantic-release/python-semantic-release/commit/8b742d3db6652981a7b5f773a74b0534edc1fc15>)

  v9.0.2 (2024-02-08)

  🪲 Bug Fixes

    •   util: Properly parse windows line-endings in commit messages, closes #820 <https://github.com/python-semantic-release/python-semantic-release/issues/820> (70193ba <https://github.com/python-semantic-release/python-semantic-release/commit/70193ba117c1a6d3690aed685fee8a734ba174e5>)

  📖 Documentation

    •   Remove duplicate note in configuration.rst (PR#807 <https://github.com/python-semantic-release/python-semantic-release/pull/807>, fb6f243 <https://github.com/python-semantic-release/python-semantic-release/commit/fb6f243a141642c02469f1080180ecaf4f3cec66>)

  v9.0.1 (2024-02-06)

  🪲 Bug Fixes

    •   config: Set commit parser opt defaults based on parser choice (PR#782 <https://github.com/python-semantic-release/python-semantic-release/pull/782>, 9c594fb <https://github.com/python-semantic-release/python-semantic-release/commit/9c594fb6efac7e4df2b0bfbd749777d3126d03d7>)

  v9.0.0 (2024-02-06)

  ♻️ Refactoring

    •   Drop support for Python 3.7 (PR#828 <https://github.com/python-semantic-release/python-semantic-release/pull/828>, ad086f5 <https://github.com/python-semantic-release/python-semantic-release/commit/ad086f5993ae4741d6e20fee618d1bce8df394fb>)

  💥 BREAKING CHANGES

    •   Removed Python 3.7 specific control flows and made more modern implementations the default control flow without a bypass or workaround. Will break on Python 3.7 now. If you require Python 3.7, you should lock your major version at v8. Since we only have enough manpower to maintain the latest major release, unfortunately there will not be any more updates to v8.

    •   We decided to remove support for Python 3.7 because it has been officially deprecated by the Python Foundation over a year ago and our codebase is starting to have limitations and custom implementations just to maintain support for 3.7.

  v8.7.2 (2024-01-03)

  🪲 Bug Fixes

    •   lint: Correct linter errors (c9556b0 <https://github.com/python-semantic-release/python-semantic-release/commit/c9556b0ca6df6a61e9ce909d18bc5be8b6154bf8>)

  v8.7.1 (2024-01-03)

  🪲 Bug Fixes

    •   cli-generate-config: Ensure configuration types are always toml parsable (PR#785 <https://github.com/python-semantic-release/python-semantic-release/pull/785>, 758e649 <https://github.com/python-semantic-release/python-semantic-release/commit/758e64975fe46b961809f35977574729b7c44271>)

  📖 Documentation

    •   Add note on default envvar behavior (PR#780 <https://github.com/python-semantic-release/python-semantic-release/pull/780>, 0b07cae <https://github.com/python-semantic-release/python-semantic-release/commit/0b07cae71915c5c82d7784898b44359249542a64>)

    •   configuration: Change defaults definition of token default to table (PR#786 <https://github.com/python-semantic-release/python-semantic-release/pull/786>, df1df0d <https://github.com/python-semantic-release/python-semantic-release/commit/df1df0de8bc655cbf8f86ae52aff10efdc66e6d2>)

    •   contributing: Add docs-build, testing conf, & build instructions (PR#787 <https://github.com/python-semantic-release/python-semantic-release/pull/787>, 011b072 <https://github.com/python-semantic-release/python-semantic-release/commit/011b0729cba3045b4e7291fd970cb17aad7bae60>)

  v8.7.0 (2023-12-22)

  ✨ Features

    •   config: Enable default environment token per hvcs (PR#774 <https://github.com/python-semantic-release/python-semantic-release/pull/774>, 26528eb <https://github.com/python-semantic-release/python-semantic-release/commit/26528eb8794d00dfe985812269702fbc4c4ec788>)

  v8.6.0 (2023-12-22)

  ✨ Features

    •   utils: Expand parsable valid git remote url formats (PR#771 <https://github.com/python-semantic-release/python-semantic-release/pull/771>, cf75f23 <https://github.com/python-semantic-release/python-semantic-release/commit/cf75f237360488ebb0088e5b8aae626e97d9cbdd>)

  📖 Documentation

    •   Minor correction to commit-parsing documentation (PR#777 <https://github.com/python-semantic-release/python-semantic-release/pull/777>, 245e878 <https://github.com/python-semantic-release/python-semantic-release/commit/245e878f02d5cafec6baf0493c921c1e396b56e8>)

  v8.5.2 (2023-12-19)

  🪲 Bug Fixes

    •   cli: Gracefully output configuration validation errors (PR#772 <https://github.com/python-semantic-release/python-semantic-release/pull/772>, e8c9d51 <https://github.com/python-semantic-release/python-semantic-release/commit/e8c9d516c37466a5dce75a73766d5be0f9e74627>)

  v8.5.1 (2023-12-12)

  🪲 Bug Fixes

    •   cmd-version: Handle committing of git-ignored file gracefully (PR#764 <https://github.com/python-semantic-release/python-semantic-release/pull/764>, ea89fa7 <https://github.com/python-semantic-release/python-semantic-release/commit/ea89fa72885e15da91687172355426a22c152513>)

    •   config: Cleanly handle repository in detached HEAD state (PR#765 <https://github.com/python-semantic-release/python-semantic-release/pull/765>, ac4f9aa <https://github.com/python-semantic-release/python-semantic-release/commit/ac4f9aacb72c99f2479ae33369822faad011a824>)

    •   config: Gracefully fail when repo is in a detached HEAD state (PR#765 <https://github.com/python-semantic-release/python-semantic-release/pull/765>, ac4f9aa <https://github.com/python-semantic-release/python-semantic-release/commit/ac4f9aacb72c99f2479ae33369822faad011a824>)

    •   version: Only commit non git-ignored files during version commit (PR#764 <https://github.com/python-semantic-release/python-semantic-release/pull/764>, ea89fa7 <https://github.com/python-semantic-release/python-semantic-release/commit/ea89fa72885e15da91687172355426a22c152513>)

  📖 Documentation

    •   configuration: Adjust wording and improve clarity (PR#766 <https://github.com/python-semantic-release/python-semantic-release/pull/766>, 6b2fc8c <https://github.com/python-semantic-release/python-semantic-release/commit/6b2fc8c156e122ee1b43fdb513b2dc3b8fd76724>)

    •   configuration: Fix typo in text (PR#766 <https://github.com/python-semantic-release/python-semantic-release/pull/766>, 6b2fc8c <https://github.com/python-semantic-release/python-semantic-release/commit/6b2fc8c156e122ee1b43fdb513b2dc3b8fd76724>)

  v8.5.0 (2023-12-07)

  ✨ Features

    •   Allow template directories to contain a '.' at the top-level (PR#762 <https://github.com/python-semantic-release/python-semantic-release/pull/762>, 07b232a <https://github.com/python-semantic-release/python-semantic-release/commit/07b232a3b34be0b28c6af08aea4852acb1b9bd56>)

  v8.4.0 (2023-12-07)

  ✨ Features

    •   cmd-version: Add --tag/--no-tag option to version command (PR#752 <https://github.com/python-semantic-release/python-semantic-release/pull/752>, de6b9ad <https://github.com/python-semantic-release/python-semantic-release/commit/de6b9ad921e697b5ea2bb2ea8f180893cecca920>)

    •   version: Add --no-tag option to turn off tag creation (PR#752 <https://github.com/python-semantic-release/python-semantic-release/pull/752>, de6b9ad <https://github.com/python-semantic-release/python-semantic-release/commit/de6b9ad921e697b5ea2bb2ea8f180893cecca920>)

  🪲 Bug Fixes

    •   version: Separate push tags from commit push when not committing changes (PR#752 <https://github.com/python-semantic-release/python-semantic-release/pull/752>, de6b9ad <https://github.com/python-semantic-release/python-semantic-release/commit/de6b9ad921e697b5ea2bb2ea8f180893cecca920>)

  📖 Documentation

    •   commands: Update version subcommand options (PR#752 <https://github.com/python-semantic-release/python-semantic-release/pull/752>, de6b9ad <https://github.com/python-semantic-release/python-semantic-release/commit/de6b9ad921e697b5ea2bb2ea8f180893cecca920>)

    •   migration: Fix comments about publish command (PR#747 <https://github.com/python-semantic-release/python-semantic-release/pull/747>, 90380d7 <https://github.com/python-semantic-release/python-semantic-release/commit/90380d797a734dcca5040afc5fa00e3e01f64152>)

  v8.3.0 (2023-10-23)

  ✨ Features

    •   action: Use composite action for semantic release (PR#692 <https://github.com/python-semantic-release/python-semantic-release/pull/692>, 4648d87 <https://github.com/python-semantic-release/python-semantic-release/commit/4648d87bac8fb7e6cc361b765b4391b30a8caef8>)

  v8.2.0 (2023-10-23)

  ✨ Features

    •   Allow user customization of release notes template (PR#736 <https://github.com/python-semantic-release/python-semantic-release/pull/736>, 94a1311 <https://github.com/python-semantic-release/python-semantic-release/commit/94a131167e1b867f8bc112a042b9766e050ccfd1>)

  📖 Documentation

    •   Add PYTHONPATH mention for commit parser (3284258 <https://github.com/python-semantic-release/python-semantic-release/commit/3284258b9fa1a3fe165f336181aff831d50fddd3>)

  v8.1.2 (2023-10-13)

  🪲 Bug Fixes

    •   Correct lint errors (a13a6c3 <https://github.com/python-semantic-release/python-semantic-release/commit/a13a6c37e180dc422599939a5725835306c18ff2>)

    •   Error when running build command on windows systems (PR#732 <https://github.com/python-semantic-release/python-semantic-release/pull/732>, 2553657 <https://github.com/python-semantic-release/python-semantic-release/commit/25536574760b407410f435441da533fafbf94402>)

  v8.1.1 (2023-09-19)

  🪲 Bug Fixes

    •   Attribute error when logging non-strings (PR#711 <https://github.com/python-semantic-release/python-semantic-release/pull/711>, 75e6e48 <https://github.com/python-semantic-release/python-semantic-release/commit/75e6e48129da8238a62d5eccac1ae55d0fee0f9f>)

  v8.1.0 (2023-09-19)

  ✨ Features

    •   Upgrade pydantic to v2 (PR#714 <https://github.com/python-semantic-release/python-semantic-release/pull/714>, 5a5c5d0 <https://github.com/python-semantic-release/python-semantic-release/commit/5a5c5d0ee347750d7c417c3242d52e8ada50b217>)

  📖 Documentation

    •   Fix typos (PR#708 <https://github.com/python-semantic-release/python-semantic-release/pull/708>, 2698b0e <https://github.com/python-semantic-release/python-semantic-release/commit/2698b0e006ff7e175430b98450ba248ed523b341>)

    •   Update project urls (PR#715 <https://github.com/python-semantic-release/python-semantic-release/pull/715>, 5fd5485 <https://github.com/python-semantic-release/python-semantic-release/commit/5fd54856dfb6774feffc40d36d5bb0f421f04842>)

  v8.0.8 (2023-08-26)

  🪲 Bug Fixes

    •   Dynamic_import() import path split (PR#686 <https://github.com/python-semantic-release/python-semantic-release/pull/686>, 1007a06 <https://github.com/python-semantic-release/python-semantic-release/commit/1007a06d1e16beef6d18f44ff2e0e09921854b54>)

  v8.0.7 (2023-08-16)

  🪲 Bug Fixes

    •   Use correct upload url for github (PR#661 <https://github.com/python-semantic-release/python-semantic-release/pull/661>, 8a515ca <https://github.com/python-semantic-release/python-semantic-release/commit/8a515caf1f993aa653e024beda2fdb9e629cc42a>)

  v8.0.6 (2023-08-13)

  🪲 Bug Fixes

    •   publish: Improve error message when no tags found (PR#683 <https://github.com/python-semantic-release/python-semantic-release/pull/683>, bdc06ea <https://github.com/python-semantic-release/python-semantic-release/commit/bdc06ea061c19134d5d74bd9f168700dd5d9bcf5>)

  v8.0.5 (2023-08-10)

  🪲 Bug Fixes

    •   Don't warn about vcs token if ignore_token_for_push is true. (PR#670 <https://github.com/python-semantic-release/python-semantic-release/pull/670>, f1a54a6 <https://github.com/python-semantic-release/python-semantic-release/commit/f1a54a6c9a05b225b6474d50cd610eca19ec0c34>)

  📖 Documentation

    •   password should be token. (PR#670 <https://github.com/python-semantic-release/python-semantic-release/pull/670>, f1a54a6 <https://github.com/python-semantic-release/python-semantic-release/commit/f1a54a6c9a05b225b6474d50cd610eca19ec0c34>)

    •   Fix typo missing 's' in version_variable[s] in configuration.rst (PR#668 <https://github.com/python-semantic-release/python-semantic-release/pull/668>, 879186a <https://github.com/python-semantic-release/python-semantic-release/commit/879186aa09a3bea8bbe2b472f892cf7c0712e557>)

  v8.0.4 (2023-07-26)

  🪲 Bug Fixes

    •   changelog: Use version as semver tag by default (PR#653 <https://github.com/python-semantic-release/python-semantic-release/pull/653>, 5984c77 <https://github.com/python-semantic-release/python-semantic-release/commit/5984c7771edc37f0d7d57894adecc2591efc414d>)

  📖 Documentation

    •   Add Python 3.11 to classifiers in metadata (PR#651 <https://github.com/python-semantic-release/python-semantic-release/pull/651>, 5a32a24 <https://github.com/python-semantic-release/python-semantic-release/commit/5a32a24bf4128c39903f0c5d3bd0cb1ccba57e18>)

    •   Clarify usage of assets config option (PR#655 <https://github.com/python-semantic-release/python-semantic-release/pull/655>, efa2b30 <https://github.com/python-semantic-release/python-semantic-release/commit/efa2b3019b41eb427f0e1c8faa21ad10664295d0>)

  v8.0.3 (2023-07-21)

  🪲 Bug Fixes

    •   Skip non-parsable versions when calculating next version (PR#649 <https://github.com/python-semantic-release/python-semantic-release/pull/649>, 88f25ea <https://github.com/python-semantic-release/python-semantic-release/commit/88f25eae62589cdf53dbc3dfcb167a3ae6cba2d3>)

  v8.0.2 (2023-07-18)

  🪲 Bug Fixes

    •   Handle missing configuration (PR#644 <https://github.com/python-semantic-release/python-semantic-release/pull/644>, f15753c <https://github.com/python-semantic-release/python-semantic-release/commit/f15753ce652f36cc03b108c667a26ab74bcbf95d>)

  📖 Documentation

    •   Better description for tag_format usage (2129b72 <https://github.com/python-semantic-release/python-semantic-release/commit/2129b729837eccc41a33dbb49785a8a30ce6b187>)

    •   Clarify v8 breaking changes in GitHub action inputs (PR#643 <https://github.com/python-semantic-release/python-semantic-release/pull/643>, cda050c <https://github.com/python-semantic-release/python-semantic-release/commit/cda050cd9e789d81458157ee240ff99ec65c6f25>)

    •   Correct version_toml example in migrating_from_v7.rst (PR#641 <https://github.com/python-semantic-release/python-semantic-release/pull/641>, 325d5e0 <https://github.com/python-semantic-release/python-semantic-release/commit/325d5e048bd89cb2a94c47029d4878b27311c0f0>)

  v8.0.1 (2023-07-17)

  🪲 Bug Fixes

    •   Invalid version in Git history should not cause a release failure (PR#632 <https://github.com/python-semantic-release/python-semantic-release/pull/632>, 254430b <https://github.com/python-semantic-release/python-semantic-release/commit/254430b5cc5f032016b4c73168f0403c4d87541e>)

  📖 Documentation

    •   Reduce readthedocs formats and add entries to migration from v7 guide (9b6ddfe <https://github.com/python-semantic-release/python-semantic-release/commit/9b6ddfef448f9de30fa2845034f76655d34a9912>)

    •   migration: Fix hyperlink (PR#631 <https://github.com/python-semantic-release/python-semantic-release/pull/631>, 5fbd52d <https://github.com/python-semantic-release/python-semantic-release/commit/5fbd52d7de4982b5689651201a0e07b445158645>)

  v8.0.0 (2023-07-16)

  ✨ Features

    •   publish-cmd: Add --post-to-release-tag option to control where to publish (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Make it easier to access commit messages in ParsedCommits (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Remove publication of dists/ to artifact repository (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Rename 'upload' configuration section to 'publish' (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   github-action: Add GitHub Actions output variables (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   version-cmd: Add --skip-build option (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   version-cmd Add --strict version mode (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

  🪲 Bug Fixes

    •   Add logging for token auth, use token for push (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Caching for repo owner and name (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Correct assets type in configuration (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Correct assets type-annotation for RuntimeContext (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Correct Dockerfile CLI command and GHA fetch (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Correct handling of build commands (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Correct logic for generating release notes (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Create_or_update_release for Gitlab hvcs (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Make additional attributes available for template authors (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Only call Github Action output callback once defaults are set (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Remove commit amending behavior (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Resolve branch checkout logic in GHA (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Resolve bug in changelog logic, enable upload to pypi (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Resolve loss of tag_format configuration (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   github-action: Pin Debian version in Dockerfile (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   github-action: Correct input parsing (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   github-action: Mark container fs as safe for git to operate on (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   github-action: Quotation for git config command (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   github-action: Remove default for 'force' (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

  📖 Documentation

    •   Convert to Furo theme (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Fix typo (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Remove reference to dist publication (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   Update docs with additional required permissions (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

    •   changelog-templates: fix typo (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

  ♻️ Refactoring

    •   Remove verify-ci command (PR#619 <https://github.com/python-semantic-release/python-semantic-release/pull/619>, ec30564 <https://github.com/python-semantic-release/python-semantic-release/commit/ec30564b4ec732c001d76d3c09ba033066d2b6fe>)

  💥 BREAKING CHANGES

    •   numerous breaking changes, see Upgrading to v8 <#upgrade-v8> for more information

  v7.34.6 (2023-06-17)

  🪲 Bug Fixes

    •   Relax invoke dependency constraint (18ea200 <https://github.com/python-semantic-release/python-semantic-release/commit/18ea200633fd67e07f3d4121df5aa4c6dd29d154>)

  v7.34.5 (2023-06-17)

  🪲 Bug Fixes

    •   Consider empty commits (PR#608 <https://github.com/python-semantic-release/python-semantic-release/pull/608>, 6f2e890 <https://github.com/python-semantic-release/python-semantic-release/commit/6f2e8909636595d3cb5e858f42c63820cda45974>)

  v7.34.4 (2023-06-15)

  🪲 Bug Fixes

    •   Docker build fails installing git (PR#605 <https://github.com/python-semantic-release/python-semantic-release/pull/605>, 9e3eb97 <https://github.com/python-semantic-release/python-semantic-release/commit/9e3eb979783bc39ca564c2967c6c77eecba682e6>)

  v7.34.3 (2023-06-01)

  🪲 Bug Fixes

    •   Generate markdown linter compliant changelog headers & lists (PR#597 <https://github.com/python-semantic-release/python-semantic-release/pull/597>, cc87400 <https://github.com/python-semantic-release/python-semantic-release/commit/cc87400d4a823350de7d02dc3172d2488c9517db>)

  v7.34.2 (2023-05-29)

  🪲 Bug Fixes

    •   Open all files with explicit utf-8 encoding (PR#596 <https://github.com/python-semantic-release/python-semantic-release/pull/596>, cb71f35 <https://github.com/python-semantic-release/python-semantic-release/commit/cb71f35c26c1655e675fa735fa880d39a2c8af9c>)

  v7.34.1 (2023-05-28)

  🪲 Bug Fixes

    •   Generate markdown linter compliant changelog headers & lists (PR#594 <https://github.com/python-semantic-release/python-semantic-release/pull/594>, 9d9d403 <https://github.com/python-semantic-release/python-semantic-release/commit/9d9d40305c499c907335abe313e3ed122db0b154>)

  v7.34.0 (2023-05-28)

  ✨ Features

    •   Add option to only parse commits for current working directory (PR#509 <https://github.com/python-semantic-release/python-semantic-release/pull/509>, cdf8116 <https://github.com/python-semantic-release/python-semantic-release/commit/cdf8116c1e415363b10a01f541873e04ad874220>)

  v7.33.5 (2023-05-19)

  🪲 Bug Fixes

    •   Update docs and default config for gitmoji changes (PR#590 <https://github.com/python-semantic-release/python-semantic-release/pull/590>, 192da6e <https://github.com/python-semantic-release/python-semantic-release/commit/192da6e1352298b48630423d50191070a1c5ab24>)

    •   Update sphinx dep (PR#590 <https://github.com/python-semantic-release/python-semantic-release/pull/590>, 192da6e <https://github.com/python-semantic-release/python-semantic-release/commit/192da6e1352298b48630423d50191070a1c5ab24>)

  📖 Documentation

    •   Update broken badge and add links (PR#591 <https://github.com/python-semantic-release/python-semantic-release/pull/591>, 0c23447 <https://github.com/python-semantic-release/python-semantic-release/commit/0c234475d27ad887b19170c82deb80293b3a95f1>)

  v7.33.4 (2023-05-14)

  🪲 Bug Fixes

    •   If prerelease, publish prerelease (PR#587 <https://github.com/python-semantic-release/python-semantic-release/pull/587>, 927da9f <https://github.com/python-semantic-release/python-semantic-release/commit/927da9f8feb881e02bc08b33dc559bd8e7fc41ab>)

  v7.33.3 (2023-04-24)

  🪲 Bug Fixes

    •   Trim emojis from config (PR#583 <https://github.com/python-semantic-release/python-semantic-release/pull/583>, 02902f7 <https://github.com/python-semantic-release/python-semantic-release/commit/02902f73ee961565c2470c000f00947d9ef06cb1>)

    •   Update Gitmojis according to official node module (PR#582 <https://github.com/python-semantic-release/python-semantic-release/pull/582>, 806fcfa <https://github.com/python-semantic-release/python-semantic-release/commit/806fcfa4cfdd3df4b380afd015a68dc90d54215a>)

  📖 Documentation

    •   Grammar in docs/troubleshooting.rst (PR#557 <https://github.com/python-semantic-release/python-semantic-release/pull/557>, bbe754a <https://github.com/python-semantic-release/python-semantic-release/commit/bbe754a3db9ce7132749e7902fe118b52f48ee42>)

    •   Spelling and grammar in travis.rst (PR#556 <https://github.com/python-semantic-release/python-semantic-release/pull/556>, 3a76e9d <https://github.com/python-semantic-release/python-semantic-release/commit/3a76e9d7505c421009eb3e953c32cccac2e70e07>)

    •   Update repository name (PR#559 <https://github.com/python-semantic-release/python-semantic-release/pull/559>, 5cdb05e <https://github.com/python-semantic-release/python-semantic-release/commit/5cdb05e20f17b12890e1487c42d317dcbadd06c8>)

  v7.33.2 (2023-02-17)

  🪲 Bug Fixes

    •   Inconsistent versioning between print-version and publish (PR#524 <https://github.com/python-semantic-release/python-semantic-release/pull/524>, 17d60e9 <https://github.com/python-semantic-release/python-semantic-release/commit/17d60e9bf66f62e5845065486c9d5e450f74839a>)

  v7.33.1 (2023-02-01)

  🪲 Bug Fixes

    •   action: Mark container fs as safe for git (PR#552 <https://github.com/python-semantic-release/python-semantic-release/pull/552>, 2a55f68 <https://github.com/python-semantic-release/python-semantic-release/commit/2a55f68e2b3cb9ffa9204c00ddbf12706af5c070>)

  v7.33.0 (2023-01-15)

  ✨ Features

    •   Add signing options to action (31ad5eb <https://github.com/python-semantic-release/python-semantic-release/commit/31ad5eb5a25f0ea703afc295351104aefd66cac1>)

    •   Update action with configuration options (PR#518 <https://github.com/python-semantic-release/python-semantic-release/pull/518>, 4664afe <https://github.com/python-semantic-release/python-semantic-release/commit/4664afe5f80a04834e398fefb841b166a51d95b7>)

    •   repository: Add support for TWINE_CERT, closes #521 <https://github.com/python-semantic-release/python-semantic-release/issues/521> (PR#522 <https://github.com/python-semantic-release/python-semantic-release/pull/522>, d56e85d <https://github.com/python-semantic-release/python-semantic-release/commit/d56e85d1f2ac66fb0b59af2178164ca915dbe163>)

  🪲 Bug Fixes

    •   Changelog release commit search logic (PR#530 <https://github.com/python-semantic-release/python-semantic-release/pull/530>, efb3410 <https://github.com/python-semantic-release/python-semantic-release/commit/efb341036196c39b4694ca4bfa56c6b3e0827c6c>)

    •   github-actions: Bump Dockerfile to use Python 3.10 image, closes #533 <https://github.com/python-semantic-release/python-semantic-release/issues/533> (PR#536 <https://github.com/python-semantic-release/python-semantic-release/pull/536>, 8f2185d <https://github.com/python-semantic-release/python-semantic-release/commit/8f2185d570b3966b667ac591ae523812e9d2e00f>)

    •   action: Fix environment variable names (3c66218 <https://github.com/python-semantic-release/python-semantic-release/commit/3c66218640044adf263fcf9b2714cfc4b99c2e90>)

  📖 Documentation

    •   Update documentation (5cbdad2 <https://github.com/python-semantic-release/python-semantic-release/commit/5cbdad296034a792c9bf05e3700eac4f847eb469>)

  v7.32.2 (2022-10-22)

  🪲 Bug Fixes

    •   Fix changelog generation in tag-mode (PR#171 <https://github.com/python-semantic-release/python-semantic-release/pull/171>, 482a62e <https://github.com/python-semantic-release/python-semantic-release/commit/482a62ec374208b2d57675cb0b7f0ab9695849b9>)

  📖 Documentation

    •   Fix code blocks (PR#506 <https://github.com/python-semantic-release/python-semantic-release/pull/506>, 24b7673 <https://github.com/python-semantic-release/python-semantic-release/commit/24b767339fcef1c843f7dd3188900adab05e03b1>)

  v7.32.1 (2022-10-07)

  🪲 Bug Fixes

    •   Corrections for deprecation warnings (PR#505 <https://github.com/python-semantic-release/python-semantic-release/pull/505>, d47afb6 <https://github.com/python-semantic-release/python-semantic-release/commit/d47afb6516238939e174f946977bf4880062a622>)

  📖 Documentation

    •   Correct spelling mistakes (PR#504 <https://github.com/python-semantic-release/python-semantic-release/pull/504>, 3717e0d <https://github.com/python-semantic-release/python-semantic-release/commit/3717e0d8810f5d683847c7b0e335eeefebbf2921>)

  v7.32.0 (2022-09-25)

  ✨ Features

    •   Add setting for enforcing textual changelog sections, closes #498 <https://github.com/python-semantic-release/python-semantic-release/issues/498> (PR#502 <https://github.com/python-semantic-release/python-semantic-release/pull/502>, 988437d <https://github.com/python-semantic-release/python-semantic-release/commit/988437d21e40d3e3b1c95ed66b535bdd523210de>)

  📖 Documentation

    •   Correct documented default behavior for commit_version_number (PR#497 <https://github.com/python-semantic-release/python-semantic-release/pull/497>, ffae2dc <https://github.com/python-semantic-release/python-semantic-release/commit/ffae2dc68f7f4bc13c5fd015acd43b457e568ada>)

  v7.31.4 (2022-08-23)

  🪲 Bug Fixes

    •   Account for trailing newlines in commit messages, closes #490 <https://github.com/python-semantic-release/python-semantic-release/issues/490> (PR#495 <https://github.com/python-semantic-release/python-semantic-release/pull/495>, 111b151 <https://github.com/python-semantic-release/python-semantic-release/commit/111b1518e8c8e2bd7535bd4c4b126548da384605>)

  v7.31.3 (2022-08-22)

  🪲 Bug Fixes

    •   Use commit_subject when searching for release commits (PR#488 <https://github.com/python-semantic-release/python-semantic-release/pull/488>, 3849ed9 <https://github.com/python-semantic-release/python-semantic-release/commit/3849ed992c3cff9054b8690bcf59e49768f84f47>)

  v7.31.2 (2022-07-29)

  🪲 Bug Fixes

    •   Add better handling of missing changelog placeholder, closes #454 <https://github.com/python-semantic-release/python-semantic-release/issues/454> (e7a0e81 <https://github.com/python-semantic-release/python-semantic-release/commit/e7a0e81c004ade73ed927ba4de8c3e3ccaf0047c>)

    •   Add repo=None when not in git repo, closes #422 <https://github.com/python-semantic-release/python-semantic-release/issues/422> (40be804 <https://github.com/python-semantic-release/python-semantic-release/commit/40be804c09ab8a036fb135c9c38a63f206d2742c>)

  📖 Documentation

    •   Add example for pyproject.toml (2a4b8af <https://github.com/python-semantic-release/python-semantic-release/commit/2a4b8af1c2893a769c02476bb92f760c8522bd7a>)

  v7.31.1 (2022-07-29)

  🪲 Bug Fixes

    •   Update git email in action, closes #473 <https://github.com/python-semantic-release/python-semantic-release/issues/473> (0ece6f2 <https://github.com/python-semantic-release/python-semantic-release/commit/0ece6f263ff02a17bb1e00e7ed21c490f72e3d00>)

  v7.31.0 (2022-07-29)

  ✨ Features

    •   Add prerelease-patch and no-prerelease-patch flags for whether to auto-bump prereleases (b4e5b62 <https://github.com/python-semantic-release/python-semantic-release/commit/b4e5b626074f969e4140c75fdac837a0625cfbf6>)

    •   Override repository_url w REPOSITORY_URL env var (PR#439 <https://github.com/python-semantic-release/python-semantic-release/pull/439>, cb7578c <https://github.com/python-semantic-release/python-semantic-release/commit/cb7578cf005b8bd65d9b988f6f773e4c060982e3>)

  🪲 Bug Fixes

    •

        bug fix get_current_release_version for tag_only version_source (cad09be <https://github.com/python-semantic-release/python-semantic-release/commit/cad09be9ba067f1c882379c0f4b28115a287fc2b>)

  v7.30.2 (2022-07-26)

  🪲 Bug Fixes

    •   Declare additional_options as action inputs (PR#481 <https://github.com/python-semantic-release/python-semantic-release/pull/481>, cb5d8c7 <https://github.com/python-semantic-release/python-semantic-release/commit/cb5d8c7ce7d013fcfabd7696b5ffb846a8a6f853>)

  v7.30.1 (2022-07-25)

  🪲 Bug Fixes

    •   Don't use commit_subject for tag pattern matching (PR#480 <https://github.com/python-semantic-release/python-semantic-release/pull/480>, ac3f11e <https://github.com/python-semantic-release/python-semantic-release/commit/ac3f11e689f4a290d20b68b9c5c214098eb61b5f>)

  v7.30.0 (2022-07-25)

  ✨ Features

    •   Add additional_options input for GitHub Action (PR#477 <https://github.com/python-semantic-release/python-semantic-release/pull/477>, aea60e3 <https://github.com/python-semantic-release/python-semantic-release/commit/aea60e3d290c6fe3137bff21e0db1ed936233776>)

  🪲 Bug Fixes

    •   Allow empty additional options (PR#479 <https://github.com/python-semantic-release/python-semantic-release/pull/479>, c9b2514 <https://github.com/python-semantic-release/python-semantic-release/commit/c9b2514d3e164b20e78b33f60989d78c2587e1df>)

  v7.29.7 (2022-07-24)

  🪲 Bug Fixes

    •   Ignore dependency version bumps when parsing version from commit logs (PR#476 <https://github.com/python-semantic-release/python-semantic-release/pull/476>, 51bcb78 <https://github.com/python-semantic-release/python-semantic-release/commit/51bcb780a9f55fadfaf01612ff65c1f92642c2c1>)

  v7.29.6 (2022-07-15)

  🪲 Bug Fixes

    •   Allow changing prerelease tag using CLI flags (PR#466 <https://github.com/python-semantic-release/python-semantic-release/pull/466>, 395bf4f <https://github.com/python-semantic-release/python-semantic-release/commit/395bf4f2de73663c070f37cced85162d41934213>)

  v7.29.5 (2022-07-14)

  🪲 Bug Fixes

    •   Add packaging module requirement (PR#469 <https://github.com/python-semantic-release/python-semantic-release/pull/469>, b99c9fa <https://github.com/python-semantic-release/python-semantic-release/commit/b99c9fa88dc25e5ceacb131cd93d9079c4fb2c86>)

    •   publish: Get version bump for current release (PR#467 <https://github.com/python-semantic-release/python-semantic-release/pull/467>, dd26888 <https://github.com/python-semantic-release/python-semantic-release/commit/dd26888a923b2f480303c19f1916647de48b02bf>)

  v7.29.4 (2022-06-29)

  🪲 Bug Fixes

    •   Add text for empty ValueError (PR#461 <https://github.com/python-semantic-release/python-semantic-release/pull/461>, 733254a <https://github.com/python-semantic-release/python-semantic-release/commit/733254a99320d8c2f964d799ac4ec29737867faa>)

  v7.29.3 (2022-06-26)

  🪲 Bug Fixes

    •   Ensure that assets can be uploaded successfully on custom GitHub servers (PR#458 <https://github.com/python-semantic-release/python-semantic-release/pull/458>, 32b516d <https://github.com/python-semantic-release/python-semantic-release/commit/32b516d7aded4afcafe4aa56d6a5a329b3fc371d>)

  v7.29.2 (2022-06-20)

  🪲 Bug Fixes

    •   Ensure should_bump checks against release version if not prerelease (PR#457 <https://github.com/python-semantic-release/python-semantic-release/pull/457>, da0606f <https://github.com/python-semantic-release/python-semantic-release/commit/da0606f0d67ada5f097c704b9423ead3b5aca6b2>)

  v7.29.1 (2022-06-01)

  🪲 Bug Fixes

    •   Capture correct release version when patch has more than one digit (PR#448 <https://github.com/python-semantic-release/python-semantic-release/pull/448>, 426cdc7 <https://github.com/python-semantic-release/python-semantic-release/commit/426cdc7d7e0140da67f33b6853af71b2295aaac2>)

  v7.29.0 (2022-05-27)

  ✨ Features

    •   Allow using ssh-key to push version while using token to publish to hvcs (PR#419 <https://github.com/python-semantic-release/python-semantic-release/pull/419>, 7b2dffa <https://github.com/python-semantic-release/python-semantic-release/commit/7b2dffadf43c77d5e0eea307aefcee5c7744df5c>)

    •   config: Add ignore_token_for_push param (PR#419 <https://github.com/python-semantic-release/python-semantic-release/pull/419>, 7b2dffa <https://github.com/python-semantic-release/python-semantic-release/commit/7b2dffadf43c77d5e0eea307aefcee5c7744df5c>)

  🪲 Bug Fixes

    •   Fix and refactor prerelease (PR#435 <https://github.com/python-semantic-release/python-semantic-release/pull/435>, 94c9494 <https://github.com/python-semantic-release/python-semantic-release/commit/94c94942561f85f48433c95fd3467e03e0893ab4>)

    •   test: Override GITHUB_ACTOR env (PR#419 <https://github.com/python-semantic-release/python-semantic-release/pull/419>, 7b2dffa <https://github.com/python-semantic-release/python-semantic-release/commit/7b2dffadf43c77d5e0eea307aefcee5c7744df5c>)

  📖 Documentation

    •   Add documentation for ignore_token_for_push (PR#419 <https://github.com/python-semantic-release/python-semantic-release/pull/419>, 7b2dffa <https://github.com/python-semantic-release/python-semantic-release/commit/7b2dffadf43c77d5e0eea307aefcee5c7744df5c>)

  v7.28.1 (2022-04-14)

  🪲 Bug Fixes

    •   Fix getting current version when version_source=tag_only (PR#437 <https://github.com/python-semantic-release/python-semantic-release/pull/437>, b247936 <https://github.com/python-semantic-release/python-semantic-release/commit/b247936a81c0d859a34bf9f17ab8ca6a80488081>)

  v7.28.0 (2022-04-11)

  ✨ Features

    •   Add tag_only option for version_source, closes #354 <https://github.com/python-semantic-release/python-semantic-release/issues/354> (PR#436 <https://github.com/python-semantic-release/python-semantic-release/pull/436>, cf74339 <https://github.com/python-semantic-release/python-semantic-release/commit/cf743395456a86c62679c2c0342502af043bfc3b>)

  v7.27.1 (2022-04-03)

  🪲 Bug Fixes

    •   prerelease: Pass prerelease option to get_current_version (PR#432 <https://github.com/python-semantic-release/python-semantic-release/pull/432>, aabab0b <https://github.com/python-semantic-release/python-semantic-release/commit/aabab0b7ce647d25e0c78ae6566f1132ece9fcb9>)

  v7.27.0 (2022-03-15)

  ✨ Features

    •   Add git-lfs to docker container (PR#427 <https://github.com/python-semantic-release/python-semantic-release/pull/427>, 184e365 <https://github.com/python-semantic-release/python-semantic-release/commit/184e3653932979b82e5a62b497f2a46cbe15ba87>)

  v7.26.0 (2022-03-07)

  ✨ Features

    •   publish-cmd: add --prerelease cli flag to enable prerelease versioning (PR#413 <https://github.com/python-semantic-release/python-semantic-release/pull/413>, 7064265 <https://github.com/python-semantic-release/python-semantic-release/commit/7064265627a2aba09caa2873d823b594e0e23e77>)

    •   version-cmd: add --prerelease cli flag to enable prerelease versioning (PR#413 <https://github.com/python-semantic-release/python-semantic-release/pull/413>, 7064265 <https://github.com/python-semantic-release/python-semantic-release/commit/7064265627a2aba09caa2873d823b594e0e23e77>)

  📖 Documentation

    •   Added basic info about prerelease versioning (PR#413 <https://github.com/python-semantic-release/python-semantic-release/pull/413>, 7064265 <https://github.com/python-semantic-release/python-semantic-release/commit/7064265627a2aba09caa2873d823b594e0e23e77>)

  v7.25.2 (2022-02-24)

  🪲 Bug Fixes

    •   gitea: Use form-data from asset upload (PR#421 <https://github.com/python-semantic-release/python-semantic-release/pull/421>, e011944 <https://github.com/python-semantic-release/python-semantic-release/commit/e011944987885f75b80fe16a363f4befb2519a91>)

  v7.25.1 (2022-02-23)

  🪲 Bug Fixes

    •   gitea: Build status and asset upload (PR#420 <https://github.com/python-semantic-release/python-semantic-release/pull/420>, 57db81f <https://github.com/python-semantic-release/python-semantic-release/commit/57db81f4c6b96da8259e3bad9137eaccbcd10f6e>)

    •   gitea: Handle list build status response (PR#420 <https://github.com/python-semantic-release/python-semantic-release/pull/420>, 57db81f <https://github.com/python-semantic-release/python-semantic-release/commit/57db81f4c6b96da8259e3bad9137eaccbcd10f6e>)

  v7.25.0 (2022-02-17)

  ✨ Features

    •   hvcs: Add gitea support (PR#412 <https://github.com/python-semantic-release/python-semantic-release/pull/412>, b7e7936 <https://github.com/python-semantic-release/python-semantic-release/commit/b7e7936331b7939db09abab235c8866d800ddc1a>)

  📖 Documentation

    •   Document tag_commit, closes #410 <https://github.com/python-semantic-release/python-semantic-release/issues/410> (b631ca0 <https://github.com/python-semantic-release/python-semantic-release/commit/b631ca0a79cb2d5499715d43688fc284cffb3044>)

  v7.24.0 (2022-01-24)

  ✨ Features

    •   Include additional changes in release commits (3e34f95 <https://github.com/python-semantic-release/python-semantic-release/commit/3e34f957ff5a3ec6e6f984cc4a79a38ce4391ea9>)

  v7.23.0 (2021-11-30)

  ✨ Features

    •   Support Github Enterprise server (b4e01f1 <https://github.com/python-semantic-release/python-semantic-release/commit/b4e01f1b7e841263fa84f57f0ac331f7c0b31954>)

  v7.22.0 (2021-11-21)

  ✨ Features

    •   parser_angular: Allow customization in parser (298eebb <https://github.com/python-semantic-release/python-semantic-release/commit/298eebbfab5c083505036ba1df47a5874a1eed6e>)

  🪲 Bug Fixes

    •   Address PR feedback for parser_angular.py (f7bc458 <https://github.com/python-semantic-release/python-semantic-release/commit/f7bc45841e6a5c762f99f936c292cee25fabcd02>)

  v7.21.0 (2021-11-21)

  ✨ Features

    •   Use gitlab-ci or github actions env vars, closes #363 <https://github.com/python-semantic-release/python-semantic-release/issues/363> (8ca8dd4 <https://github.com/python-semantic-release/python-semantic-release/commit/8ca8dd40f742f823af147928bd75a9577c50d0fd>)

  🪲 Bug Fixes

    •   Remove invalid repository exception (746b62d <https://github.com/python-semantic-release/python-semantic-release/commit/746b62d4e207a5d491eecd4ca96d096eb22e3bed>)

  v7.20.0 (2021-11-21)

  ✨ Features

    •   Allow custom environment variable names (PR#392 <https://github.com/python-semantic-release/python-semantic-release/pull/392>, 372cda3 <https://github.com/python-semantic-release/python-semantic-release/commit/372cda3497f16ead2209e6e1377d38f497144883>)

    •   Rewrite Twine adapter for uploading to artifact repositories (cfb20af <https://github.com/python-semantic-release/python-semantic-release/commit/cfb20af79a8e25a77aee9ff72deedcd63cb7f62f>)

  🪲 Bug Fixes

    •   Don't use linux commands on windows (PR#393 <https://github.com/python-semantic-release/python-semantic-release/pull/393>, 5bcccd2 <https://github.com/python-semantic-release/python-semantic-release/commit/5bcccd21cc8be3289db260e645fec8dc6a592abd>)

    •   Mypy errors in vcs_helpers (13ca0fe <https://github.com/python-semantic-release/python-semantic-release/commit/13ca0fe650125be2f5e953f6193fdc4d44d3c75a>)

    •   Skip removing the build folder if it doesn't exist (8e79fdc <https://github.com/python-semantic-release/python-semantic-release/commit/8e79fdc107ffd852a91dfb5473e7bd1dfaba4ee5>)

  📖 Documentation

    •   Clean typos and add section for repository upload (1efa18a <https://github.com/python-semantic-release/python-semantic-release/commit/1efa18a3a55134d6bc6e4572ab025e24082476cd>)

  v7.19.2 (2021-09-04)

  🪲 Bug Fixes

    •   Fixed ImproperConfig import error (PR#377 <https://github.com/python-semantic-release/python-semantic-release/pull/377>, b011a95 <https://github.com/python-semantic-release/python-semantic-release/commit/b011a9595df4240cb190bfb1ab5b6d170e430dfc>)

  v7.19.1 (2021-08-17)

  🪲 Bug Fixes

    •   Add get_formatted_tag helper instead of hardcoded v-prefix in the git tags (1a354c8 <https://github.com/python-semantic-release/python-semantic-release/commit/1a354c86abad77563ebce9a6944256461006f3c7>)

  v7.19.0 (2021-08-16)

  ✨ Features

    •   Custom git tag format support (PR#373 <https://github.com/python-semantic-release/python-semantic-release/pull/373>, 1d76632 <https://github.com/python-semantic-release/python-semantic-release/commit/1d76632043bf0b6076d214a63c92013624f4b95e>)

  📖 Documentation

    •   configuration: define tag_format usage & resulting effect (PR#373 <https://github.com/python-semantic-release/python-semantic-release/pull/373>, 1d76632 <https://github.com/python-semantic-release/python-semantic-release/commit/1d76632043bf0b6076d214a63c92013624f4b95e>)

    •   parser: Documentation for scipy-parser (45ee34a <https://github.com/python-semantic-release/python-semantic-release/commit/45ee34aa21443860a6c2cd44a52da2f353b960bf>)

  v7.18.0 (2021-08-09)

  ✨ Features

    •   Add support for non-prefixed tags (PR#366 <https://github.com/python-semantic-release/python-semantic-release/pull/366>, 0fee4dd <https://github.com/python-semantic-release/python-semantic-release/commit/0fee4ddb5baaddf85ed6b76e76a04474a5f97d0a>)

  📖 Documentation

    •   Clarify second argument of ParsedCommit (086ddc2 <https://github.com/python-semantic-release/python-semantic-release/commit/086ddc28f06522453328f5ea94c873bd202ff496>)

  v7.17.0 (2021-08-07)

  ✨ Features

    •   parser: Add scipy style parser (PR#369 <https://github.com/python-semantic-release/python-semantic-release/pull/369>, 51a3921 <https://github.com/python-semantic-release/python-semantic-release/commit/51a39213ea120c4bbd7a57b74d4f0cc3103da9f5>)

  v7.16.4 (2021-08-03)

  🪲 Bug Fixes

    •   Correct rendering of gitlab issue references, closes #358 <https://github.com/python-semantic-release/python-semantic-release/issues/358> (07429ec <https://github.com/python-semantic-release/python-semantic-release/commit/07429ec4a32d32069f25ec77b4bea963bd5d2a00>)

  v7.16.3 (2021-07-29)

  🪲 Bug Fixes

    •   Print right info if token is not set, closes #360 <https://github.com/python-semantic-release/python-semantic-release/issues/360> (PR#361 <https://github.com/python-semantic-release/python-semantic-release/pull/361>, a275a7a <https://github.com/python-semantic-release/python-semantic-release/commit/a275a7a17def85ff0b41d254e4ee42772cce1981>)

  v7.16.2 (2021-06-25)

  🪲 Bug Fixes

    •   Use release-api for gitlab (1ef5cab <https://github.com/python-semantic-release/python-semantic-release/commit/1ef5caba2d8dd0f2647bc51ede0ef7152d8b7b8d>)

  📖 Documentation

    •   Recommend setting a concurrency group for GitHub Actions (34b0735 <https://github.com/python-semantic-release/python-semantic-release/commit/34b07357ab3f4f4aa787b71183816ec8aaf334a8>)

    •   Update trove classifiers to reflect supported versions (PR#344 <https://github.com/python-semantic-release/python-semantic-release/pull/344>, 7578004 <https://github.com/python-semantic-release/python-semantic-release/commit/7578004ed4b20c2bd553782443dfd77535faa377>)

  v7.16.1 (2021-06-08)

  🪲 Bug Fixes

    •   Tomlkit should stay at 0.7.0 (769a5f3 <https://github.com/python-semantic-release/python-semantic-release/commit/769a5f31115cdb1f43f19a23fe72b96a8c8ba0fc>)

  v7.16.0 (2021-06-08)

  ✨ Features

    •   Add option to omit tagging (PR#341 <https://github.com/python-semantic-release/python-semantic-release/pull/341>, 20603e5 <https://github.com/python-semantic-release/python-semantic-release/commit/20603e53116d4f05e822784ce731b42e8cbc5d8f>)

  v7.15.6 (2021-06-08)

  🪲 Bug Fixes

    •   Update click and tomlkit (PR#339 <https://github.com/python-semantic-release/python-semantic-release/pull/339>, 947ea3b <https://github.com/python-semantic-release/python-semantic-release/commit/947ea3bc0750735941446cf4a87bae20e750ba12>)

  v7.15.5 (2021-05-26)

  🪲 Bug Fixes

    •   Pin tomlkit to 0.7.0 (2cd0db4 <https://github.com/python-semantic-release/python-semantic-release/commit/2cd0db4537bb9497b72eb496f6bab003070672ab>)

  v7.15.4 (2021-04-29)

  🪲 Bug Fixes

    •   Change log level of failed toml loading, closes #235 <https://github.com/python-semantic-release/python-semantic-release/issues/235> (24bb079 <https://github.com/python-semantic-release/python-semantic-release/commit/24bb079cbeff12e7043dd35dd0b5ae03192383bb>)

  v7.15.3 (2021-04-03)

  🪲 Bug Fixes

    •   Add venv to path in github action (583c5a1 <https://github.com/python-semantic-release/python-semantic-release/commit/583c5a13e40061fc544b82decfe27a6c34f6d265>)

  v7.15.2 (2021-04-03)

  🪲 Bug Fixes

    •   Run semantic-release in virtualenv in the github action, closes #331 <https://github.com/python-semantic-release/python-semantic-release/issues/331> (b508ea9 <https://github.com/python-semantic-release/python-semantic-release/commit/b508ea9f411c1cd4f722f929aab9f0efc0890448>)

    •   Set correct path for venv in action script (aac02b5 <https://github.com/python-semantic-release/python-semantic-release/commit/aac02b5a44a6959328d5879578aa3536bdf856c2>)

    •   Use absolute path for venv in github action (d4823b3 <https://github.com/python-semantic-release/python-semantic-release/commit/d4823b3b6b1fcd5c33b354f814643c9aaf85a06a>)

  📖 Documentation

    •   Clarify that HVCS should be lowercase, closes #330 <https://github.com/python-semantic-release/python-semantic-release/issues/330> (da0ab0c <https://github.com/python-semantic-release/python-semantic-release/commit/da0ab0c62c4ce2fa0d815e5558aeec1a1e23bc89>)

  v7.15.1 (2021-03-26)

  🪲 Bug Fixes

    •   Add support for setting build_command to "false", closes #328 <https://github.com/python-semantic-release/python-semantic-release/issues/328> (520cf1e <https://github.com/python-semantic-release/python-semantic-release/commit/520cf1eaa7816d0364407dbd17b5bc7c79806086>)

    •   Upgrade python-gitlab range, closes #329 <https://github.com/python-semantic-release/python-semantic-release/issues/329> (abfacc4 <https://github.com/python-semantic-release/python-semantic-release/commit/abfacc432300941d57488842e41c06d885637e6c>)

  📖 Documentation

    •   Add common options to documentation, closes #327 <https://github.com/python-semantic-release/python-semantic-release/issues/327> (20d79a5 <https://github.com/python-semantic-release/python-semantic-release/commit/20d79a51bffa26d40607c1b77d10912992279112>)

  v7.15.0 (2021-02-18)

  ✨ Features

    •   Allow the use of .pypirc for twine uploads (PR#325 <https://github.com/python-semantic-release/python-semantic-release/pull/325>, 6bc56b8 <https://github.com/python-semantic-release/python-semantic-release/commit/6bc56b8aa63069a25a828a2d1a9038ecd09b7d5d>)

  📖 Documentation

    •   Add documentation for releasing on a Jenkins instance (PR#324 <https://github.com/python-semantic-release/python-semantic-release/pull/324>, 77ad988 <https://github.com/python-semantic-release/python-semantic-release/commit/77ad988a2057be59e4559614a234d6871c06ee37>)

  v7.14.0 (2021-02-11)

  ✨ Features

    •   checks: Add support for Jenkins CI (PR#322 <https://github.com/python-semantic-release/python-semantic-release/pull/322>, 3e99855 <https://github.com/python-semantic-release/python-semantic-release/commit/3e99855c6bc72b3e9a572c58cc14e82ddeebfff8>)

  📖 Documentation

    •   Correct casing on proper nouns (PR#320 <https://github.com/python-semantic-release/python-semantic-release/pull/320>, d51b999 <https://github.com/python-semantic-release/python-semantic-release/commit/d51b999a245a4e56ff7a09d0495c75336f2f150d>)

    •   Correcting Python casing (PR#320 <https://github.com/python-semantic-release/python-semantic-release/pull/320>, d51b999 <https://github.com/python-semantic-release/python-semantic-release/commit/d51b999a245a4e56ff7a09d0495c75336f2f150d>)

    •   Correcting Semantic Versioning casing (PR#320 <https://github.com/python-semantic-release/python-semantic-release/pull/320>, d51b999 <https://github.com/python-semantic-release/python-semantic-release/commit/d51b999a245a4e56ff7a09d0495c75336f2f150d>)

  v7.13.2 (2021-01-29)

  🪲 Bug Fixes

    •   Crash when TOML has no PSR section (PR#319 <https://github.com/python-semantic-release/python-semantic-release/pull/319>, 5f8ab99 <https://github.com/python-semantic-release/python-semantic-release/commit/5f8ab99bf7254508f4b38fcddef2bdde8dd15a4c>)

    •   Fix crash when TOML has no PSR section (PR#319 <https://github.com/python-semantic-release/python-semantic-release/pull/319>, 5f8ab99 <https://github.com/python-semantic-release/python-semantic-release/commit/5f8ab99bf7254508f4b38fcddef2bdde8dd15a4c>)

  📖 Documentation

    •   Fix version_toml example for Poetry (PR#318 <https://github.com/python-semantic-release/python-semantic-release/pull/318>, 39acb68 <https://github.com/python-semantic-release/python-semantic-release/commit/39acb68bfffe8242040e476893639ba26fa0d6b5>)

  v7.13.1 (2021-01-26)

  🪲 Bug Fixes

    •   Use multiline version_pattern match in replace, closes #306 <https://github.com/python-semantic-release/python-semantic-release/issues/306> (PR#315 <https://github.com/python-semantic-release/python-semantic-release/pull/315>, 1a85af4 <https://github.com/python-semantic-release/python-semantic-release/commit/1a85af434325ce52e11b49895e115f7a936e417e>)

  v7.13.0 (2021-01-26)

  ✨ Features

    •   Support toml files for version declaration, closes #245 <https://github.com/python-semantic-release/python-semantic-release/issues/245>, #275 <https://github.com/python-semantic-release/python-semantic-release/issues/275> (PR#307 <https://github.com/python-semantic-release/python-semantic-release/pull/307>, 9b62a7e <https://github.com/python-semantic-release/python-semantic-release/commit/9b62a7e377378667e716384684a47cdf392093fa>)

  v7.12.0 (2021-01-25)

  ✨ Features

    •   github: Retry GitHub API requests on failure (PR#314 <https://github.com/python-semantic-release/python-semantic-release/pull/314>, ac241ed <https://github.com/python-semantic-release/python-semantic-release/commit/ac241edf4de39f4fc0ff561a749fa85caaf9e2ae>)

  🪲 Bug Fixes

    •   github: Add retries to github API requests (PR#314 <https://github.com/python-semantic-release/python-semantic-release/pull/314>, ac241ed <https://github.com/python-semantic-release/python-semantic-release/commit/ac241edf4de39f4fc0ff561a749fa85caaf9e2ae>)

  📖 Documentation

    •   actions: Pat must be passed to checkout step too, closes #311 <https://github.com/python-semantic-release/python-semantic-release/issues/311> (e2d8e47 <https://github.com/python-semantic-release/python-semantic-release/commit/e2d8e47d2b02860881381318dcc088e150c0fcde>)

  v7.11.0 (2021-01-08)

  ✨ Features

    •   print-version: Add print-version command to output version (512e3d9 <https://github.com/python-semantic-release/python-semantic-release/commit/512e3d92706055bdf8d08b7c82927d3530183079>)

  🪲 Bug Fixes

    •   Add dot to --define option help (eb4107d <https://github.com/python-semantic-release/python-semantic-release/commit/eb4107d2efdf8c885c8ae35f48f1b908d1fced32>)

    •   Avoid Unknown bump level 0 message (8ab624c <https://github.com/python-semantic-release/python-semantic-release/commit/8ab624cf3508b57a9656a0a212bfee59379d6f8b>)

    •   actions: Fix github actions with new main location (6666672 <https://github.com/python-semantic-release/python-semantic-release/commit/6666672d3d97ab7cdf47badfa3663f1a69c2dbdf>)

  ⚙️ Build System

    •   Add __main__.py magic file (e93f36a <https://github.com/python-semantic-release/python-semantic-release/commit/e93f36a7a10e48afb42c1dc3d860a5e2a07cf353>)

  v7.10.0 (2021-01-08)

  ✨ Features

    •   build: Allow falsy values for build_command to disable build step (c07a440 <https://github.com/python-semantic-release/python-semantic-release/commit/c07a440f2dfc45a2ad8f7c454aaac180c4651f70>)

  📖 Documentation

    •   Fix incorrect reference syntax (42027f0 <https://github.com/python-semantic-release/python-semantic-release/commit/42027f0d2bb64f4c9eaec65112bf7b6f67568e60>)

    •   Rewrite getting started page (97a9046 <https://github.com/python-semantic-release/python-semantic-release/commit/97a90463872502d1207890ae1d9dd008b1834385>)

  v7.9.0 (2020-12-21)

  ✨ Features

    •   hvcs: Add hvcs_domain config option, closes #277 <https://github.com/python-semantic-release/python-semantic-release/issues/277> (ab3061a <https://github.com/python-semantic-release/python-semantic-release/commit/ab3061ae93c49d71afca043b67b361e2eb2919e6>)

  🪲 Bug Fixes

    •   history: Coerce version to string (PR#298 <https://github.com/python-semantic-release/python-semantic-release/pull/298>, d4cdc3d <https://github.com/python-semantic-release/python-semantic-release/commit/d4cdc3d3cd2d93f2a78f485e3ea107ac816c7d00>)

    •   history: Require semver >= 2.10 (5087e54 <https://github.com/python-semantic-release/python-semantic-release/commit/5087e549399648cf2e23339a037b33ca8b62d954>)

  v7.8.2 (2020-12-19)

  ✨ Features

    •   repository: Add to settings artifact repository (f4ef373 <https://github.com/python-semantic-release/python-semantic-release/commit/f4ef3733b948282fba5a832c5c0af134609b26d2>)

  🪲 Bug Fixes

    •   cli: Skip remove_dist where not needed (04817d4 <https://github.com/python-semantic-release/python-semantic-release/commit/04817d4ecfc693195e28c80455bfbb127485f36b>)

  v7.8.1 (2020-12-18)

  🪲 Bug Fixes

    •   Filenames with unknown mimetype are now properly uploaded to github release (f3ece78 <https://github.com/python-semantic-release/python-semantic-release/commit/f3ece78b2913e70f6b99907b192a1e92bbfd6b77>)

    •   logs: Fix TypeError when enabling debug logs (2591a94 <https://github.com/python-semantic-release/python-semantic-release/commit/2591a94115114c4a91a48f5b10b3954f6ac932a1>)

  v7.8.0 (2020-12-18)

  ✨ Features

    •   Add upload_to_pypi_glob_patterns option (42305ed <https://github.com/python-semantic-release/python-semantic-release/commit/42305ed499ca08c819c4e7e65fcfbae913b8e6e1>)

  🪲 Bug Fixes

    •   changelog: Use "issues" link vs "pull" (93e48c9 <https://github.com/python-semantic-release/python-semantic-release/commit/93e48c992cb8b763f430ecbb0b7f9c3ca00036e4>)

    •   netrc: Prefer using token defined in GH_TOKEN instead of .netrc file (3af32a7 <https://github.com/python-semantic-release/python-semantic-release/commit/3af32a738f2f2841fd75ec961a8f49a0b1c387cf>)

  v7.7.0 (2020-12-12)

  ✨ Features

    •   changelog: Add PR links in markdown (PR#282 <https://github.com/python-semantic-release/python-semantic-release/pull/282>, 0448f6c <https://github.com/python-semantic-release/python-semantic-release/commit/0448f6c350bbbf239a81fe13dc5f45761efa7673>)

  v7.6.0 (2020-12-06)

  ✨ Features

    •   Add major_on_zero option (d324154 <https://github.com/python-semantic-release/python-semantic-release/commit/d3241540e7640af911eb24c71e66468feebb0d46>)

  📖 Documentation

    •   Add documentation for option major_on_zero (2e8b26e <https://github.com/python-semantic-release/python-semantic-release/commit/2e8b26e4ee0316a2cf2a93c09c783024fcd6b3ba>)

  v7.5.0 (2020-12-04)

  ✨ Features

    •   logs: Include scope in changelogs (PR#281 <https://github.com/python-semantic-release/python-semantic-release/pull/281>, 21c96b6 <https://github.com/python-semantic-release/python-semantic-release/commit/21c96b688cc44cc6f45af962ffe6d1f759783f37>)

  v7.4.1 (2020-12-04)

  🪲 Bug Fixes

    •   Add "changelog_capitalize" to flags, closes #278 <https://github.com/python-semantic-release/python-semantic-release/issues/278> (PR#279 <https://github.com/python-semantic-release/python-semantic-release/pull/279>, 37716df <https://github.com/python-semantic-release/python-semantic-release/commit/37716dfa78eb3f848f57a5100d01d93f5aafc0bf>)

  v7.4.0 (2020-11-24)

  ✨ Features

    •   Add changelog_capitalize configuration, closes #260 <https://github.com/python-semantic-release/python-semantic-release/issues/260> (7cacca1 <https://github.com/python-semantic-release/python-semantic-release/commit/7cacca1eb436a7166ba8faf643b53c42bc32a6a7>)

  📖 Documentation

    •   Fix broken internal references (PR#270 <https://github.com/python-semantic-release/python-semantic-release/pull/270>, da20b9b <https://github.com/python-semantic-release/python-semantic-release/commit/da20b9bdd3c7c87809c25ccb2a5993a7ea209a22>)

    •   Update links to Github docs (PR#268 <https://github.com/python-semantic-release/python-semantic-release/pull/268>, c53162e <https://github.com/python-semantic-release/python-semantic-release/commit/c53162e366304082a3bd5d143b0401da6a16a263>)

  v7.3.0 (2020-09-28)

  ✨ Features

    •   Generate changelog.md file (PR#266 <https://github.com/python-semantic-release/python-semantic-release/pull/266>, 2587dfe <https://github.com/python-semantic-release/python-semantic-release/commit/2587dfed71338ec6c816f58cdf0882382c533598>)

  📖 Documentation

    •   Fix docstring (5a5e2cf <https://github.com/python-semantic-release/python-semantic-release/commit/5a5e2cfb5e6653fb2e95e6e23e56559953b2c2b4>)

  v7.2.5 (2020-09-16)

  🪲 Bug Fixes

    •   Add required to inputs in action metadata (PR#264 <https://github.com/python-semantic-release/python-semantic-release/pull/264>, e76b255 <https://github.com/python-semantic-release/python-semantic-release/commit/e76b255cf7d3d156e3314fc28c54d63fa126e973>)

  v7.2.4 (2020-09-14)

  🪲 Bug Fixes

    •   Use range for toml dependency, closes #241 <https://github.com/python-semantic-release/python-semantic-release/issues/241> (45707e1 <https://github.com/python-semantic-release/python-semantic-release/commit/45707e1b7dcab48103a33de9d7f9fdb5a34dae4a>)

  v7.2.3 (2020-09-12)

  🪲 Bug Fixes

    •   Support multiline version_pattern matching by default (82f7849 <https://github.com/python-semantic-release/python-semantic-release/commit/82f7849dcf29ba658e0cb3b5d21369af8bf3c16f>)

  📖 Documentation

    •   Create 'getting started' instructions (PR#256 <https://github.com/python-semantic-release/python-semantic-release/pull/256>, 5f4d000 <https://github.com/python-semantic-release/python-semantic-release/commit/5f4d000c3f153d1d23128acf577e389ae879466e>)

    •   Link to getting started guide in README (f490e01 <https://github.com/python-semantic-release/python-semantic-release/commit/f490e0194fa818db4d38c185bc5e6245bfde546b>)

  v7.2.2 (2020-07-26)

  🪲 Bug Fixes

    •   changelog: Send changelog to stdout, closes #250 <https://github.com/python-semantic-release/python-semantic-release/issues/250> (87e2bb8 <https://github.com/python-semantic-release/python-semantic-release/commit/87e2bb881387ff3ac245ab9923347a5a616e197b>)

  📖 Documentation

    •   Add quotation marks to the pip commands in CONTRIBUTING.rst (PR#253 <https://github.com/python-semantic-release/python-semantic-release/pull/253>, e20fa43 <https://github.com/python-semantic-release/python-semantic-release/commit/e20fa43098c06f5f585c81b9cd7e287dcce3fb5d>)

  v7.2.1 (2020-06-29)

  🪲 Bug Fixes

    •   Commit all files with bumped versions (PR#249 <https://github.com/python-semantic-release/python-semantic-release/pull/249>, b3a1766 <https://github.com/python-semantic-release/python-semantic-release/commit/b3a1766be7edb7d2eb76f2726d35ab8298688b3b>)

  📖 Documentation

    •   Give example of multiple build commands (PR#248 <https://github.com/python-semantic-release/python-semantic-release/pull/248>, 65f1ffc <https://github.com/python-semantic-release/python-semantic-release/commit/65f1ffcc6cac3bf382f4b821ff2be59d04f9f867>)

  v7.2.0 (2020-06-15)

  ✨ Features

    •   Bump versions in multiple files, closes #175 <https://github.com/python-semantic-release/python-semantic-release/issues/175> (PR#246 <https://github.com/python-semantic-release/python-semantic-release/pull/246>, 0ba2c47 <https://github.com/python-semantic-release/python-semantic-release/commit/0ba2c473c6e44cc326b3299b6ea3ddde833bdb37>)

  v7.1.1 (2020-05-28)

  🪲 Bug Fixes

    •   changelog: Swap sha and message in table changelog (6741370 <https://github.com/python-semantic-release/python-semantic-release/commit/6741370ab09b1706ff6e19b9fbe57b4bddefc70d>)

  v7.1.0 (2020-05-24)

  ✨ Features

    •   changelog: Add changelog_table component, closes #237 <https://github.com/python-semantic-release/python-semantic-release/issues/237> (PR#242 <https://github.com/python-semantic-release/python-semantic-release/pull/242>, fe6a7e7 <https://github.com/python-semantic-release/python-semantic-release/commit/fe6a7e7fa014ffb827a1430dbcc10d1fc84c886b>)

  v7.0.0 (2020-05-22)

  ✨ Features

    •   Pass changelog_sections to components (PR#240 <https://github.com/python-semantic-release/python-semantic-release/pull/240>, 3e17a98 <https://github.com/python-semantic-release/python-semantic-release/commit/3e17a98d7fa8468868a87e62651ac2c010067711>)

    •   changelog: Add changelog components (PR#240 <https://github.com/python-semantic-release/python-semantic-release/pull/240>, 3e17a98 <https://github.com/python-semantic-release/python-semantic-release/commit/3e17a98d7fa8468868a87e62651ac2c010067711>)

  📖 Documentation

    •   Add conda-forge badge (e9536bb <https://github.com/python-semantic-release/python-semantic-release/commit/e9536bbe119c9e3b90c61130c02468e0e1f14141>)

    •   Add documentation for changelog_components (PR#240 <https://github.com/python-semantic-release/python-semantic-release/pull/240>, 3e17a98 <https://github.com/python-semantic-release/python-semantic-release/commit/3e17a98d7fa8468868a87e62651ac2c010067711>)

  💥 BREAKING CHANGES

    •   changelog: The compare_url option has been removed in favor of using changelog_components. This functionality is now available as the semantic_release.changelog.compare_url component.

  v6.4.1 (2020-05-15)

  🪲 Bug Fixes

    •   Convert \r\n to \n in commit messages, closes #239 <https://github.com/python-semantic-release/python-semantic-release/issues/239> (34acbbc <https://github.com/python-semantic-release/python-semantic-release/commit/34acbbcd25320a9d18dcd1a4f43e1ce1837b2c9f>)

  v6.4.0 (2020-05-15)

  ✨ Features

    •   history: Create emoji parser (PR#238 <https://github.com/python-semantic-release/python-semantic-release/pull/238>, 2e1c50a <https://github.com/python-semantic-release/python-semantic-release/commit/2e1c50a865628b372f48945a039a3edb38a7cdf0>)

  🪲 Bug Fixes

    •   Add emojis to default changelog_sections (PR#238 <https://github.com/python-semantic-release/python-semantic-release/pull/238>, 2e1c50a <https://github.com/python-semantic-release/python-semantic-release/commit/2e1c50a865628b372f48945a039a3edb38a7cdf0>)

    •   Include all parsed types in changelog (PR#238 <https://github.com/python-semantic-release/python-semantic-release/pull/238>, 2e1c50a <https://github.com/python-semantic-release/python-semantic-release/commit/2e1c50a865628b372f48945a039a3edb38a7cdf0>)

  📖 Documentation

    •   Add documentation for emoji parser (PR#238 <https://github.com/python-semantic-release/python-semantic-release/pull/238>, 2e1c50a <https://github.com/python-semantic-release/python-semantic-release/commit/2e1c50a865628b372f48945a039a3edb38a7cdf0>)

  ♻️ Refactoring

    •   history: Get breaking changes in parser (PR#238 <https://github.com/python-semantic-release/python-semantic-release/pull/238>, 2e1c50a <https://github.com/python-semantic-release/python-semantic-release/commit/2e1c50a865628b372f48945a039a3edb38a7cdf0>)

  v6.3.1 (2020-05-11)

  🪲 Bug Fixes

    •   Use getboolean for commit_version_number, closes #186 <https://github.com/python-semantic-release/python-semantic-release/issues/186> (a60e0b4 <https://github.com/python-semantic-release/python-semantic-release/commit/a60e0b4e3cadf310c3e0ad67ebeb4e69d0ee50cb>)

  v6.3.0 (2020-05-09)

  ✨ Features

    •   history: Support linking compare page in changelog, closes #218 <https://github.com/python-semantic-release/python-semantic-release/issues/218> (79a8e02 <https://github.com/python-semantic-release/python-semantic-release/commit/79a8e02df82fbc2acecaad9e9ff7368e61df3e54>)

  📖 Documentation

    •   Document compare_link option (e52c355 <https://github.com/python-semantic-release/python-semantic-release/commit/e52c355c0d742ddd2cfa65d42888296942e5bec5>)

    •   Rewrite commit-log-parsing.rst (4c70f4f <https://github.com/python-semantic-release/python-semantic-release/commit/4c70f4f2aa3343c966d1b7ab8566fcc782242ab9>)

  v6.2.0 (2020-05-02)

  ✨ Features

    •   history: Check all paragraphs for breaking changes, closes #200 <https://github.com/python-semantic-release/python-semantic-release/issues/200> (fec08f0 <https://github.com/python-semantic-release/python-semantic-release/commit/fec08f0dbd7ae15f95ca9c41a02c9fe6d448ede0>)

  📖 Documentation

    •   Add = to verbosity option, closes #227 <https://github.com/python-semantic-release/python-semantic-release/issues/227> (a0f4c9c <https://github.com/python-semantic-release/python-semantic-release/commit/a0f4c9cd397fcb98f880097319c08160adb3c3e6>)

    •   Use references where possible, closes #221 <https://github.com/python-semantic-release/python-semantic-release/issues/221> (f38e5d4 <https://github.com/python-semantic-release/python-semantic-release/commit/f38e5d4a1597cddb69ce47a4d79b8774e796bf41>)

  v6.1.0 (2020-04-26)

  ✨ Features

    •   actions: Support PYPI_TOKEN on GitHub Actions (df2c080 <https://github.com/python-semantic-release/python-semantic-release/commit/df2c0806f0a92186e914cfc8cc992171d74422df>)

    •   pypi: Support easier use of API tokens, closes #213 <https://github.com/python-semantic-release/python-semantic-release/issues/213> (bac135c <https://github.com/python-semantic-release/python-semantic-release/commit/bac135c0ae7a6053ecfc7cdf2942c3c89640debf>)

  📖 Documentation

    •   Add documentation for PYPI_TOKEN (a8263a0 <https://github.com/python-semantic-release/python-semantic-release/commit/a8263a066177d1d42f2844e4cb42a76a23588500>)

  v6.0.1 (2020-04-15)

  🪲 Bug Fixes

    •   hvcs: Convert get_hvcs to use LoggedFunction (3084249 <https://github.com/python-semantic-release/python-semantic-release/commit/308424933fd3375ca3730d9eaf8abbad2435830b>)

  v6.0.0 (2020-04-15)

  📖 Documentation

    •   Create Read the Docs config file (aa5a1b7 <https://github.com/python-semantic-release/python-semantic-release/commit/aa5a1b700a1c461c81c6434686cb6f0504c4bece>)

    •   Include README.rst in index.rst (8673a9d <https://github.com/python-semantic-release/python-semantic-release/commit/8673a9d92a9bf348bb3409e002a830741396c8ca>)

    •   Move action.rst into main documentation (509ccaf <https://github.com/python-semantic-release/python-semantic-release/commit/509ccaf307a0998eced69ad9fee1807132babe28>)

    •   Rewrite README.rst (e049772 <https://github.com/python-semantic-release/python-semantic-release/commit/e049772cf14cdd49538cf357db467f0bf3fe9587>)

    •   Rewrite troubleshooting page (0285de2 <https://github.com/python-semantic-release/python-semantic-release/commit/0285de215a8dac3fcc9a51f555fa45d476a56dff>)

  ♻️ Refactoring

    •   debug: Use logging and click_log instead of ndebug (15b1f65 <https://github.com/python-semantic-release/python-semantic-release/commit/15b1f650f29761e1ab2a91b767cbff79b2057a4c>)

  💥 BREAKING CHANGES

    •   debug: debug="*" no longer has an effect, instead use --verbosity DEBUG.

  v5.2.0 (2020-04-09)

  ✨ Features

    •   github: Add tag as default release name (2997908 <https://github.com/python-semantic-release/python-semantic-release/commit/2997908f80f4fcec56917d237a079b961a06f990>)

  📖 Documentation

    •   Automate API docs (7d4fea2 <https://github.com/python-semantic-release/python-semantic-release/commit/7d4fea266cc75007de51609131eb6d1e324da608>)

  v5.1.0 (2020-04-04)

  ✨ Features

    •   history: Allow customizing changelog_sections (PR#207 <https://github.com/python-semantic-release/python-semantic-release/pull/207>, d5803d5 <https://github.com/python-semantic-release/python-semantic-release/commit/d5803d5c1668d86482a31ac0853bac7ecfdc63bc>)

  📖 Documentation

    •   Improve formatting of configuration page (9a8e22e <https://github.com/python-semantic-release/python-semantic-release/commit/9a8e22e838d7dbf3bfd941397c3b39560aca6451>)

    •   Improve formatting of envvars page (b376a56 <https://github.com/python-semantic-release/python-semantic-release/commit/b376a567bfd407a507ce0752614b0ca75a0f2973>)

    •   Update index.rst (b27c26c <https://github.com/python-semantic-release/python-semantic-release/commit/b27c26c66e7e41843ab29076f7e724908091b46e>)

  v5.0.3 (2020-03-26)

  🪲 Bug Fixes

    •   Bump dependencies and fix Windows issues on Development (PR#173 <https://github.com/python-semantic-release/python-semantic-release/pull/173>, 0a6f8c3 <https://github.com/python-semantic-release/python-semantic-release/commit/0a6f8c3842b05f5f424dad5ce1fa5e3823c7e688>)

    •   Missing mime types on Windows (PR#173 <https://github.com/python-semantic-release/python-semantic-release/pull/173>, 0a6f8c3 <https://github.com/python-semantic-release/python-semantic-release/commit/0a6f8c3842b05f5f424dad5ce1fa5e3823c7e688>)

  v5.0.2 (2020-03-22)

  🪲 Bug Fixes

    •   history: Leave case of other characters unchanged (96ba94c <https://github.com/python-semantic-release/python-semantic-release/commit/96ba94c4b4593997343ec61ecb6c823c1494d0e2>)

  v5.0.1 (2020-03-22)

  🪲 Bug Fixes

    •   Make action use current version of semantic-release (123984d <https://github.com/python-semantic-release/python-semantic-release/commit/123984d735181c622f3d99088a1ad91321192a11>)

  v5.0.0 (2020-03-22)

  ✨ Features

    •   build: Allow config setting for build command, closes #188 <https://github.com/python-semantic-release/python-semantic-release/issues/188> (PR#195 <https://github.com/python-semantic-release/python-semantic-release/pull/195>, 740f4bd <https://github.com/python-semantic-release/python-semantic-release/commit/740f4bdb26569362acfc80f7e862fc2c750a46dd>)

  🪲 Bug Fixes

    •   Rename default of build_command config (d5db22f <https://github.com/python-semantic-release/python-semantic-release/commit/d5db22f9f7acd05d20fd60a8b4b5a35d4bbfabb8>)

  📖 Documentation

    •   pypi: Update docstrings in pypi.py (6502d44 <https://github.com/python-semantic-release/python-semantic-release/commit/6502d448fa65e5dc100e32595e83fff6f62a881a>)

  💥 BREAKING CHANGES

    •   build: Previously the build_commands configuration variable set the types of bundles sent to python setup.py. It has been replaced by the configuration variable build_command which takes the full command e.g. python setup.py sdist or poetry build.

  v4.11.0 (2020-03-22)

  ✨ Features

    •   actions: Create GitHub Action (350245d <https://github.com/python-semantic-release/python-semantic-release/commit/350245dbfb07ed6a1db017b1d9d1072b368b1497>)

  📖 Documentation

    •   Make AUTHORS.rst dynamic (db2e076 <https://github.com/python-semantic-release/python-semantic-release/commit/db2e0762f3189d0f1a6ba29aad32bdefb7e0187f>)

    •   readme: Fix minor typo (c22f69f <https://github.com/python-semantic-release/python-semantic-release/commit/c22f69f62a215ff65e1ab6dcaa8e7e9662692e64>)

  v4.10.0 (2020-03-03)

  ✨ Features

    •   Make commit message configurable (PR#184 <https://github.com/python-semantic-release/python-semantic-release/pull/184>, eb0762c <https://github.com/python-semantic-release/python-semantic-release/commit/eb0762ca9fea5cecd5c7b182504912a629be473b>)

  v4.9.0 (2020-03-02)

  ✨ Features

    •   pypi: Add build_commands config (22146ea <https://github.com/python-semantic-release/python-semantic-release/commit/22146ea4b94466a90d60b94db4cc65f46da19197>)

  🪲 Bug Fixes

    •   pypi: Change bdist_wheels to bdist_wheel (c4db509 <https://github.com/python-semantic-release/python-semantic-release/commit/c4db50926c03f3d551c8331932c567c7bdaf4f3d>)

  v4.8.0 (2020-02-28)

  ✨ Features

    •   git: Add a new config for commit author (aa2c22c <https://github.com/python-semantic-release/python-semantic-release/commit/aa2c22c469448fe57f02bea67a02f998ce519ac3>)

  v4.7.1 (2020-02-28)

  🪲 Bug Fixes

    •   Repair parsing of remotes in the gitlab ci format, closes #181 <https://github.com/python-semantic-release/python-semantic-release/issues/181> (0fddbe2 <https://github.com/python-semantic-release/python-semantic-release/commit/0fddbe2fb70d24c09ceddb789a159162a45942dc>)

  v4.7.0 (2020-02-28)

  ✨ Features

    •   Upload distribution files to GitHub Releases (PR#177 <https://github.com/python-semantic-release/python-semantic-release/pull/177>, e427658 <https://github.com/python-semantic-release/python-semantic-release/commit/e427658e33abf518191498c3142a0f18d3150e07>)

    •   github: Upload dists to release (PR#177 <https://github.com/python-semantic-release/python-semantic-release/pull/177>, e427658 <https://github.com/python-semantic-release/python-semantic-release/commit/e427658e33abf518191498c3142a0f18d3150e07>)

  🪲 Bug Fixes

    •   Post changelog after PyPI upload (PR#177 <https://github.com/python-semantic-release/python-semantic-release/pull/177>, e427658 <https://github.com/python-semantic-release/python-semantic-release/commit/e427658e33abf518191498c3142a0f18d3150e07>)

    •   Support repository owner names containing dots, closes #179 <https://github.com/python-semantic-release/python-semantic-release/issues/179> (a6c4da4 <https://github.com/python-semantic-release/python-semantic-release/commit/a6c4da4c0e6bd8a37f64544f7813fa027f5054ed>)

    •   github: Fix upload of .whl files (PR#177 <https://github.com/python-semantic-release/python-semantic-release/pull/177>, e427658 <https://github.com/python-semantic-release/python-semantic-release/commit/e427658e33abf518191498c3142a0f18d3150e07>)

    •   github: Use application/octet-stream for .whl files (90a7e47 <https://github.com/python-semantic-release/python-semantic-release/commit/90a7e476a04d26babc88002e9035cad2ed485b07>)

  📖 Documentation

    •   Document upload_to_release config option (PR#177 <https://github.com/python-semantic-release/python-semantic-release/pull/177>, e427658 <https://github.com/python-semantic-release/python-semantic-release/commit/e427658e33abf518191498c3142a0f18d3150e07>)

  v4.6.0 (2020-02-19)

  ✨ Features

    •   history: Capitalize changelog messages (1a8e306 <https://github.com/python-semantic-release/python-semantic-release/commit/1a8e3060b8f6d6362c27903dcfc69d17db5f1d36>)

  🪲 Bug Fixes

    •   Add more debug statements in logs (bc931ec <https://github.com/python-semantic-release/python-semantic-release/commit/bc931ec46795fde4c1ccee004eec83bf73d5de7a>)

    •   Only overwrite with patch if bump is None, closes #159 <https://github.com/python-semantic-release/python-semantic-release/issues/159> (1daa4e2 <https://github.com/python-semantic-release/python-semantic-release/commit/1daa4e23ec2dd40c6b490849276524264787e24e>)

  v4.5.1 (2020-02-16)

  🪲 Bug Fixes

    •   github: Send token in request header, closes #167 <https://github.com/python-semantic-release/python-semantic-release/issues/167> (be9972a <https://github.com/python-semantic-release/python-semantic-release/commit/be9972a7b1fb183f738fb31bd370adb30281e4d5>)

  📖 Documentation

    •   Add note about automatic releases in readme (e606e75 <https://github.com/python-semantic-release/python-semantic-release/commit/e606e7583a30167cf7679c6bcada2f9e768b3abe>)

    •   Fix broken list in readme (7aa572b <https://github.com/python-semantic-release/python-semantic-release/commit/7aa572b2a323ddbc69686309226395f40c52b469>)

    •   Update readme and getting started docs (07b3208 <https://github.com/python-semantic-release/python-semantic-release/commit/07b3208ff64301e544c4fdcb48314e49078fc479>)

  v4.5.0 (2020-02-08)

  ✨ Features

    •   history: Enable colon defined version, closes #165 <https://github.com/python-semantic-release/python-semantic-release/issues/165> (7837f50 <https://github.com/python-semantic-release/python-semantic-release/commit/7837f5036269328ef29996b9ea63cccd5a6bc2d5>)

  🪲 Bug Fixes

    •   Remove erroneous submodule (762bfda <https://github.com/python-semantic-release/python-semantic-release/commit/762bfda728c266b8cd14671d8da9298fc99c63fb>)

    •   cli: --noop flag works when before command, closes #73 <https://github.com/python-semantic-release/python-semantic-release/issues/73> (4fcc781 <https://github.com/python-semantic-release/python-semantic-release/commit/4fcc781d1a3f9235db552f0f4431c9f5e638d298>)

  v4.4.1 (2020-01-18)

  🪲 Bug Fixes

    •   Add quotes around twine arguments, closes #163 <https://github.com/python-semantic-release/python-semantic-release/issues/163> (46a83a9 <https://github.com/python-semantic-release/python-semantic-release/commit/46a83a94b17c09d8f686c3ae7b199d7fd0e0e5e5>)

  v4.4.0 (2020-01-17)

  ✨ Features

    •   parser: Add support for exclamation point for breaking changes, closes #156 <https://github.com/python-semantic-release/python-semantic-release/issues/156> (a4f8a10 <https://github.com/python-semantic-release/python-semantic-release/commit/a4f8a10afcc358a8fbef83be2041129480350be2>)

    •   parser: Make BREAKING-CHANGE synonymous with BREAKING CHANGE (beedccf <https://github.com/python-semantic-release/python-semantic-release/commit/beedccfddfb360aeebef595342ee980446012ec7>)

  🪲 Bug Fixes

    •   github: Add check for GITHUB_ACTOR for git push (PR#162 <https://github.com/python-semantic-release/python-semantic-release/pull/162>, c41e9bb <https://github.com/python-semantic-release/python-semantic-release/commit/c41e9bb986d01b92d58419cbdc88489d630a11f1>)

  v4.3.4 (2019-12-17)

  🪲 Bug Fixes

    •   Fallback to whole log if correct tag is not available, closes #51 <https://github.com/python-semantic-release/python-semantic-release/issues/51> (PR#157 <https://github.com/python-semantic-release/python-semantic-release/pull/157>, 252bffd <https://github.com/python-semantic-release/python-semantic-release/commit/252bffd3be7b6dfcfdb384d24cb1cd83d990fc9a>)

  v4.3.3 (2019-11-06)

  🪲 Bug Fixes

    •   Instead of requiring click 7.0, looks like all tests will pass with at least 2.0. (PR#155 <https://github.com/python-semantic-release/python-semantic-release/pull/155>, f07c7f6 <https://github.com/python-semantic-release/python-semantic-release/commit/f07c7f653be1c018e443f071d9a196d9293e9521>)

    •   Set version of click to >=2.0,<8.0. (PR#155 <https://github.com/python-semantic-release/python-semantic-release/pull/155>, f07c7f6 <https://github.com/python-semantic-release/python-semantic-release/commit/f07c7f653be1c018e443f071d9a196d9293e9521>)

    •   Upgrade to click 7.0, closes #117 <https://github.com/python-semantic-release/python-semantic-release/issues/117> (PR#155 <https://github.com/python-semantic-release/python-semantic-release/pull/155>, f07c7f6 <https://github.com/python-semantic-release/python-semantic-release/commit/f07c7f653be1c018e443f071d9a196d9293e9521>)

  v4.3.2 (2019-10-05)

  🪲 Bug Fixes

    •   Update regex to get repository owner and name for project with dots, closes #151 <https://github.com/python-semantic-release/python-semantic-release/issues/151> (2778e31 <https://github.com/python-semantic-release/python-semantic-release/commit/2778e316a0c0aa931b1012cb3862d04659c05e73>)

  v4.3.1 (2019-09-29)

  🪲 Bug Fixes

    •   Support repo urls without git terminator (700e9f1 <https://github.com/python-semantic-release/python-semantic-release/commit/700e9f18dafde1833f482272a72bb80b54d56bb3>)

  v4.3.0 (2019-09-06)

  ✨ Features

    •   Add the possibility to load configuration from pyproject.toml (35f8bfe <https://github.com/python-semantic-release/python-semantic-release/commit/35f8bfef443c8b69560c918f4b13bc766fb3daa2>)

    •   Allow the override of configuration options from cli, closes #119 <https://github.com/python-semantic-release/python-semantic-release/issues/119> (f0ac82f <https://github.com/python-semantic-release/python-semantic-release/commit/f0ac82fe59eb59a768a73a1bf2ea934b9d448c58>)

    •   Allow users to get version from tag and write/commit bump to file, closes #104 <https://github.com/python-semantic-release/python-semantic-release/issues/104> (1f9fe1c <https://github.com/python-semantic-release/python-semantic-release/commit/1f9fe1cc7666d47cc0c348c4705b63c39bf10ecc>)

    •   Make the vcs functionalities work with gitlab, closes #121 <https://github.com/python-semantic-release/python-semantic-release/issues/121> (82d555d <https://github.com/python-semantic-release/python-semantic-release/commit/82d555d45b9d9e295ef3f9546a6ca2a38ca4522e>)

  🪲 Bug Fixes

    •   Manage subgroups in git remote url, closes #139 <https://github.com/python-semantic-release/python-semantic-release/issues/139>, #140 <https://github.com/python-semantic-release/python-semantic-release/issues/140> (4b11875 <https://github.com/python-semantic-release/python-semantic-release/commit/4b118754729094e330389712cf863e1c6cefee69>)

    •   Update list of commit types to include build, ci and perf, closes #145 <https://github.com/python-semantic-release/python-semantic-release/issues/145> (41ea12f <https://github.com/python-semantic-release/python-semantic-release/commit/41ea12fa91f97c0046178806bce3be57c3bc2308>)

  v4.2.0 (2019-08-05)

  ✨ Features

    •   Add configuration to customize handling of dists, closes #115 <https://github.com/python-semantic-release/python-semantic-release/issues/115> (2af6f41 <https://github.com/python-semantic-release/python-semantic-release/commit/2af6f41b21205bdd192514a434fca2feba17725a>)

    •   Add support for configuring branch, closes #43 <https://github.com/python-semantic-release/python-semantic-release/issues/43> (14abb05 <https://github.com/python-semantic-release/python-semantic-release/commit/14abb05e7f878e88002f896812d66b4ea5c219d4>)

    •   Add support for showing unreleased changelog, closes #134 <https://github.com/python-semantic-release/python-semantic-release/issues/134> (41ef794 <https://github.com/python-semantic-release/python-semantic-release/commit/41ef7947ad8a07392c96c7540980476e989c1d83>)

  🪲 Bug Fixes

    •   Add commit hash when generating breaking changes, closes #120 <https://github.com/python-semantic-release/python-semantic-release/issues/120> (0c74faf <https://github.com/python-semantic-release/python-semantic-release/commit/0c74fafdfa81cf2e13db8f4dcf0a6f7347552504>)

    •   Kept setting new version for tag source (0e24a56 <https://github.com/python-semantic-release/python-semantic-release/commit/0e24a5633f8f94b48da97b011634d4f9d84f7b4b>)

    •   Remove deletion of build folder, closes #115 <https://github.com/python-semantic-release/python-semantic-release/issues/115> (b45703d <https://github.com/python-semantic-release/python-semantic-release/commit/b45703dad38c29b28575060b21e5fb0f8482c6b1>)

    •   Updated the tag tests (3303eef <https://github.com/python-semantic-release/python-semantic-release/commit/3303eefa49a0474bbd85df10ae186ccbf9090ec1>)

    •   Upgrade click to 7.0 (2c5dd80 <https://github.com/python-semantic-release/python-semantic-release/commit/2c5dd809b84c2157a5e6cdcc773c43ec864f0328>)

  v4.1.2 (2019-08-04)

  🪲 Bug Fixes

    •   Correct isort build fail (0037210 <https://github.com/python-semantic-release/python-semantic-release/commit/00372100b527ff9308d9e43fe5c65cdf179dc4dc>)

    •   Make sure the history only breaks loop for version commit, closes #135 <https://github.com/python-semantic-release/python-semantic-release/issues/135> (5dc6cfc <https://github.com/python-semantic-release/python-semantic-release/commit/5dc6cfc634254f09997bb3cb0f17abd296e2c01f>)

    •   vcs: Allow cli to be run from subdirectory (fb7bb14 <https://github.com/python-semantic-release/python-semantic-release/commit/fb7bb14300e483626464795b8ff4f033a194cf6f>)

  📖 Documentation

    •   circleci: Point badge to master branch (9c7302e <https://github.com/python-semantic-release/python-semantic-release/commit/9c7302e184a1bd88f39b3039691b55cd77f0bb07>)

  v4.1.1 (2019-02-15)

  📖 Documentation

    •   Correct usage of changelog (f4f59b0 <https://github.com/python-semantic-release/python-semantic-release/commit/f4f59b08c73700c6ee04930221bfcb1355cbc48d>)

    •   Debug usage and related (f08e594 <https://github.com/python-semantic-release/python-semantic-release/commit/f08e5943a9876f2d17a7c02f468720995c7d9ffd>)

    •   Describing the commands (b6fa04d <https://github.com/python-semantic-release/python-semantic-release/commit/b6fa04db3044525a1ee1b5952fb175a706842238>)

    •   Update url for commit guidelinesThe guidelines can now be found in theDEVELOPERS.md in angular. (90c1b21 <https://github.com/python-semantic-release/python-semantic-release/commit/90c1b217f86263301b91d19d641c7b348e37d960>)

  v4.1.0 (2019-01-31)

  ✨ Features

    •   ci_checks: Add support for bitbucket (9fc120d <https://github.com/python-semantic-release/python-semantic-release/commit/9fc120d1a7e4acbbca609628e72651685108b364>)

  🪲 Bug Fixes

    •   Initialize git Repo from current folder (c7415e6 <https://github.com/python-semantic-release/python-semantic-release/commit/c7415e634c0affbe6396e0aa2bafe7c1b3368914>)

    •   Maintain version variable formatting on bump (PR#103 <https://github.com/python-semantic-release/python-semantic-release/pull/103>, bf63156 <https://github.com/python-semantic-release/python-semantic-release/commit/bf63156f60340614fae94c255fb2f097cf317b2b>)

    •   Use same changelog code for command as post (248f622 <https://github.com/python-semantic-release/python-semantic-release/commit/248f62283c59182868c43ff105a66d85c923a894>)

  📖 Documentation

    •   Add installation instructions for development (PR#106 <https://github.com/python-semantic-release/python-semantic-release/pull/106>, 9168d0e <https://github.com/python-semantic-release/python-semantic-release/commit/9168d0ea56734319a5d77e890f23ff6ba51cc97d>)

    •   readme: Add testing instructions (bb352f5 <https://github.com/python-semantic-release/python-semantic-release/commit/bb352f5b6616cc42c9f2f2487c51dedda1c68295>)

  v4.0.1 (2019-01-12)

  🪲 Bug Fixes

    •   Add better error message when pypi credentials are empty, closes #96 <https://github.com/python-semantic-release/python-semantic-release/issues/96> (c4e5dcb <https://github.com/python-semantic-release/python-semantic-release/commit/c4e5dcbeda0ce8f87d25faefb4d9ae3581029a8f>)

    •   Clean out dist and build before building, closes #86 <https://github.com/python-semantic-release/python-semantic-release/issues/86> (b628e46 <https://github.com/python-semantic-release/python-semantic-release/commit/b628e466f86bc27cbe45ec27a02d4774a0efd3bb>)

    •   Filter out pypi secrets from exceptions, closes #41 <https://github.com/python-semantic-release/python-semantic-release/issues/41> (5918371 <https://github.com/python-semantic-release/python-semantic-release/commit/5918371c1e82b06606087c9945d8eaf2604a0578>)

    •   Unfreeze dependencies, closes #100 <https://github.com/python-semantic-release/python-semantic-release/issues/100> (847833b <https://github.com/python-semantic-release/python-semantic-release/commit/847833bf48352a4935f906d0c3f75e1db596ca1c>)

    •   Use correct syntax to exclude tests in package, closes #92 <https://github.com/python-semantic-release/python-semantic-release/issues/92> (3e41e91 <https://github.com/python-semantic-release/python-semantic-release/commit/3e41e91c318663085cd28c8165ece21d7e383475>)

    •   parser_angular: Fix non-match when special chars in scope (8a33123 <https://github.com/python-semantic-release/python-semantic-release/commit/8a331232621b26767e4268079f9295bf695047ab>)

  📖 Documentation

    •   Remove reference to gitter, closes #90 <https://github.com/python-semantic-release/python-semantic-release/issues/90> (896e37b <https://github.com/python-semantic-release/python-semantic-release/commit/896e37b95cc43218e8f593325dd4ea63f8b895d9>)

  v4.0.0 (2018-11-22)

  ✨ Features

    •   Add support for commit_message config variable (4de5400 <https://github.com/python-semantic-release/python-semantic-release/commit/4de540011ab10483ee1865f99c623526cf961bb9>)

    •   CI checks: Add support for GitLab CI checks, closes #88 <https://github.com/python-semantic-release/python-semantic-release/issues/88> (8df5e2b <https://github.com/python-semantic-release/python-semantic-release/commit/8df5e2bdd33a620e683f3adabe174e94ceaa88d9>)

  🪲 Bug Fixes

    •   Add check of credentials (7d945d4 <https://github.com/python-semantic-release/python-semantic-release/commit/7d945d44b36b3e8c0b7771570cb2305e9e09d0b2>)

    •   Add credentials check (0694604 <https://github.com/python-semantic-release/python-semantic-release/commit/0694604f3b3d2159a4037620605ded09236cdef5>)

    •   Add dists to twine call (1cec2df <https://github.com/python-semantic-release/python-semantic-release/commit/1cec2df8bcb7f877c813d6470d454244630b050a>)

    •   Change requests from fixed version to version range (PR#93 <https://github.com/python-semantic-release/python-semantic-release/pull/93>, af3ad59 <https://github.com/python-semantic-release/python-semantic-release/commit/af3ad59f018876e11cc3acdda0b149f8dd5606bd>)

    •   Re-add skip-existing (366e9c1 <https://github.com/python-semantic-release/python-semantic-release/commit/366e9c1d0b9ffcde755407a1de18e8295f6ad3a1>)

    •   Remove repository argument in twine (e24543b <https://github.com/python-semantic-release/python-semantic-release/commit/e24543b96adb208897f4ce3eaab96b2f4df13106>)

    •   Remove universal from setup config (18b2402 <https://github.com/python-semantic-release/python-semantic-release/commit/18b24025e397aace03dd5bb9eed46cfdd13491bd>)

    •   Update twine (c4ae7b8 <https://github.com/python-semantic-release/python-semantic-release/commit/c4ae7b8ecc682855a8568b247690eaebe62d2d26>)

    •   Use new interface for twine (c04872d <https://github.com/python-semantic-release/python-semantic-release/commit/c04872d00a26e9bf0f48eeacb360b37ce0fba01e>)

    •   Use twine through cli call (ab84beb <https://github.com/python-semantic-release/python-semantic-release/commit/ab84beb8f809e39ae35cd3ce5c15df698d8712fd>)

  📖 Documentation

    •   Add type hints and more complete docstrings, closes #81 <https://github.com/python-semantic-release/python-semantic-release/issues/81> (a6d5e9b <https://github.com/python-semantic-release/python-semantic-release/commit/a6d5e9b1ccbe75d59e7240528593978a19d8d040>)

    •   Fix typo in documentation index (da6844b <https://github.com/python-semantic-release/python-semantic-release/commit/da6844bce0070a0020bf13950bd136fe28262602>)

  ♻️ Refactoring

    •   Remove support for python 2 (85fe638 <https://github.com/python-semantic-release/python-semantic-release/commit/85fe6384c15db317bc7142f4c8bbf2da58cece58>)

  💥 BREAKING CHANGES

    •   If you rely on the commit message to be the version number only, this will break your code

    •   This will only work with python 3 after this commit.

  v3.11.2 (2018-06-10)

  🪲 Bug Fixes

    •   Upgrade twine (9722313 <https://github.com/python-semantic-release/python-semantic-release/commit/9722313eb63c7e2c32c084ad31bed7ee1c48a928>)

  v3.11.1 (2018-06-06)

  🪲 Bug Fixes

    •   Change Gitpython version number, closes #80 <https://github.com/python-semantic-release/python-semantic-release/issues/80> (23c9d4b <https://github.com/python-semantic-release/python-semantic-release/commit/23c9d4b6a1716e65605ed985881452898d5cf644>)

  📖 Documentation

    •   Add retry option to cli docs (021da50 <https://github.com/python-semantic-release/python-semantic-release/commit/021da5001934f3199c98d7cf29f62a3ad8c2e56a>)

  v3.11.0 (2018-04-12)

  ✨ Features

    •   Add --retry cli option (PR#78 <https://github.com/python-semantic-release/python-semantic-release/pull/78>, 3e312c0 <https://github.com/python-semantic-release/python-semantic-release/commit/3e312c0ce79a78d25016a3b294b772983cfb5e0f>)

    •   Add support to finding previous version from tags if not using commit messages (PR#68 <https://github.com/python-semantic-release/python-semantic-release/pull/68>, 6786487 <https://github.com/python-semantic-release/python-semantic-release/commit/6786487ebf4ab481139ef9f43cd74e345debb334>)

    •   Be a bit more forgiving to find previous tags (PR#68 <https://github.com/python-semantic-release/python-semantic-release/pull/68>, 6786487 <https://github.com/python-semantic-release/python-semantic-release/commit/6786487ebf4ab481139ef9f43cd74e345debb334>)

  🪲 Bug Fixes

    •   Add pytest cache to gitignore (b8efd5a <https://github.com/python-semantic-release/python-semantic-release/commit/b8efd5a6249c79c8378bffea3e245657e7094ec9>)

    •   Make repo non if it is not a git repository, closes #74 <https://github.com/python-semantic-release/python-semantic-release/issues/74> (1dc306b <https://github.com/python-semantic-release/python-semantic-release/commit/1dc306b9b1db2ac360211bdc61fd815302d0014c>)

  📖 Documentation

    •   Define --retry usage (3e312c0 <https://github.com/python-semantic-release/python-semantic-release/commit/3e312c0ce79a78d25016a3b294b772983cfb5e0f>)

    •   Remove old notes about trello board (7f50c52 <https://github.com/python-semantic-release/python-semantic-release/commit/7f50c521a522bb0c4579332766248778350e205b>)

    •   Update status badges (cfa13b8 <https://github.com/python-semantic-release/python-semantic-release/commit/cfa13b8260e3f3b0bfcb395f828ad63c9c5e3ca5>)

  v3.10.3 (2018-01-29)

  🪲 Bug Fixes

    •   Error when not in git repository, closes #74 <https://github.com/python-semantic-release/python-semantic-release/issues/74> (PR#75 <https://github.com/python-semantic-release/python-semantic-release/pull/75>, 251b190 <https://github.com/python-semantic-release/python-semantic-release/commit/251b190a2fd5df68892346926d447cbc1b32475a>)

  v3.10.2 (2017-08-03)

  🪲 Bug Fixes

    •   Update call to upload to work with twine 1.9.1 (PR#72 <https://github.com/python-semantic-release/python-semantic-release/pull/72>, 8f47643 <https://github.com/python-semantic-release/python-semantic-release/commit/8f47643c54996e06c358537115e7e17b77cb02ca>)

  v3.10.1 (2017-07-22)

  🪲 Bug Fixes

    •   Update Twine (PR#69 <https://github.com/python-semantic-release/python-semantic-release/pull/69>, 9f268c3 <https://github.com/python-semantic-release/python-semantic-release/commit/9f268c373a932621771abbe9607b739b1e331409>)

  v3.10.0 (2017-05-05)

  ✨ Features

    •   Add git hash to the changelog (PR#65 <https://github.com/python-semantic-release/python-semantic-release/pull/65>, 628170e <https://github.com/python-semantic-release/python-semantic-release/commit/628170ebc440fc6abf094dd3e393f40576dedf9b>)

  🪲 Bug Fixes

    •   Make changelog problems not fail whole publish (b5a68cf <https://github.com/python-semantic-release/python-semantic-release/commit/b5a68cf6177dc0ed80eda722605db064f3fe2062>)

  📖 Documentation

    •   Fix typo in cli.py docstring (PR#64 <https://github.com/python-semantic-release/python-semantic-release/pull/64>, 0d13985 <https://github.com/python-semantic-release/python-semantic-release/commit/0d139859cd71f2d483f4360f196d6ef7c8726c18>)

  v3.9.0 (2016-07-03)

  ✨ Features

    •   Add option for choosing between versioning by commit or tag (c0cd1f5 <https://github.com/python-semantic-release/python-semantic-release/commit/c0cd1f5b2e0776d7b636c3dd9e5ae863125219e6>)

    •   Don't use file to track version, only tag to commit for versioning (cd25862 <https://github.com/python-semantic-release/python-semantic-release/commit/cd258623ee518c009ae921cd6bb3119dafae43dc>)

    •   Get repo version from historical tags instead of config file (a45a9bf <https://github.com/python-semantic-release/python-semantic-release/commit/a45a9bfb64538efeb7f6f42bb6e7ede86a4ddfa8>)

  🪲 Bug Fixes

    •   Can't get the proper last tag from commit history (5a0e681 <https://github.com/python-semantic-release/python-semantic-release/commit/5a0e681e256ec511cd6c6a8edfee9d905891da10>)

  v3.8.1 (2016-04-17)

  🪲 Bug Fixes

    •   Add search_parent_directories option to gitpython (PR#62 <https://github.com/python-semantic-release/python-semantic-release/pull/62>, 8bf9ce1 <https://github.com/python-semantic-release/python-semantic-release/commit/8bf9ce11137399906f18bc8b25698b6e03a65034>)

  v3.8.0 (2016-03-21)

  ✨ Features

    •   Add ci checks for circle ci (151d849 <https://github.com/python-semantic-release/python-semantic-release/commit/151d84964266c8dca206cef8912391cb73c8f206>)

  🪲 Bug Fixes

    •   Add git fetch to frigg after success (74a6cae <https://github.com/python-semantic-release/python-semantic-release/commit/74a6cae2b46c5150e63136fde0599d98b9486e36>)

    •   Make tag parser work correctly with breaking changes (9496f6a <https://github.com/python-semantic-release/python-semantic-release/commit/9496f6a502c79ec3acb4e222e190e76264db02cf>)

    •   Refactoring cli.py to improve --help and error messages (c79fc34 <https://github.com/python-semantic-release/python-semantic-release/commit/c79fc3469fb99bf4c7f52434fa9c0891bca757f9>)

  📖 Documentation

    •   Add info about correct commit guidelines (af35413 <https://github.com/python-semantic-release/python-semantic-release/commit/af35413fae80889e2c5fc6b7d28f77f34b3b4c02>)

    •   Add info about trello board in readme (5229557 <https://github.com/python-semantic-release/python-semantic-release/commit/5229557099d76b3404ea3677292332442a57ae2e>)

    •   Fix badges in readme (7f4e549 <https://github.com/python-semantic-release/python-semantic-release/commit/7f4e5493edb6b3fb3510d0bb78fcc8d23434837f>)

    •   Update info about releases in contributing.md (466f046 <https://github.com/python-semantic-release/python-semantic-release/commit/466f0460774cad86e7e828ffb50c7d1332b64e7b>)

  v3.7.2 (2016-03-19)

  🪲 Bug Fixes

    •   Move code around a bit to make flake8 happy (41463b4 <https://github.com/python-semantic-release/python-semantic-release/commit/41463b49b5d44fd94c11ab6e0a81e199510fabec>)

  v3.7.1 (2016-03-15)

  📖 Documentation

    •   configuration: Fix typo in setup.cfg section (725d87d <https://github.com/python-semantic-release/python-semantic-release/commit/725d87dc45857ef2f9fb331222845ac83a3af135>)

  v3.7.0 (2016-01-10)

  ✨ Features

    •   Add ci_checks for Frigg CI (577c374 <https://github.com/python-semantic-release/python-semantic-release/commit/577c374396fe303b6fe7d64630d2959998d3595c>)

  v3.6.1 (2016-01-10)

  🪲 Bug Fixes

    •   Add requests as dependency (4525a70 <https://github.com/python-semantic-release/python-semantic-release/commit/4525a70d5520b44720d385b0307e46fae77a7463>)

  v3.6.0 (2015-12-28)

  ✨ Features

    •   Add checks for semaphore, closes #44 <https://github.com/python-semantic-release/python-semantic-release/issues/44> (2d7ef15 <https://github.com/python-semantic-release/python-semantic-release/commit/2d7ef157b1250459060e99601ec53a00942b6955>)

  📖 Documentation

    •   Add documentation for configuring on CI (7806940 <https://github.com/python-semantic-release/python-semantic-release/commit/7806940ae36cb0d6ac0f966e5d6d911bd09a7d11>)

    •   Add note about node semantic release (0d2866c <https://github.com/python-semantic-release/python-semantic-release/commit/0d2866c528098ecaf1dd81492f28d3022a2a54e0>)

    •   Add step by step guide for configuring travis ci (6f23414 <https://github.com/python-semantic-release/python-semantic-release/commit/6f2341442f61f0284b1119a2c49e96f0be678929>)

    •   Move automatic-releases to subfolder (ed68e5b <https://github.com/python-semantic-release/python-semantic-release/commit/ed68e5b8d3489463e244b078ecce8eab2cba2bb1>)

    •   Remove duplicate readme (42a9421 <https://github.com/python-semantic-release/python-semantic-release/commit/42a942131947cd1864c1ba29b184caf072408742>)

  v3.5.0 (2015-12-22)

  ✨ Features

    •   Add author in commit, closes #40 <https://github.com/python-semantic-release/python-semantic-release/issues/40> (020efaa <https://github.com/python-semantic-release/python-semantic-release/commit/020efaaadf588e3fccd9d2f08a273c37e4158421>)

    •   Checkout master before publishing (dc4077a <https://github.com/python-semantic-release/python-semantic-release/commit/dc4077a2d07e0522b625336dcf83ee4e0e1640aa>)

  🪲 Bug Fixes

    •   Remove " from git push command (031318b <https://github.com/python-semantic-release/python-semantic-release/commit/031318b3268bc37e6847ec049b37425650cebec8>)

  📖 Documentation

    •   Convert readme to rst (e8a8d26 <https://github.com/python-semantic-release/python-semantic-release/commit/e8a8d265aa2147824f18065b39a8e7821acb90ec>)

  v3.4.0 (2015-12-22)

  ✨ Features

    •   Add travis environment checks (f386db7 <https://github.com/python-semantic-release/python-semantic-release/commit/f386db75b77acd521d2f5bde2e1dde99924dc096>)

  v3.3.3 (2015-12-22)

  🪲 Bug Fixes

    •   Do git push and git push --tags instead of --follow-tags (8bc70a1 <https://github.com/python-semantic-release/python-semantic-release/commit/8bc70a183fd72f595c72702382bc0b7c3abe99c8>)

  v3.3.2 (2015-12-21)

  🪲 Bug Fixes

    •   Change build badge (0dc068f <https://github.com/python-semantic-release/python-semantic-release/commit/0dc068fff2f8c6914f4abe6c4e5fb2752669159e>)

  📖 Documentation

    •   Update docstrings for generate_changelog (987c6a9 <https://github.com/python-semantic-release/python-semantic-release/commit/987c6a96d15997e38c93a9d841c618c76a385ce7>)

  v3.3.1 (2015-12-21)

  🪲 Bug Fixes

    •   Add pandoc to travis settings (17d40a7 <https://github.com/python-semantic-release/python-semantic-release/commit/17d40a73062ffa774542d0abc0f59fc16b68be37>)

    •   Only list commits from the last version tag, closes #28 <https://github.com/python-semantic-release/python-semantic-release/issues/28> (191369e <https://github.com/python-semantic-release/python-semantic-release/commit/191369ebd68526e5b1afcf563f7d13e18c8ca8bf>)

  v3.3.0 (2015-12-20)

  ✨ Features

    •   Add support for environment variables for pypi credentials (3b383b9 <https://github.com/python-semantic-release/python-semantic-release/commit/3b383b92376a7530e89b11de481c4dfdfa273f7b>)

  🪲 Bug Fixes

    •   Add missing parameters to twine.upload (4bae22b <https://github.com/python-semantic-release/python-semantic-release/commit/4bae22bae9b9d9abf669b028ea3af4b3813a1df0>)

    •   Better filtering of github token in push error (9b31da4 <https://github.com/python-semantic-release/python-semantic-release/commit/9b31da4dc27edfb01f685e6036ddbd4c715c9f60>)

    •   Downgrade twine to version 1.5.0 (66df378 <https://github.com/python-semantic-release/python-semantic-release/commit/66df378330448a313aff7a7c27067adda018904f>)

    •   Make sure the github token is not in the output (55356b7 <https://github.com/python-semantic-release/python-semantic-release/commit/55356b718f74d94dd92e6c2db8a15423a6824eb5>)

    •   Push to master by default (a0bb023 <https://github.com/python-semantic-release/python-semantic-release/commit/a0bb023438a1503f9fdb690d976d71632f19a21f>)

  v3.2.1 (2015-12-20)

  🪲 Bug Fixes

    •   Add requirements to manifest (ed25ecb <https://github.com/python-semantic-release/python-semantic-release/commit/ed25ecbaeec0e20ad3040452a5547bb7d6faf6ad>)

    •   pypi: Add sdist as default in addition to bdist_wheel (a1a35f4 <https://github.com/python-semantic-release/python-semantic-release/commit/a1a35f43175187091f028474db2ebef5bfc77bc0>)

  v3.2.0 (2015-12-20)

  ✨ Features

    •   angular-parser: Remove scope requirement (90c9d8d <https://github.com/python-semantic-release/python-semantic-release/commit/90c9d8d4cd6d43be094cda86579e00b507571f98>)

    •   git: Add push to <GH_TOKEN@github-url> (546b5bf <https://github.com/python-semantic-release/python-semantic-release/commit/546b5bf15466c6f5dfe93c1c03ca34604b0326f2>)

  🪲 Bug Fixes

    •   deps: Use one file for requirements (4868543 <https://github.com/python-semantic-release/python-semantic-release/commit/486854393b24803bb2356324e045ccab17510d46>)

  v3.1.0 (2015-08-31)

  ✨ Features

    •   pypi: Add option to disable pypi upload (f5cd079 <https://github.com/python-semantic-release/python-semantic-release/commit/f5cd079edb219de5ad03a71448d578f5f477da9c>)

  v3.0.0 (2015-08-25)

  ✨ Features

    •   parser: Add tag parser (a7f392f <https://github.com/python-semantic-release/python-semantic-release/commit/a7f392fd4524cc9207899075631032e438e2593c>)

  🪲 Bug Fixes

    •   errors: Add exposing of errors in package (3662d76 <https://github.com/python-semantic-release/python-semantic-release/commit/3662d7663291859dd58a91b4b4ccde4f0edc99b2>)

    •   version: Parse file instead for version (005dba0 <https://github.com/python-semantic-release/python-semantic-release/commit/005dba0094eeb4098315ef383a746e139ffb504d>)

  v2.1.4 (2015-08-24)

  🪲 Bug Fixes

    •   github: Fix property calls (7ecdeb2 <https://github.com/python-semantic-release/python-semantic-release/commit/7ecdeb22de96b6b55c5404ebf54a751911c4d8cd>)

  v2.1.3 (2015-08-22)

  🪲 Bug Fixes

    •   hvcs: Make Github.token an property (37d5e31 <https://github.com/python-semantic-release/python-semantic-release/commit/37d5e3110397596a036def5f1dccf0860964332c>)

  📖 Documentation

    •   api: Update apidocs (6185380 <https://github.com/python-semantic-release/python-semantic-release/commit/6185380babedbbeab2a2a342f17b4ff3d4df6768>)

    •   parsers: Add documentation about commit parsers (9b55422 <https://github.com/python-semantic-release/python-semantic-release/commit/9b554222768036024a133153a559cdfc017c1d91>)

    •   readme: Update readme with information about the changelog command (56a745e <https://github.com/python-semantic-release/python-semantic-release/commit/56a745ef6fa4edf6f6ba09c78fcc141102cf2871>)

  v2.1.2 (2015-08-20)

  🪲 Bug Fixes

    •   cli: Fix call to generate_changelog in publish (5f8bce4 <https://github.com/python-semantic-release/python-semantic-release/commit/5f8bce4cbb5e1729e674efd6c651e2531aea2a16>)

  v2.1.1 (2015-08-20)

  🪲 Bug Fixes

    •   history: Fix issue in get_previous_version (f961786 <https://github.com/python-semantic-release/python-semantic-release/commit/f961786aa3eaa3a620f47cc09243340fd329b9c2>)

  v2.1.0 (2015-08-20)

  ✨ Features

    •   cli: Add the possibility to re-post the changelog (4d028e2 <https://github.com/python-semantic-release/python-semantic-release/commit/4d028e21b9da01be8caac8f23f2c11e0c087e485>)

  🪲 Bug Fixes

    •   cli: Fix check of token in changelog command (cc6e6ab <https://github.com/python-semantic-release/python-semantic-release/commit/cc6e6abe1e91d3aa24e8d73e704829669bea5fd7>)

    •   github: Fix the github releases integration (f0c3c1d <https://github.com/python-semantic-release/python-semantic-release/commit/f0c3c1db97752b71f2153ae9f623501b0b8e2c98>)

    •   history: Fix changelog generation (f010272 <https://github.com/python-semantic-release/python-semantic-release/commit/f01027203a8ca69d21b4aff689e60e8c8d6f9af5>)

  v2.0.0 (2015-08-19)

  ✨ Features

    •   cli: Add command for printing the changelog (336b8bc <https://github.com/python-semantic-release/python-semantic-release/commit/336b8bcc01fc1029ff37a79c92935d4b8ea69203>)

    •   github: Add github release changelog helper (da18795 <https://github.com/python-semantic-release/python-semantic-release/commit/da187951af31f377ac57fe17462551cfd776dc6e>)

    •   history: Add angular parser (91e4f0f <https://github.com/python-semantic-release/python-semantic-release/commit/91e4f0f4269d01b255efcd6d7121bbfd5a682e12>)

    •   history: Add generate_changelog function (347f21a <https://github.com/python-semantic-release/python-semantic-release/commit/347f21a1f8d655a71a0e7d58b64d4c6bc6d0bf31>)

    •   history: Add markdown changelog formatter (d77b58d <https://github.com/python-semantic-release/python-semantic-release/commit/d77b58db4b66aec94200dccab94f483def4dacc9>)

    •   history: Set angular parser as the default (c2cf537 <https://github.com/python-semantic-release/python-semantic-release/commit/c2cf537a42beaa60cd372c7c9f8fb45db8085917>)

    •   publish: Add publishing of changelog to github (74324ba <https://github.com/python-semantic-release/python-semantic-release/commit/74324ba2749cdbbe80a92b5abbecfeab04617699>)

    •   settings: Add loading of current parser (7bd0916 <https://github.com/python-semantic-release/python-semantic-release/commit/7bd0916f87a1f9fe839c853eab05cae1af420cd2>)

  🪲 Bug Fixes

    •   cli: Change output indentation on changelog (2ca41d3 <https://github.com/python-semantic-release/python-semantic-release/commit/2ca41d3bd1b8b9d9fe7e162772560e3defe2a41e>)

    •   history: Fix level id's in angular parser (2918d75 <https://github.com/python-semantic-release/python-semantic-release/commit/2918d759bf462082280ede971a5222fe01634ed8>)

    •   history: Fix regex in angular parser (974ccda <https://github.com/python-semantic-release/python-semantic-release/commit/974ccdad392d768af5e187dabc184be9ac3e133d>)

    •   history: Support unexpected types in changelog generator (13deacf <https://github.com/python-semantic-release/python-semantic-release/commit/13deacf5d33ed500e4e94ea702a2a16be2aa7c48>)

  💥 BREAKING CHANGES

    •   history: The default parser is now angular. Thus, the default behavior of the commit log evaluator will change. From now on it will use the angular commit message spec to determine the new version.

  v1.0.0 (2015-08-04)

  💥 Breaking

    •   Restructure helpers into history and pypi (00f64e6 <https://github.com/python-semantic-release/python-semantic-release/commit/00f64e623db0e21470d55488c5081e12d6c11fd3>)

  📖 Documentation

    •   Add automatic publishing documentation, resolves #18 <https://github.com/python-semantic-release/python-semantic-release/issues/18> (58076e6 <https://github.com/python-semantic-release/python-semantic-release/commit/58076e60bf20a5835b112b5e99a86c7425ffe7d9>)

  v0.9.1 (2015-08-04)

  🪲 Bug Fixes

    •   Fix get_current_head_hash to ensure it only returns the hash (7c28832 <https://github.com/python-semantic-release/python-semantic-release/commit/7c2883209e5bf4a568de60dbdbfc3741d34f38b4>)

  v0.9.0 (2015-08-03)

  ✨ Features

    •   Add Python 2.7 support, resolves #10 <https://github.com/python-semantic-release/python-semantic-release/issues/10> (c05e13f <https://github.com/python-semantic-release/python-semantic-release/commit/c05e13f22163237e963c493ffeda7e140f0202c6>)

  v0.8.0 (2015-08-03)

  ✨ Features

    •   Add check_build_status option, resolves #5 <https://github.com/python-semantic-release/python-semantic-release/issues/5> (310bb93 <https://github.com/python-semantic-release/python-semantic-release/commit/310bb9371673fcf9b7b7be48422b89ab99753f04>)

    •   Add get_current_head_hash in git helpers (d864282 <https://github.com/python-semantic-release/python-semantic-release/commit/d864282c498f0025224407b3eeac69522c2a7ca0>)

    •   Add git helper to get owner and name of repo (f940b43 <https://github.com/python-semantic-release/python-semantic-release/commit/f940b435537a3c93ab06170d4a57287546bd8d3b>)

  v0.7.0 (2015-08-02)

  ✨ Features

    •   Add patch_without_tag option, resolves #6 <https://github.com/python-semantic-release/python-semantic-release/issues/6> (3734a88 <https://github.com/python-semantic-release/python-semantic-release/commit/3734a889f753f1b9023876e100031be6475a90d1>)

  📖 Documentation

    •   Set up sphinx based documentation, resolves #1 <https://github.com/python-semantic-release/python-semantic-release/issues/1> (41fba78 <https://github.com/python-semantic-release/python-semantic-release/commit/41fba78a389a8d841316946757a23a7570763c39>)

  v0.6.0 (2015-08-02)

  ✨ Features

    •   Add twine for uploads to pypi, resolves #13 <https://github.com/python-semantic-release/python-semantic-release/issues/13> (eec2561 <https://github.com/python-semantic-release/python-semantic-release/commit/eec256115b28b0a18136a26d74cfc3232502f1a6>)

  v0.5.4 (2015-07-29)

  🪲 Bug Fixes

    •   Add python2 not supported warning (e84c4d8 <https://github.com/python-semantic-release/python-semantic-release/commit/e84c4d8b6f212aec174baccd188185627b5039b6>)

  v0.5.3 (2015-07-28)

  ⚙️ Build System

    •   Add wheel as a dependency (971e479 <https://github.com/python-semantic-release/python-semantic-release/commit/971e4795a8b8fea371fcc02dc9221f58a0559f32>)

  v0.5.2 (2015-07-28)

  🪲 Bug Fixes

    •   Fix python wheel tag (f9ac163 <https://github.com/python-semantic-release/python-semantic-release/commit/f9ac163491666022c809ad49846f3c61966e10c1>)

  v0.5.1 (2015-07-28)

  🪲 Bug Fixes

    •   Fix push commands (8374ef6 <https://github.com/python-semantic-release/python-semantic-release/commit/8374ef6bd78eb564a6d846b882c99a67e116394e>)

  v0.5.0 (2015-07-28)

  ✨ Features

    •   Add setup.py hook for the cli interface (c363bc5 <https://github.com/python-semantic-release/python-semantic-release/commit/c363bc5d3cb9e9a113de3cd0c49dd54a5ea9cf35>)

  v0.4.0 (2015-07-28)

  ✨ Features

    •   Add publish command (d8116c9 <https://github.com/python-semantic-release/python-semantic-release/commit/d8116c9dec472d0007973939363388d598697784>)

  v0.3.2 (2015-07-28)

    •   No change

  v0.3.1 (2015-07-28)

  🪲 Bug Fixes

    •   Fix wheel settings (1e860e8 <https://github.com/python-semantic-release/python-semantic-release/commit/1e860e8a4d9ec580449a0b87be9660a9482fa2a4>)

  v0.3.0 (2015-07-27)

  ✨ Features

    •   Add support for tagging releases (5f4736f <https://github.com/python-semantic-release/python-semantic-release/commit/5f4736f4e41bc96d36caa76ca58be0e1e7931069>)

  🪲 Bug Fixes

    •   Fix issue when version should not change (441798a <https://github.com/python-semantic-release/python-semantic-release/commit/441798a223195138c0d3d2c51fc916137fef9a6c>)

  v0.2.0 (2015-07-27)

  ✨ Features

    •   added no-operation (--noop) mode (44c2039 <https://github.com/python-semantic-release/python-semantic-release/commit/44c203989aabc9366ba42ed2bc40eaccd7ac891c>)

  ⚙️ Build System

    •   Swapped pygit2 with gitpython to avoid libgit2 dependency (8165a2e <https://github.com/python-semantic-release/python-semantic-release/commit/8165a2eef2c6eea88bfa52e6db37abc7374cccba>)

  v0.1.1 (2015-07-27)

  🪲 Bug Fixes

    •   Fix entry point (bd7ce7f <https://github.com/python-semantic-release/python-semantic-release/commit/bd7ce7f47c49e2027767fb770024a0d4033299fa>)

  v0.1.0 (2015-07-27)

    •   Initial Release

  Concepts

This section covers the core concepts of Python Semantic Release and how it works. Understanding these concepts will help you effectively use Python Semantic Release in your projects.

  Getting Started

If you haven't done so already, install Python Semantic Release locally following the installation instructions <#installation>.

If you are using a CI/CD service, you may not have to add Python Semantic Release to your project's dependencies permanently, but for the duration of this guide for the initial setup, you will need to have it installed locally.

  Configuring PSR

Python Semantic Release ships with a reasonable default configuration but some aspects MUST be customized to your project. To view the default configuration, run the following command:

            semantic-release generate-config

The output of the above command is the default configuration in TOML format without any modifications. If this is fine for your project, then you do not need to configure anything else.

PSR accepts overrides to the default configuration keys individually. If you don't define the key-value pair in your configuration file, the default value will be used.

By default, Python Semantic Release will look for configuration overrides in pyproject.toml under the TOML table [tool.semantic_release]. You may specify a different file using the -c/--config option, for example:

            # In TOML format with top level table [semantic_release]
            semantic-release -c releaserc.toml

            # In JSON format with top level object key {"semantic_release": {}}
            semantic-release -c releaserc.json

The easiest way to get started is to output the default configuration to a file, delete keys you do not need to override, and then edit the remaining keys to suit your project.

To set up in pyproject.toml, run the following command:

            # In file redirect in bash
            semantic-release generate-config --pyproject >> pyproject.toml

            # Open your editor to edit the configuration
            vim pyproject.toml

See also:

            •   cmd-generate-config

            •   Configuration <#configuration>

  Configuring the Version Stamp Feature

One of the best features of Python Semantic Release is the ability to automatically stamp the new version number into your project files, so you don't have to manually update the version upon each release. The version that is stamped is automatically determined by Python Semantic Release from your commit messages which compliments automated versioning seamlessly.

The most crucial version stamp is the one in your project metadata, which is used by the Python Package Index (PyPI) and other package managers to identify the version of your package.

For Python projects, this is typically the version field in your pyproject.toml file. First, set up your project metadata with the base version value. If you are starting with a brand new project, set project.version = "0.0.0". If you are working on an existing project, set it to the last version number you released. Do not include any v prefix.

Important:
        The version number must be a valid SemVer version, which means it should follow the format MAJOR.MINOR.PATCH (e.g., 1.0.0). Python Semantic Release does NOT support Canonical version values defined in the PEP 440 <https://peps.python.org/pep-0440/> specification at this time. See Issue #455 <https://github.com/python-semantic-release/python-semantic-release/issues/455> for more details. Note that you can still define a SemVer version in the project.version field, and when your build is generated, the build tool will automatically generate a PEP 440 compliant version as long as you do NOT use a non-pep440 compliant pre-release token.

Your project metadata might look like this in pyproject.toml:

            [project]
            name = "my-package"
            version = "0.0.0"  # Set this to the last released version or "0.0.0" for new projects
            description = "A sample Python package"

To configure PSR to automatically update this version number, you need to specify the file and value to update in your configuration. Since pyproject.toml uses TOML format, you will add the replacement specification to the tool.semantic_release.version_toml list. Update the following configuration in your pyproject.toml file to include the version variable location:

            [tool.semantic_release]
            version_toml = ["pyproject.toml:project.version"]

            # Alternatively, if you are using poetry's 'version' key, then you would use:
            version_toml = ["pyproject.toml:tool.poetry.version"]

If you have other TOML files where you want to stamp the version, you can add them to the version_toml list as well. In the above example, there is an implicit assumption that you only want the version as the raw number format. If you want to specify the full tag value (e.g. v-prefixed version), then include :tf for "tag format" at the end of the version variable specification.

For non-TOML formatted files (such as JSON or YAML files), you can use the version_variables <#config-version-variables> configuration key instead. This feature uses an advanced Regular Expression to find and replace the version variable in the specified files.

For Python files, its much more effective to use importlib instead which will allow you to dynamically import the version from your package metadata and not require your project to commit the version number bump to the repository. For example, in your package's base __init__.py

            # my_package/__init__.py
            from importlib.metadata import version as get_version

            __version__ = get_version(__package__)
            # Note: __package__ must match your 'project.name' as defined in pyproject.toml

See also:

            •   Configuration specification of version_toml <#config-version-toml>

            •   Configuration specification of version_variables <#config-version-variables>

  Using PSR to Build your Project

PSR provides a convenient way to build your project artifacts as part of the versioning process now that you have stamped the version into your project files. To enable this, you will need to specify the build command in your configuration. This command will be executed after the next version has been determined, and stamped into your files but before a release tag has been created.

To set up the build command, add the following to your pyproject.toml file:

            [tool.semantic_release]
            build_command = "python -m build --sdist --wheel ."

See also:

            •   build_command <#config-build-command> - Configuration specification for the build command.

            •   build_command_env <#config-build-command-env> - Configuration specification for the build command environment variables.

  Choosing a Commit Message Parser

PSR uses commit messages to determine the type of version bump that should be applied to your project. PSR supports multiple commit message parsing styles, allowing you to choose the one that best fits your project's needs. Choose one of the supported commit parsers defined in Commit Parsing <#commit-parsing>, or provide your own and configure it in your pyproject.toml file.

Each commit parser has its own default configuration options so if you want to customize the parser behavior, you will need to specify the parser options you want to override.

            [tool.semantic_release]
            commit_parser = "conventional"

            [tool.semantic_release.commit_parser_options]
            minor_tags = ["feat"]
            patch_tags = ["fix", "perf"]
            parse_squash_commits = true
            ignore_merge_commits = true

  Choosing your Changelog

Prior to creating a release, PSR will generate a changelog from the commit messages of your project. The changelog is extremely customizable from the format to the content of each section. PSR ships with a default changelog template that will be used if you do not provide custom templates. The default should be sufficient for most projects and has its own set of configuration options.

For basic customization, you can choose either an traditional Markdown formatted changelog (default) or if you want to integrate with a Sphinx Documentation project, you can use the reStructuredText (RST) format. You can also choose the file name and location of where to write the default changelog.

To set your changelog location and changelog format, add the following to your pyproject.toml file:

            [tool.semantic_release.changelog.default_templates]
            changelog_file = "docs/source/CHANGELOG.rst"
            output_format = "rst" # or "md" for Markdown format

Secondly, the more important aspect of configuring your changelog is to define Commit Exclusion Patterns or patterns that will be used to filter out commits from the changelog. PSR does NOT (yet) come with a built-in set of exclusion patterns, so you will need to define them yourself. These commit patterns should be in line with your project's commit parser configuration.

To set commit exclusion patterns for a conventional commits parsers, add the following to your pyproject.toml file:

            [tool.semantic_release.changelog]
            # Recommended patterns for conventional commits parser that is scope aware
            exclude_commit_patterns = [
                '''chore(?:\([^)]*?\))?: .+''',
                '''ci(?:\([^)]*?\))?: .+''',
                '''refactor(?:\([^)]*?\))?: .+''',
                '''style(?:\([^)]*?\))?: .+''',
                '''test(?:\([^)]*?\))?: .+''',
                '''build\((?!deps\): .+)''',
                '''Initial [Cc]ommit.*''',
            ]

See also:

            •   Changelog <#config-changelog> - Customize your changelog

            •   changelog.mode <#config-changelog-mode> - Choose the changelog mode ('update' or 'init')

            •   Migrating an Existing Changelog <#changelog-templates-migrating-existing-changelog>

  Defining your Release Branches

PSR provides a powerful feature to manage release types across multiple branches which can allow you to configure your project to have different release branches for different purposes, such as pre-release branches, beta branches, and your stable releases.

Note:
        Most projects that do NOT publish pre-releases will be fine with PSR's built-in default.

To define an alpha pre-release branch when you are working on a fix or new feature, you can add the following to your pyproject.toml file:

            [tool.semantic_release.branches.alpha]
            # Matches branches with the prefixes 'feat/', 'fix/', or 'perf/'.
            match = "^(feat|fix|perf)/.+"
            prerelease = true
            prerelease_token = "alpha"

Any time you execute semantic-release version on a branch with the prefix feat/, fix/, or perf/, PSR will determine if a version bump is needed and if so, the resulting version will be a pre-release version with the alpha token. For example,
Branch | Version Bump | Current Version | Next Version
main | Patch | 1.0.0 | 1.0.1
fix/bug-1 | Patch | 1.0.0 | 1.0.1-alpha.1

See also:

            •   Multibranch Releases <#multibranch-releases> - Learn about multi-branch releases and how to configure them.

  Configuring 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.

  GitHub (GH_TOKEN)

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 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 <https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens#repository-permissions-for-contents> permission.

  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 <https://support.atlassian.com/bitbucket-cloud/docs/push-back-to-your-repository/#App-secret>, store the secret in the BITBUCKET_TOKEN environment variable and the username in BITBUCKET_USER.

    3.  Use an Access Token <https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens> for the repository and store it in the BITBUCKET_TOKEN environment variable.

See also:

            •   Changelog <#config-changelog> - customize your project's changelog.

            •   Custom Release Notes <#changelog-templates-custom-release-notes> - customize the published release notes

            •   version --vcs-release/--no-vcs-release - enable/disable VCS release creation.

  Testing your Configuration

It's time to test your configuration!

            # 1. Run the command in no-operation mode to see what would happen
            semantic-release -v --noop version

            # 2. If the output looks reasonable, try to run the command without any history changes
            #    '-vv' will give you verbose debug output, which is useful for troubleshooting
            #    commit parsing issues.
            semantic-release -vv version --no-commit --no-tag

            # 3. Evaluate your repository to see the changes that were made but not committed
            #    - Check the version number in your pyproject.toml
            #    - Check the distribution files from the build command
            #    - Check the changelog file for the new release notes

            # 4. If everything looks good, make sure to commit/save your configuration changes
            git add pyproject.toml
            git commit -m "chore(config): configure Python Semantic Release"

            # 5. Now, try to run the release command with your history changes but without pushing
            semantic-release -v version --no-push --no-vcs-release

            # 6. Check the result on your local repository
            git status
            git log --graph --decorate --all

            # 7a. If you are happy with the release history and resulting commit & tag,
            #     reverse your changes before trying the full release command.
            git tag -d v0.0.1  # replace with the actual version you released
            git reset --hard HEAD~1

            # 7b. [Optional] Once you have configured a remote VCS token, try
            #     running the full release command to update the remote repository.
            semantic-release version --push --vcs-release
            #    This is optional as you may not want a personal access token set up or make
            #    make the release permanent yet.

See also:

            •   cmd-version

            •   Increasing Verbosity <#troubleshooting-verbosity>

  Configuring CI/CD

PSR is meant to help you release at speed! See our CI/CD Configuration guides under the Automated Releases <#automatic> section.

  Commit Parsing

One of the core components of Python Semantic Release (PSR) is the commit parser. The commit parser is responsible for parsing a Project's Git Repository commit history to extract insights about project changes and make decisions based on this insight.

The primary decision that PSR makes based on the commit history is whether or not to release a new version of the project, and if so, what version number to release. This decision is made based on the commit message descriptions of the change impact introduced by the commit. The change impact describes the impact to the end consumers of the project. Depending on the type of change, the version number will be incremented according to the Semantic Versioning <https://semver.org/> specification (semver). It is the commit parser's job to extract the change impact from the commit message to determine the severity of the changes and then subsequently determine the semver level that the version should be bumped to for the next release.

The commit parser is also responsible for interpreting other aspects of the commit message which can be used to generate a helpful and detailed changelog. This includes extracting the type of change, the scope of the change, any breaking change descriptions, any linked pull/merge request numbers, and any linked issue numbers.

PSR provides several built-in commit parsers to handle a variety of different commit message styles. If the built-in parsers do not meet your needs, you can write your own custom parser to handle your specific commit message style.

Warning:
        PSR's built-in commit parsers are designed to be flexible enough to provide a convenient way to generate the most effective changelogs we can, which means some features are added beyond the scope of the original commit message style guidelines.

        Other tools may not follow the same conventions as PSR's guideline extensions, so if you plan to use any similar programs in tandem with PSR, you should be aware of the differences in feature support and fall back to the official format guidelines if necessary.

----

  Built-in Commit Parsers

The following parsers are built in to Python Semantic Release:

    •   ConventionalCommitParser

    •   ConventionalCommitMonorepoParser (available in v10.4.0+)

    •   AngularCommitParser (deprecated in v9.19.0)

    •   EmojiCommitParser

    •   ScipyCommitParser

    •   TagCommitParser (deprecated in v9.12.0)

----

  Conventional Commits Parser

Introduced in v9.19.0

A parser that is designed to parse commits formatted according to the Conventional Commits Specification <https://www.conventionalcommits.org/en/v1.0.0>. The parser is implemented with the following logic in relation to PSR's core features:

    •   Version Bump Determination: This parser extracts the commit type from the subject line of the commit (the first line of a commit message). This type is matched against the configuration mapping to determine the level bump for the specific commit. If the commit type is not found in the configuration mapping, the commit is considered a non-parsable commit and will return it as a ParseError object and ultimately a commit of type "unknown". The configuration mapping contains lists of commit types that correspond to the level bump for each commit type. Some commit types are still valid do not trigger a level bump, such as "chore" or "docs". You can also configure the default level bump commit_parser_options.default_level_bump <#config-commit-parser-options> if desired. To trigger a major release, the commit message body must contain a paragraph that begins with BREAKING CHANGE:. This will override the level bump determined by the commit type.

    •   Changelog Generation: PSR will group commits in the changelog by the commit type used in the commit message. The commit type shorthand is converted to a more human-friendly section heading and then used as the version section title of the changelog and release notes. Under the section title, the parsed commit descriptions are listed out in full. If the commit includes an optional scope, then the scope is prefixed on to the first line of the commit description. If a commit has any breaking change prefixed paragraphs in the commit message body, those paragraphs are separated out into a "Breaking Changes" section in the changelog (Breaking Changes section is available from the default changelog in v9.15.0). Each breaking change paragraph is listed in a bulleted list format across the entire version. A single commit is allowed to have more than one breaking change prefixed paragraph (as opposed to the Conventional Commits Specification <https://www.conventionalcommits.org/en/v1.0.0>). Commits with an optional scope and a breaking change will have the scope prefixed on to the breaking change paragraph. Parsing errors will return a ParseError object and ultimately a commit of type "unknown". Unknown commits are consolidated into an "Unknown" section in the changelog by the default template. To remove unwanted commits from the changelog that normally are placed in the "unknown" section, consider the use of the configuration option changelog.exclude_commit_patterns <#config-changelog-exclude-commit-patterns> to ignore those commit styles.

    •   Pull/Merge Request Identifier Detection: This parser implements PSR's Common Linked Merge Request Detection to identify and extract pull/merge request numbers. The parser will return a string value if a pull/merge request number is found in the commit message. If no pull/merge request number is found, the parser will return an empty string.

    •   Linked Issue Identifier Detection: This parser implements PSR's Common Issue Identifier Detection to identify and extract issue numbers. The parser will return a tuple of issue numbers as strings if any are found in the commit message. If no issue numbers are found, the parser will return an empty tuple.

    •   Squash Commit Evaluation: This parser implements PSR's Common Squash Commit Evaluation to identify and extract each commit message as a separate commit message within a single squashed commit. You can toggle this feature on/off via the commit_parser_options <#config-commit-parser-options> setting.

    •   Release Notice Footer Detection: This parser implements PSR's Common Release Notice Footer Detection, which is a custom extension to traditional Conventional Commits Specification <https://www.conventionalcommits.org/en/v1.0.0> to use the NOTICE keyword as a git footer to document additional release information that is not considered a breaking change.

Limitations:

    •   Commits with the revert type are not currently supported. Track the implementation of this feature in the issue #402 <https://github.com/python-semantic-release/python-semantic-release/issues/402>.

If no commit parser options are provided via the configuration, the parser will use PSR's built-in defaults <#semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions>.

----

  Conventional Commits Monorepo Parser

Introduced in v10.4.0

Important:
        In order for this parser to be effective, please review the section titled Releasing Packages from a Monorepo <#monorepos> for details on file structure, configurations, and release actions.

This parser is an extension of the Conventional Commits Parser, designed specifically for monorepo environments. A monorepo environment is defined as a single source control repository that contains multiple packages, each of which can be released independently and may have different version numbers.

This parser introduces two new configuration options that determine which packages are affected by a commit. These options control whether a commit is considered for version determination, changelog generation, and other release actions for the relevant packages. The 2 new configuration options are path_filters <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions.path_filters> and scope_prefix <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions.scope_prefix>.

Features:

    •   Package Specific Commit Filtering: For monorepo support, this parser uses 2 filtering rules to determine if a commit should be considered for a specific package. The first rule is based on file paths that are changed in the commit and the second rule is based on the optional scope prefix defined in the commit message. If either rule matches, then the commit is considered relevant to that package and will be used in version determination, changelog generation, etc, for that package. If neither rule matches, then the commit is ignored for that package. File path filtering rules are applied first and are the primary way to determine package relevance. The path_filters <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions.path_filters> option allows for specifying a list of file path patterns and will also support negated patterns to ignore specific paths that otherwise would be selected from the file glob pattern. Negated patterns are defined by prefixing the pattern with an exclamation point (!). File path filtering is quite effective by itself but to handle the edge cases, the parser has the scope_prefix <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions.scope_prefix> configuration option to allow the developer to specifically define when the commit is relevant to the package. In monorepo setups, there are often shared files between packages (generally at the root project level) that are modified occasionally but not always relevant to the package being released. Since you do not want to define this path in the package configuration as it may not be relevant to the release, then this parser will look for a match with the scope prefix. The scope prefix is a regular expression that is used to match the text inside the scope field of a Conventional Commit. The scope prefix is optional and is used only if file path filtering does not match. Commits that have matching files in the commit will be considered relevant to the package regardless if a scope prefix exists or if it matches.

    •   Version Bump Determination: Once package-specific commit filtering is applied, the relevant commits are passed to the Conventional Commits Parser for evaluation and then used for version bump determination. See Conventional Commits Parser for details.

    •   Changelog Generation: Once package-specific commit filtering is applied, the relevant commits are passed to the Conventional Commits Parser for evaluation and then used for changelog generation. See Conventional Commits Parser for details.

    •   Pull/Merge Request Identifier Detection: Once package-specific commit filtering is applied, the relevant commits are passed to the Conventional Commits Parser for pull/merge request identifier detection. See Common Linked Merge Request Detection for details.

    •   Linked Issue Identifier Detection: Once package-specific commit filtering is applied, the relevant commits are passed to the Conventional Commits Parser for linked issue identifier detection. See Common Issue Identifier Detection for details.

    •   Squash Commit Evaluation: Squashed commits are separated out into individual commits with the same set of changed files BEFORE the package-specific commit filtering is applied. Each pseudo-commit is then subjected to the same filtering rules as regular commits. See Common Squash Commit Evaluation for details.

    •   Release Notice Footer Detection: Once package-specific commit filtering is applied, the relevant commits are passed to the Conventional Commits Parser for release notice footer detection. See Common Release Notice Footer Detection for details.

Limitations:

    •   revert commit type is NOT supported, see Conventional Commits Parser's limitations for details.

If no commit parser options are provided via the configuration, the parser will use PSR's built-in defaults <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions>.

----

  Angular Commit Parser

Warning:
        This parser was deprecated in v9.19.0. It will be removed in a future release. This parser is being replaced by the Conventional Commits Parser.

A parser that is designed to parse commits formatted according to the Angular Commit Style Guidelines <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits>. The parser is implemented with the following logic in relation to how PSR's core features:

    •   Version Bump Determination: This parser extracts the commit type from the subject line of the commit (the first line of a commit message). This type is matched against the configuration mapping to determine the level bump for the specific commit. If the commit type is not found in the configuration mapping, the commit is considered a non-parsable commit and will return it as a ParseError object and ultimately a commit of type "unknown". The configuration mapping contains lists of commit types that correspond to the level bump for each commit type. Some commit types are still valid do not trigger a level bump, such as "chore" or "docs". You can also configure the default level bump commit_parser_options.default_level_bump <#config-commit-parser-options> if desired. To trigger a major release, the commit message body must contain a paragraph that begins with BREAKING CHANGE:. This will override the level bump determined by the commit type.

    •   Changelog Generation: PSR will group commits in the changelog by the commit type used in the commit message. The commit type shorthand is converted to a more human-friendly section heading and then used as the version section title of the changelog and release notes. Under the section title, the parsed commit descriptions are listed out in full. If the commit includes an optional scope, then the scope is prefixed on to the first line of the commit description. If a commit has any breaking change prefixed paragraphs in the commit message body, those paragraphs are separated out into a "Breaking Changes" section in the changelog (Breaking Changes section is available from the default changelog in v9.15.0). Each breaking change paragraph is listed in a bulleted list format across the entire version. A single commit is allowed to have more than one breaking change prefixed paragraph (as opposed to the Angular Commit Style Guidelines <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits>). Commits with an optional scope and a breaking change will have the scope prefixed on to the breaking change paragraph. Parsing errors will return a ParseError object and ultimately a commit of type "unknown". Unknown commits are consolidated into an "Unknown" section in the changelog by the default template. To remove unwanted commits from the changelog that normally are placed in the "unknown" section, consider the use of the configuration option changelog.exclude_commit_patterns <#config-changelog-exclude-commit-patterns> to ignore those commit styles.

    •   Pull/Merge Request Identifier Detection: This parser implements PSR's Common Linked Merge Request Detection to identify and extract pull/merge request numbers. The parser will return a string value if a pull/merge request number is found in the commit message. If no pull/merge request number is found, the parser will return an empty string. Feature available in v9.13.0+.

    •   Linked Issue Identifier Detection: This parser implements PSR's Common Issue Identifier Detection to identify and extract issue numbers. The parser will return a tuple of issue numbers as strings if any are found in the commit message. If no issue numbers are found, the parser will return an empty tuple. Feature available in v9.15.0+.

    •   Squash Commit Evaluation: This parser implements PSR's Common Squash Commit Evaluation to identify and extract each commit message as a separate commit message within a single squashed commit. You can toggle this feature on/off via the commit_parser_options <#config-commit-parser-options> setting. Feature available in v9.17.0+.

    •   Release Notice Footer Detection: This parser implements PSR's Common Release Notice Footer Detection, which is a custom extension to traditional Angular Commit Style Guidelines <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits> to use the NOTICE keyword as a git footer to document additional release information that is not considered a breaking change. Feature available in v9.18.0+.

Limitations:

    •   Commits with the revert type are not currently supported. Track the implementation of this feature in the issue #402 <https://github.com/python-semantic-release/python-semantic-release/issues/402>.

If no commit parser options are provided via the configuration, the parser will use PSR's built-in defaults <#semantic_release.commit_parser.angular.AngularParserOptions>.

----

  Emoji Commit Parser

A parser that is designed to parse commits formatted to the Gitmoji Specification <https://gitmoji.dev/specification> with a few additional features that the specification does not cover but provide similar functionality expected from a Semantic Release tool. As the Gitmoji Specification <https://gitmoji.dev/specification> describes, the emojis can be specified in either the unicode format or the shortcode text format. See the Gitmoji Specification <https://gitmoji.dev/specification> for the pros and cons for which format to use, but regardless, the configuration options must match the format used in the commit messages. The parser is implemented with the following logic in relation to how PSR's core features:

    •   Version Bump Determination: This parser only looks for emojis in the subject line of the commit (the first line of a commit message). If more than one emoji is found, the emoji configured with the highest priority is selected for the change impact for the specific commit. The emoji with the highest priority is the one configured in the major configuration option, followed by the minor, and patch in descending priority order. If no emoji is found in the subject line, the commit is classified as other and will default to the level bump defined by the configuration option commit_parser_options.default_level_bump <#config-commit-parser-options>.

    •   Changelog Generation: PSR will group commits in the changelog by the emoji type used in the commit message. The emoji is used as the version section title and the commit descriptions are listed under that section. No emojis are removed from the commit message so each will be listed in the changelog and release notes. When more than one emoji is found in the subject line of a commit, the emoji with the highest priority is the one that will influence the grouping of the commit in the changelog. Commits containing no emojis or non-configured emojis are consolidated into an "Other" section. To remove unwanted commits from the changelog that would normally be added into the "other" section, consider the use of the configuration option changelog.exclude_commit_patterns <#config-changelog-exclude-commit-patterns> to ignore those commit styles.

    •   Pull/Merge Request Identifier Detection: This parser implements PSR's Common Linked Merge Request Detection to identify and extract pull/merge request numbers. The parser will return a string value if a pull/merge request number is found in the commit message. If no pull/merge request number is found, the parser will return an empty string. Feature available in v9.13.0+.

    •   Linked Issue Identifier Detection: [Disabled by default] This parser implements PSR's Common Issue Identifier Detection to identify and extract issue numbers. The parser will return a tuple of issue numbers as strings if any are found in the commit message. If no issue numbers are found, the parser will return an empty tuple. This feature is disabled by default since it is not a part of the Gitmoji Specification <https://gitmoji.dev/specification> but can be enabled by setting the configuration option commit_parser_options.parse_linked_issues to true. Feature available in v9.15.0+.

    •   Squash Commit Evaluation: This parser implements PSR's Common Squash Commit Evaluation to identify and extract each commit message as a separate commit message within a single squashed commit. You can toggle this feature on/off via the commit_parser_options <#config-commit-parser-options> setting. Feature available in v9.17.0+.

    •   Release Notice Footer Detection: This parser implements PSR's Common Release Notice Footer Detection, which is a custom extension that uses the NOTICE keyword as a git footer to document additional release information that is not considered a breaking change. Feature available in v9.18.0+.

If no commit parser options are provided via the configuration, the parser will use PSR's built-in defaults <#semantic_release.commit_parser.emoji.EmojiParserOptions>.

----

  Scipy Commit Parser

A parser that is designed to parse commits formatted according to the Scipy Commit Style Guidelines <https://scipy.github.io/devdocs/dev/contributor/development_workflow.html#writing-the-commit-message>. This is essentially a variation of the Angular Commit Style Guidelines <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits> with all different commit types. Because of this small variance, this parser only extends our Angular Commit Parser parser with pre-defined scipy commit types in the default Scipy Parser Options and all other features are inherited.

Limitations:

    •   Commits with the REV type are not currently supported. Track the implementation of this feature in the issue #402 <https://github.com/python-semantic-release/python-semantic-release/issues/402>.

If no commit parser options are provided via the configuration, the parser will use PSR's built-in defaults <#semantic_release.commit_parser.scipy.ScipyParserOptions>.

----

  Tag Commit Parser

Warning:
        This parser was deprecated in v9.12.0. It will be removed in a future release.

The original parser from v1.0.0 of Python Semantic Release. Similar to the emoji parser above, but with less features.

If no commit parser options are provided via the configuration, the parser will use PSR's built-in defaults <#semantic_release.commit_parser.tag.TagParserOptions>.

----

  Common Linked Merge Request Detection

Introduced in v9.13.0

All of the PSR built-in parsers implement common pull/merge request identifier detection logic to extract pull/merge request numbers from the commit message regardless of the VCS platform. The parsers evaluate the subject line for a parenthesis-enclosed number at the end of the line. PSR's parsers will return a string value if a pull/merge request number is found in the commit message. If no pull/merge request number is found, the parsers will return an empty string.

Examples:

All of the following will extract a MR number of "x123", where 'x' is the character prefix

    1.  BitBucket: Merged in feat/my-awesome-feature (pull request #123)

    2.  GitHub: feat: add new feature (#123)

    3.  GitLab: fix: resolve an issue (!123)

----

  Common Issue Identifier Detection

Introduced in v9.15.0

All of the PSR built-in parsers implement common issue identifier detection logic, which is similar to many VCS platforms such as GitHub, GitLab, and BitBucket. The parsers will look for common issue closure text prefixes in the Git Trailer format <https://git-scm.com/docs/git-interpret-trailers> in the commit message to identify and extract issue numbers. The detection logic is not strict to any specific issue tracker as we try to provide a flexible approach to identifying issue numbers but in order to be flexible, it is required to the use the Git Trailer format <https://git-scm.com/docs/git-interpret-trailers> with a colon (:) as the token separator.

PSR attempts to support all variants of issue closure text prefixes, but not all will work for your VCS. PSR supports the following case-insensitive prefixes and their conjugations (plural, present, & past tense):

    •   close (closes, closing, closed)

    •   fix (fixes, fixing, fixed)

    •   resolve (resolves, resolving, resolved)

    •   implement (implements, implementing, implemented)

PSR also allows for a more flexible approach to identifying more than one issue number without the need of extra git trailers (although PSR does support multiple git trailers). PSR support various list formats which can be used to identify more than one issue in a list. This format will not necessarily work on your VCS. PSR currently support the following list formats:

    •   comma-separated (ex. Closes: #123, #456, #789)

    •   space-separated (ex. resolve: #123 #456 #789)

    •   semicolon-separated (ex. Fixes: #123; #456; #789)

    •   slash-separated (ex. close: #123/#456/#789)

    •   ampersand-separated (ex. Implement: #123 & #789)

    •   and-separated (ex. Resolve: #123 and #456 and #789)

    •   mixed (ex. Closed: #123, #456, and #789 or Fixes: #123, #456 & #789)

All the examples above use the most common issue number prefix (#) but PSR is flexible to support other prefixes used by VCS platforms or issue trackers such as JIRA (ex. ABC-###).

The parsers will return a tuple of issue numbers as strings if any are found in the commit message. Strings are returned to ensure that the any issue number prefix characters are preserved (ex. #123 or ABC-123). If no issue numbers are found, the parsers will return an empty tuple.

References:

    •   BitBucket: Resolving Issues Automatically <https://support.atlassian.com/bitbucket-cloud/docs/resolve-issues-automatically-when-users-push-code/>

    •   GitHub: Linking Issue to PR <https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue>

    •   GitLab: Default Closing Patterns <https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#default-closing-pattern>

----

  Common Release Notice Footer Detection

Introduced in v9.18.0*

All of the PSR built-in parsers implement common release notice footer detection logic to identify and extract a NOTICE git trailer that documents any additional release information the developer wants to provide to the software consumer. The idea extends from the concept of the BREAKING CHANGE: git trailer to document any breaking change descriptions but the NOTICE trailer is intended to document any information that is below the threshold of a breaking change while still important for the software consumer to be aware of. Common uses would be to provide deprecation warnings or more detailed change usage information for that release. Parsers will collapse single newlines after the NOTICE trailer into a single line paragraph. Commits may have more than one NOTICE trailer in a single commit message. Each ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> will have a release_notices attribute that is a tuple of string paragraphs to identify each release notice.

In the default changelog and release notes template, these release notices will be formatted into their own section called Additional Release Information. Each will include any commit scope defined and each release notice in alphabetical order.

----

  Common Squash Commit Evaluation

Introduced in v9.17.0

All of the PSR built-in parsers implement common squash commit evaluation logic to identify and extract individual commit messages from a single squashed commit. The parsers will look for common squash commit delimiters and multiple matches of the commit message format to identify each individual commit message that was squashed. The parsers will return a list containing each commit message as a separate commit object. Squashed commits will be evaluated individually for both the level bump and changelog generation. If no squash commits are found, a list with the single commit object will be returned.

Currently, PSR has been tested against GitHub, BitBucket, and official git squash merge commit messages. GitLab does not have a default template for squash commit messages but can be customized per project or server. If you are using GitLab, you will need to ensure that the squash commit message format is similar to the example below.

Example:

The following example will extract three separate commit messages from a single GitHub formatted squash commit message of conventional commit style:

            feat(config): add new config option (#123)

            * refactor(config): change the implementation of config loading

            * docs(configuration): defined new config option for the project

When parsed with the default conventional-commit parser with squash commits toggled on, the version bump will be determined by the highest level bump of the three commits (in this case, a minor bump because of the feature commit) and the release notes would look similar to the following:

            ## Features

            - **config**: add new config option (#123)

            ## Documentation

            - **configuration**: defined new config option for the project (#123)

            ## Refactoring

            - **config**: change the implementation of config loading (#123)

Merge request numbers and commit hash values will be the same across all extracted commits. Additionally, any exclude_commit_patterns <#config-changelog-exclude-commit-patterns> will be applied individually to each extracted commit so if you are have an exclusion match for ignoring refactor commits, the second commit in the example above would be excluded from the changelog.

Important:
        When squash commit evaluation is enabled, if you squashed a higher level bump commit into the body of a lower level bump commit, the higher level bump commit will be evaluated as the level bump for the entire squashed commit. This includes breaking change descriptions.

----

  Customization

Each of the built-in parsers can be customized by providing overrides in the commit_parser_options <#config-commit-parser-options> setting of the configuration file. This can be used to toggle parsing features on and off or to add, modify, or remove the commit types that are used to determine the level bump for a commit. Review the API documentation for the specific parser's options class to see what changes to the default behavior can be made.

----

  Custom Parsers

Custom parsers can be written to handle commit message styles that are not covered by the built-in parsers or by option customization of the built-in parsers.

Python Semantic Release provides several building blocks to help you write your parser. To maintain compatibility with how Python Semantic Release will invoke your parser, you should use the appropriate object as described below, or create your own object as a subclass of the original which maintains the same interface. Type parameters are defined where appropriate to assist with static type-checking.

The commit_parser <#config-commit-parser> option, if set to a string which does not match one of Python Semantic Release's built-in commit parsers, will be used to attempt to dynamically import a custom commit parser class.

In order to use your custom parser, you must provide how to import the module and class via the configuration option. There are two ways to provide the import string:

    1.  File Path & Class: The format is "path/to/module_file.py:ClassName". This is the easiest way to provide a custom parser. This method allows you to store your custom parser directly in the repository with no additional installation steps. PSR will locate the file, load the module, and instantiate the class. Relative paths are recommended and it should be provided relative to the current working directory. This import variant is available in v9.16.0 and later.

    2.  Module Path & Class: The format is "package.module_name:ClassName". This method allows you to store your custom parser in a package that is installed in the same environment as PSR. This method is useful if you want to share your custom parser across multiple repositories. To share it across multiple repositories generally you will need to publish the parser as its own separate package and then pip install it into the current virtual environment. You can also keep it in the same repository as your project as long as it is in the current directory of the virtual environment and is locatable by the Python import system. You may need to set the PYTHONPATH environment variable if you have a more complex directory structure. This import variant is available in v8.0.0 and later.

        To test that your custom parser is importable, you can run the following command in the directory where PSR will be executed:

                python -c "from package.module_name import ClassName"

    Note:
            Remember this is basic python import rules so the package name is optional and generally packages are defined by a directory with __init__.py files.

  Tokens

The tokens built into Python Semantic Release's commit parsing mechanism are inspired by both the error-handling mechanism in Rust's error handling <https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html> and its implementation in black <https://github.com/psf/black/blob/main/src/black/rusty.py>. It is documented that catching exceptions in Python is slower <https://docs.python.org/3/faq/design.html#how-fast-are-exceptions> than the equivalent guard implemented using if/else checking when exceptions are actually caught, so although try/except blocks are cheap if no exception is raised, commit parsers should always return an object such as ParseError <#semantic_release.commit_parser.token.ParseError> instead of raising an error immediately. This is to avoid catching a potentially large number of parsing errors being caught as the commit history of a repository is being parsed. Python Semantic Release does not raise an exception if a commit cannot be parsed.

Python Semantic Release uses ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> as the return type of a successful parse operation, and ParseError <#semantic_release.commit_parser.token.ParseError> as the return type from an unsuccessful parse of a commit. You should review the API documentation linked to understand the fields available on each of these objects.

It is important to note, the ParseError <#semantic_release.commit_parser.token.ParseError> implements an additional method, raise_error. This method raises a CommitParseError <#semantic_release.errors.CommitParseError> with the message contained in the error field, as a convenience.

In Python Semantic Release, the type semantic_release.commit_parser.token.ParseResult is defined as ParseResultType[ParsedCommit, ParseError], as a convenient shorthand.

ParseResultType is a generic type, which is the Union of its two type parameters. One of the types in this union should be the type returned on a successful parse of the commit, while the other should be the type returned on an unsuccessful parse of the commit.

A custom parser result type, therefore, could be implemented as follows:

    •   MyParsedCommit subclasses ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit>

    •   MyParseError subclasses ParseError <#semantic_release.commit_parser.token.ParseError>

    •   MyParseResult = ParseResultType[MyParsedCommit, MyParseError]

Internally, Python Semantic Release uses isinstance() to determine if the result of parsing a commit was a success or not, so you should check that your custom result and error types return True from isinstance(<object>, ParsedCommit) and isinstance(<object>, ParseError) respectively.

While it's not advisable to remove any of the fields that are available in the built-in token types, currently only the bump field of the successful result type is used to determine how the version should be incremented as part of this release. However, it's perfectly possible to add additional fields to your tokens which can be populated by your parser; these fields will then be available on each commit in your changelog template <#changelog-templates>, so you can make additional information available.

  Parser Options

When writing your own parser, you should accompany the parser with an "options" class which accepts the appropriate keyword arguments. This class' __init__ method should store the values that are needed for parsing appropriately. Python Semantic Release will pass any configuration options from the configuration file's commit_parser_options <#config-commit-parser-options>, into your custom parser options class. To ensure that the configuration options are passed correctly, the options class should inherit from the ParserOptions class.

The "options" class is used to validate the options which are configured in the repository, and to provide default values for these options where appropriate.

  Commit Parsers

The commit parsers that are built into Python Semantic Release implement an instance method called parse, which takes a single parameter commit of type git.objects.commit.Commit <gitpython-commit-object>, and returns the type ParseResultType.

To be compatible with Python Semantic Release, a commit parser must subclass CommitParser. A subclass must implement the following:

    •   A class-level attribute parser_options, which must be set to ParserOptions or a subclass of this.

    •   An __init__ method which takes a single parameter, options, that should be of the same type as the class' parser_options attribute.

    •   A method, parse, which takes a single parameter commit that is of type git.objects.commit.Commit <gitpython-commit-object>, and returns ParseResult, or a subclass of this.

By default, the constructor for CommitParser will set the options parameter on the options attribute of the parser, so there is no need to override this in order to access self.options during the parse method. However, if you have any parsing logic that needs to be done only once, it may be a good idea to perform this logic during parser instantiation rather than inside the parse method. The parse method will be called once per commit in the repository's history during parsing, so the effect of slow parsing logic within the parse method will be magnified significantly for projects with sizeable Git histories.

Commit Parsers have two type parameters, "TokenType" and "OptionsType". The first is the type which is returned by the parse method, and the second is the type of the "options" class for this parser.

Therefore, a custom commit parser could be implemented via:

            class MyParserOptions(semantic_release.ParserOptions):
                def __init__(self, message_prefix: str) -> None:
                    self.prefix = message_prefix * 2

            class MyCommitParser(
                semantic_release.CommitParser[semantic_release.ParseResult, MyParserOptions]
            ):
                def parse(self, commit: git.objects.commit.Commit) -> semantic_release.ParseResult:
                    ...

  Version Change Reports

When using the cmd-version and cmd-changelog commands, Python Semantic Release (PSR) will generate a changelog and release notes for your project automatically in the default configuration. The changelog is rendered using the Jinja <https://jinja.palletsprojects.com/en/3.1.x/> template engine, and in the default configuration, PSR will use a built-in template file to render the changelog at the file location defined by the changelog_file <#config-changelog-changelog-file> setting.

Through the use of the templating engine & the template_dir <#config-changelog-template-dir> configuration setting, you can customize the appearance of your changelog and release notes content. You may also generate a set of files using your custom template directory and the templates will be rendered relative to the root of your repository.

Because PSR uses a third-party library, Jinja <https://jinja.palletsprojects.com/en/3.1.x/>, as its template engine, we do not include all the syntax within our documentation but rather you should refer to the Template Designer Documentation <https://jinja.palletsprojects.com/en/3.1.x/templates/> for guidance on how to customize the appearance of your release files. If you would like to customize the template environment itself, then certain options are available to you via changelog environment configuration <#config-changelog-environment>.

If you do not want to use the changelog generation features, you can disable changelog generation entirely during the cmd-version command by providing the --no-changelog command-line option.

  Using the Default Changelog

If you don't provide any custom templates in the changelog.template_dir <#config-changelog-template-dir>, the default changelog templates will be used to render the changelog.

PSR provides two default changelog output formats:

    1.  Markdown (.md), default

    2.  reStructuredText (.rst), available since v9.11.0

Both formats are kept in sync with one another to display the equivalent information in the respective format. The default changelog template is located in the data/templates/ directory within the PSR package. The templates are written in modular style (ie. multiple files) and during the render process are ultimately combined together to render the final changelog output. The rendering start point is the CHANGELOG.{FORMAT_EXT}.j2 underneath the respective format directory.

PSR provides a few configuration options to customize the default changelog output and can be found under the changelog.default_templates <#config-changelog-default-templates> section as well as some common configuration options under the changelog <#config-changelog> section.

To toggle the output format, you only need to set the changelog.default_templates.changelog_file <#config-changelog-default-templates-changelog-file> file name to include the desired file extension (.md or .rst). If you would like a different extension for the resulting changelog file, but would like to still have control over the template format, you can set the changelog.default_templates.output_format <#config-changelog-default-templates-output-format> configuration setting to the desired format.

A common and highly-recommended configuration option is the changelog.exclude_commit_patterns <#config-changelog-exclude-commit-patterns> setting which allows the user to define regular expressions that will exclude commits from the changelog output. This is useful to filter out change messages that are not relevant to your external consumers (ex. ci and test in the conventional commit standard) and only include the important changes that impact the consumer of your software.

Another important configuration option is the changelog.mode <#config-changelog-mode> setting which determines the behavior of the changelog generation. There are 2 modes that available that described in detail below.

    1.  Initialization Mode when mode = "init".

    2.  Update Mode when mode = "update".

  Initialization Mode

When using the initialization mode, the changelog file will be created from scratch using the entire git history and overwrite any existing changelog file. This is the default behavior introduced in v8.0.0. This is useful when you are trying to convert over to Python Semantic Release for the first time or when you want to automatically update the entire format of your changelog file.

Warning:
        If you have an existing changelog in the location you have configured with the changelog.changelog_file <#config-changelog-changelog-file> setting, PSR will overwrite the contents of this file on each release.

        Please make sure to refer to Migrating an Existing Changelog.

  Update Mode

Note:
        Introduced in v9.10.0.

When using the update mode, only the change information from the last release will be prepended into the existing changelog file (defined by the changelog.changelog_file <#config-changelog-changelog-file>). This mimics the behavior that was used in versions prior to v8.0.0 before the conversion to a templating engine but now uses the Jinja <https://jinja.palletsprojects.com/en/3.1.x/> to accomplish the update. This mode is best suited for managing changes over the lifetime of your project when you may have a need to make manual changes or adjustments to the changelog and its not easily recreated with a template.

How It Works

In order to insert the new release information into an existing changelog file, your changelog file must have an insertion flag to indicate where the new release information should be inserted. The default template will read in your existing changelog file, split the content based on the insertion flag, and then recombine the content (including the insertion flag) with the new release information added after the insertion flag.

The insertion flag is customizable through the changelog.insertion_flag <#config-changelog-insertion-flag> setting. Generally, your insertion flag should be unique text to your changelog file to avoid any unexpected behavior. See the examples below.

In the case where the insertion flag is NOT found in the existing changelog file, the changelog file will be re-written without any changes.

If there is no existing changelog file found, then the changelog file will be initialized from scratch as if the mode was set to init, except the changelog.insertion_flag <#config-changelog-insertion-flag> will be included into the newly created changelog file.

Tip:
        We have accomplished changelog updating through the use of the Jinja <https://jinja.palletsprojects.com/en/3.1.x/> templating and additional context filters and context variables. This is notable because in the case that you want to customize your changelog template, you now can use the same logic to enable changelog updates of your custom template!

See also:

            •   Migrating an Existing Changelog.

Example

Given your existing changelog looks like the following with a changelog.insertion_flag <#config-changelog-insertion-flag> set to <!-- version list -->, when you run the cmd-version command, the new release information will be inserted after the insertion flag.

Before

            # CHANGELOG

            <!-- version list -->

            ## 1.0.0

            - Initial Release

After

            # CHANGELOG

            <!-- version list -->

            ## v1.1.0

            ### Feature

            - feat: added a new feature

            ### Fix

            - fix: resolved divide by zero error

            ## 1.0.0

            - Initial Release

  Configuration Examples

    1.  Goal: Configure an updating reStructuredText changelog with a custom insertion flag within pyproject.toml.

                [tool.semantic_release.changelog]
                mode = "update"
                insertion_flag = "..\n    All versions below are listed in reverse chronological order"

                [tool.semantic_release.changelog.default_templates]
                changelog_file = "CHANGELOG.rst"
                output_format = "rst"  # optional because of the file extension

    2.  Goal: Configure an updating Markdown changelog with custom file name and default insertion flag within a separate config file releaserc.json.

                {
                  "semantic_release": {
                    "changelog": {
                      "mode": "update",
                      "default_templates": {
                        "changelog_file": "docs/HISTORY",
                        "output_format": "md"
                      }
                    }
                  }
                }

    3.  Goal: Configure an initializing reStructuredText changelog with filtered conventional commits patterns and merge commits within a custom config file releaserc.toml.

                [semantic_release.changelog]
                mode = "init"
                default_templates = { changelog_file = "docs/CHANGELOG.rst" }
                exclude_commit_patterns = [
                  '''chore(?:\([^)]*?\))?: .+''',
                  '''ci(?:\([^)]*?\))?: .+''',
                  '''refactor(?:\([^)]*?\))?: .+''',
                  '''style(?:\([^)]*?\))?: .+''',
                  '''test(?:\([^)]*?\))?: .+''',
                  '''build\((?!deps\): .+)''',
                  '''Merged? .*''',
                ]

If identified or supported by the parser, the default changelog templates will include a separate section of breaking changes and additional release information. Refer to the commit parsing <#commit-parsing> section to see how to write commit messages that will be properly parsed and displayed in these sections.

  Using the Default Release Notes

PSR has the capability to generate release notes as part of the publishing of a new version similar to the changelog. The release notes are generated using a Jinja <https://jinja.palletsprojects.com/en/3.1.x/> template and posted to the your remote version control server (VCS) such as GitHub, GitLab, etc during the cmd-version command. PSR provides a default built-in template out-of-the-box for generating release notes.

The difference between the changelog and release notes is that the release notes only contain the changes for the current release. Due to the modularity of the PSR templates, the format is similar to an individual version of the default changelog but may include other version specific information.

At this time, the default template for version release notes is only available in Markdown format for all VCS types.

If you want to review what the default release notes look like you can use the following command to print the release notes to the console (remove any configuration for defining a custom template directory):

            # Create a current tag
            git tag v1.0.0
            semantic-release --noop changelog --post-to-release-tag v1.0.0

The default template provided by PSR will respect the mask_initial_release <#config-changelog-default-templates-mask-initial-release> setting and will also add a comparison link to the previous release if one exists without customization.

As of v9.18.0, the default release notes will also include a statement to declare which license the project was released under. PSR determines which license to declare based on the value of project.license-expression in the pyproject.toml file as defined in the PEP 639 <https://peps.python.org/pep-0639/> specification.

See also:

            •   To personalize your release notes, see the Custom Release Notes section.

  Custom Changelogs

If you would like to customize the appearance of your changelog, you can create your own custom templates and configure PSR to render your templates instead during the cmd-version and cmd-changelog commands.

To use a custom template, you need to create a directory within your repository and set the template_dir <#config-changelog-template-dir> setting to the name of this directory. The default name is "templates".

Templates are identified by giving a .j2 extension to the template file. Any such templates have the .j2 extension removed from the target file. Therefore, to render an output file foo.csv, you should create a template called foo.csv.j2 within your template directory.

If you have additional files that you would like to render alongside your changelog, you can place these files within the template directory. A file within your template directory which does not end in .j2 will not be treated as a template; it will be copied to its target location without being rendered by the template engine.

Tip:
        Hidden files within the template directory (i.e. filenames that begin with a period ".") are excluded from the rendering process. Hidden folders within the template directory are also excluded, along with all files and folders contained within them. This is useful for defining macros or other template components that should not be rendered individually.

Tip:
        When initially starting out at customizing your own changelog templates, you should reference the default template embedded within PSR. The template directory is located at data/templates/ within the PSR package. Within our templates directory we separate out each type of commit parser (e.g. conventional) and the content format type (e.g. markdown). You can copy this directory to your repository's templates directory and then customize the templates to your liking.

  Directory Structure

When the templates are rendered, files within the templates directory tree are output to the location within your repository that has the same relative path to the root of your project as the relative path of the template within the templates directory.

Example

An example project has the following structure:

            example-project/
            ├── src/
            │   └── example_project/
            │       └── __init__.py
            └── ch-templates/
                ├── CHANGELOG.md.j2
                ├── .components/
                │   └── authors.md.j2
                ├── .macros.j2
                ├── src/
                │   └── example_project/
                │       └── data/
                │           └── data.json.j2
                └── static/
                    └── config.cfg

And a custom templates folder configured via the following snippet in pyproject.toml:

            [tool.semantic_release.changelog]
            template_dir = "ch-templates"

After running a release with Python Semantic Release, the directory structure of the project will now look like this (excluding the template directory):

            example-project/
            ├── CHANGELOG.md
            ├── src/
            │   └── example_project/
            │       ├── data/
            │       │   └── data.json
            │       └── __init__.py
            └── static/
                └── config.cfg

Importantly, note the following:

    •   There is no top-level .macros file created, because hidden files are excluded from the rendering process.

    •   There is no top-level .components directory created, because hidden folders and all files and folders contained within it are excluded from the rendering process.

    •   The .components/authors.md.j2 file is not rendered directly, however, it is used as a component to the CHANGELOG.md.j2 via an include statement in the changelog template.

    •   To render data files into the src/ folder, the path to which the template should be rendered has to be created within the ch-templates directory.

    •   The ch-templates/static folder is created at the top-level of the project, and the file ch-templates/static/config.cfg is copied, not rendered to the new top-level static folder.

You may wish to leverage this behavior to modularize your changelog template, to define macros in a separate file, or to reference static data which you would like to avoid duplicating between your template environment and the remainder of your project.

  Changelog Template Context

During the rendering of a directory tree, Python Semantic Release provides information about the history of the project available within the templating environment in order for it to be used to generate the changelog and other desired documents.

Important project information is provided to the templating environment through the global variable context or ctx for short. Within the template environment, the context object has the following attributes:

    •   changelog_insertion_flag (str): the insertion flag used to determine where the new release information should be inserted into the changelog file. This value is passed directly from changelog.insertion_flag <#config-changelog-insertion-flag>.

        Introduced in v9.10.0.

        Example Usage:

                {%  set changelog_parts = prev_changelog_contents.split(
                        ctx.changelog_insertion_flag, maxsplit=1
                    )
                %}

    •   changelog_mode (Literal["init", "update"]): the mode of the changelog generation currently being used. This can be used to determine different rendering logic. This value is passed directly from the changelog.mode <#config-changelog-mode> configuration setting.

        Introduced in v9.10.0.

        Example Usage:

                {%    if ctx.changelog_mode == "init"
                %}{%    include ".changelog_init.md.j2"
                %}{#
                #}{%  elif ctx.changelog_mode == "update"
                %}{%    include ".changelog_update.md.j2"
                %}{#
                #}{%  endif
                %}

    •   history (ReleaseHistory): the ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory> instance for the project (See the Release History section for more information).

        Example Usage:

                {%    set unreleased_commits = ctx.history.unreleased | dictsort
                %}{%  for release in context.history.released.values()
                %}{%    include ".versioned_changes.md.j2"
                #}{%  endfor
                %}

    •   hvcs_type (str): the name of the VCS server type currently configured. This can be used to determine which filters are available or different rendering logic.

        Introduced in v9.6.0.

        Example Usage:

                {%    if ctx.hvcs_type == "github"
                %}{{   "29" | pull_request_url
                }}{#
                #}{%  elif ctx.hvcs_type == "gitlab"
                %}{{    "29" | merge_request_url
                }}{#
                #}{%  endif
                %}

    •   mask_initial_release (bool): a boolean value indicating whether the initial release should be masked with a generic message. This value is passed directly from the changelog.default_templates.mask_initial_release <#config-changelog-default-templates-mask-initial-release> configuration setting.

        Introduced in v9.14.0.

        Example Usage:

                #}{%  if releases | length == 1 and ctx.mask_initial_release
                %}{#    # On a first release, generate a generic message
                #}{%    include ".components/first_release.md.j2"
                %}{%  else
                %}{#    # Not the first release
                #}{%    include ".components/versioned_changes.md.j2"
                %}{%  endif
                %}

    •   repo_name (str): the name of the current repository parsed from the Git url.

        Example Usage:

                {{ ctx.repo_name }}

                example_repo

    •   repo_owner (str): the owner of the current repository parsed from the Git url.

        Example Usage:

                {{ ctx.repo_owner }}

                example_org

    •   prev_changelog_file (str): the path to the previous changelog file that should be updated with the new release information. This value is passed directly from changelog.changelog_file <#config-changelog-changelog-file>.

        Introduced in v9.10.0.

        Example Usage:

                {% set prev_changelog_contents = prev_changelog_file | read_file | safe %}

  Release History

A ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory> object has two attributes: released and unreleased.

The unreleased attribute is of type Dict[str, List[ParseResult]]. Each commit in the current branch's commit history since the last release on this branch is grouped by the type attribute of the ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> returned by the commit parser, or if the parser returned a ParseError <#semantic_release.commit_parser.token.ParseError> then the result is grouped under the "unknown" key.

For this reason, every element of ReleaseHistory.unreleased["unknown"] is a ParseError <#semantic_release.commit_parser.token.ParseError>, and every element of every other value in ReleaseHistory.unreleased is of type ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit>.

Typically, commit types will be "feature", "fix", "breaking", though the specific types are determined by the parser. For example, the EmojiCommitParser <#semantic_release.commit_parser.emoji.EmojiCommitParser> uses a textual representation of the emoji corresponding to the most significant change introduced in a commit (e.g. ":boom:") as the different commit types. As a template author, you are free to customize how these are presented in the rendered template.

Note:
        If you are using a custom commit parser following the guide at Custom Parsers <#commit-parser-custom-parser>, your custom implementations of ParseResult, ParseError <#semantic_release.commit_parser.token.ParseError> and ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> will be used in place of the built-in types.

The released attribute is of type Dict[Version, Release]. The keys of this dictionary correspond to each version released within this branch's history, and are of type Version <#semantic_release.version.version.Version>. You can use the as_tag() method to render these as the Git tag that they correspond to inside your template.

A Release <#semantic_release.changelog.release_history.Release> object has an elements attribute, which has the same structure as the unreleased attribute of a ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>; that is, elements is of type Dict[str, List[ParseResult]], where every element of elements["unknown"] is a ParseError <#semantic_release.commit_parser.token.ParseError>, and elements of every other value correspond to the type attribute of the ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> returned by the commit parser.

The commits represented within each ReleaseHistory.released[version].elements grouping are the commits which were made between version and the release corresponding to the previous version. That is, given two releases Version(1, 0, 0) and Version(1, 1, 0), ReleaseHistory.released[Version(1, 0, 0)].elements contains only commits made after the release of Version(1, 0, 0) up to and including the release of Version(1, 1, 0).

To maintain a consistent order of subsections in the changelog headed by the commit type, it's recommended to use Jinja's dictsort <https://jinja.palletsprojects.com/en/3.1.x/templates/#jinja-filters.dictsort> filter.

Each Release <#semantic_release.changelog.release_history.Release> object also has the following attributes:

    •   tagger: git.Actor: The tagger who tagged the release.

    •   committer: git.Actor: The committer who made the release commit.

    •   tagged_date: datetime: The date and time at which the release was tagged.

See also:

            •   Built-in Commit Parsers <#commit-parser-builtin>

            •   Commit Parser Tokens <#commit-parser-tokens>

            •   git.Actor <https://gitpython.readthedocs.io/en/stable/reference.html#git.objects.util.Actor>

            •   datetime.strftime Format Codes <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes>

  Changelog Template Filters

In addition to the context variables, PSR seeds the template environment with a set of custom functions (commonly called filters in Jinja <https://jinja.palletsprojects.com/en/3.1.x/> terminology) for use within the template. Filter's first argument is always piped (|) to the function while any additional arguments are passed in parentheses like normal function calls.

The filters provided vary based on the VCS configured and available features:

    •   autofit_text_width (Callable[[textStr, maxWidthInt, indent_sizeInt], textStr]): given a text string, fit the text to the maximum width provided. This filter is useful when you want to wrap text to a specific width. The filter will attempt to break the text at word boundaries and will indent the text by the amount specified in the indent_size parameter.

        Introduced in v9.12.0.

        Example Usage:

                {{ "This is a long string that needs to be wrapped to a specific width" | autofit_text_width(40, 4) }}

    Markdown Output:

                This is a long string that needs to be
                    wrapped to a specific width

    •   convert_md_to_rst (Callable[[MdStr], RstStr]): given a markdown string, convert it to reStructuredText format. This filter is useful when building a reStructuredText changelog but your commit messages are in markdown format. It is utilized by the default RST changelog template. It is limited in its ability to convert all markdown to reStructuredText, but it handles most common cases (bold, italics, inline-raw, etc.) within commit messages.

        Introduced in v9.11.0.

        Example Usage:

                {{  "\n* %s (`%s`_)\n" | format(
                      commit.message.rstrip() | convert_md_to_rst,
                      commit.short_hash,
                    )
                }}

    •   create_pypi_url(package_name: str, version: str = ""): given a package name and an optional version, return a URL to the PyPI page for the package. If a version is provided, the URL will point to the specific version page. If no version is provided, the URL will point to the package page.

        Introduced in v9.18.0.

        Example Usage:

                {{ "example-package" | create_pypi_url }}
                {{ "example-package" | create_pypi_url("1.0.0") }}

    Markdown Output:

                https://pypi.org/project/example-package
                https://pypi.org/project/example-package/1.0.0

    •   create_release_url (Callable[[TagStr], UrlStr]): given a tag, return a URL to the release page on the remote vcs. This filter is useful when you want to link to the release page on the remote vcs.

        Introduced in v9.18.0.

        Example Usage:

                {{ "v1.0.0" | create_release_url }}

    Markdown Output:

                https://example.com/example/repo/releases/tag/v1.0.0

    •   create_server_url (Callable[[PathStr, AuthStr | None, QueryStr | None, FragmentStr | None], UrlStr]): when given a path, prepend the configured vcs server host and url scheme. Optionally you can provide, a auth string, a query string or a url fragment to be normalized into the resulting url. Parameter order is as described above respectively.

        Introduced in v9.6.0.

        Example Usage:

                {{ "example/repo.git" | create_server_url }}
                {{ "example/repo" | create_server_url(None, "results=1", "section-header") }}

    Markdown Output:

                https://example.com/example/repo.git
                https://example.com/example/repo?results=1#section-header

    •   create_repo_url (Callable[[RepoPathStr, QueryStr | None, FragmentStr | None], UrlStr]): when given a repository path, prepend the configured vcs server host, and repo namespace. Optionally you can provide, an additional query string and/or a url fragment to also put in the url. Parameter order is as described above respectively. This is similar to create_server_url but includes the repo namespace and owner automatically.

        Introduced in v9.6.0.

        Example Usage:

                {{ "releases/tags/v1.0.0" | create_repo_url }}
                {{ "issues" | create_repo_url("q=is%3Aissue+is%3Aclosed") }}

    Markdown Output:

                https://example.com/example/repo/releases/tags/v1.0.0
                https://example.com/example/repo/issues?q=is%3Aissue+is%3Aclosed

    •   commit_hash_url (Callable[[hashStr], UrlStr]): given a commit hash, return a URL to the commit in the remote.

        Introduced in v8.0.0.

        Example Usage:

                {{ commit.hexsha | commit_hash_url }}

    Markdown Output:

                https://example.com/example/repo/commit/a1b2c3d435657f5d339ba10c7b1ed81b460af51d

    •   compare_url (Callable[[StartRefStr, StopRefStr], UrlStr]): given a starting git reference and a ending git reference create a comparison url between the two references that can be opened on the remote

        Introduced in v9.6.0.

        Example Usage:

                {{ "v1.0.0" | compare_url("v1.1.0") }}

    Markdown Output:

                https://example.com/example/repo/compare/v1.0.0...v1.1.0

    •   issue_url (Callable[[IssueNumStr | IssueNumInt], UrlStr]): given an issue number, return a URL to the issue on the remote vcs. In v9.12.2, this filter was updated to handle a string that has leading prefix symbols (ex. #32) and will strip the prefix before generating the URL.

        Introduced in v9.6.0, Modified in v9.12.2.

        Example Usage:

                {# Add Links to issues annotated in the commit message
                 # NOTE: commit.linked_issues is only available in v9.15.0 or greater
                 #
                #}{% for issue_ref in commit.linked_issues
                %}{{     "- [%s](%s)" | format(issue_ref, issue_ref | issue_url)
                }}{% endfor
                %}

    Markdown Output:

                - [#32](https://example.com/example/repo/issues/32)

    •   merge_request_url (Callable[[MergeReqStr | MergeReqInt], UrlStr]): given a merge request number, return a URL to the merge request in the remote. This is an alias to the pull_request_url but only available for the VCS that uses the merge request terminology. In v9.12.2, this filter was updated to handle a string that has leading prefix symbols (ex. #29) and will strip the prefix before generating the URL.

        Introduced in v9.6.0, Modified in v9.12.2.

        Example Usage:

                {{
                    "[%s](%s)" | format(
                      commit.linked_merge_request,
                      commit.linked_merge_request | merge_request_url
                    )
                }}
                {# commit.linked_merge_request is only available in v9.13.0 or greater #}

    Markdown Output:

                [#29](https://example.com/example/repo/-/merge_requests/29)

    •   pull_request_url (Callable[[PullReqStr | PullReqInt], UrlStr]): given a pull request number, return a URL to the pull request in the remote. For remote vcs' that use merge request terminology, this filter is an alias to the merge_request_url filter function. In v9.12.2, this filter was updated to handle a string that has leading prefix symbols (ex. #29) and will strip the prefix before generating the URL.

        Introduced in v9.6.0, Modified in v9.12.2.

        Example Usage:

                {# Create a link to the merge request associated with the commit
                 # NOTE: commit.linked_merge_request is only available in v9.13.0 or greater
                #}{{
                    "[%s](%s)" | format(
                      commit.linked_merge_request,
                      commit.linked_merge_request | pull_request_url
                    )
                }}

    Markdown Output:

                [#29](https://example.com/example/repo/pull/29)

    •   format_w_official_vcs_name (Callable[[str], str]): given a format string, insert the official VCS type name into the string and return. This filter is useful when you want to display the proper name of the VCS type in a changelog or release notes. The filter supports three different replace formats: %s, {}, and {vcs_name}.

        Introduced in v9.18.0.

        Example Usage:

                {{ "%s Releases" | format_w_official_vcs_name }}
                {{ "{} Releases" | format_w_official_vcs_name }}
                {{ "{vcs_name} Releases" | format_w_official_vcs_name }}

    Markdown Output:

                GitHub Releases
                GitHub Releases
                GitHub Releases

    •   read_file (Callable[[str], str]): given a file path, read the file and return the contents as a string. This function was added specifically to enable the changelog update feature where it would load the existing changelog file into the templating environment to be updated.

        Introduced in v9.10.0.

        Example Usage:

                {% set prev_changelog_contents = prev_changelog_file | read_file | safe %}

    •   sort_numerically (Callable[[Iterable[str], bool], list[str]]): given a sequence of strings with possibly some non-number characters as a prefix or suffix, sort the strings as if they were just numbers from lowest to highest. This filter is useful when you want to sort issue numbers or other strings that have a numeric component in them but cannot be cast to a number directly to sort them. If you want to sort the strings in reverse order, you can pass a boolean value of True as the second argument.

        Introduced in v9.16.0.

        Example Usage:

                {{ ["#222", "#1023", "#444"] | sort_numerically }}
                {{ ["#222", "#1023", "#444"] | sort_numerically(True) }}

    Markdown Output:

                ['#222', '#444', '#1023']
                ['#1023', '#444', '#222']

Availability of the documented filters can be found in the table below:
filter - hvcs_type | bitbucket | gitea | github | gitlab
autofit_text_width | ✅ | ✅ | ✅ | ✅
convert_md_to_rst | ✅ | ✅ | ✅ | ✅
create_pypi_url | ✅ | ✅ | ✅ | ✅
create_server_url | ✅ | ✅ | ✅ | ✅
create_release_url | ❌ | ✅ | ✅ | ✅
create_repo_url | ✅ | ✅ | ✅ | ✅
commit_hash_url | ✅ | ✅ | ✅ | ✅
compare_url | ✅ | ❌ | ✅ | ✅
format_w_official_vcs_name | ✅ | ✅ | ✅ | ✅
issue_url | ❌ | ✅ | ✅ | ✅
merge_request_url | ❌ | ❌ | ❌ | ✅
pull_request_url | ✅ | ✅ | ✅ | ✅
read_file | ✅ | ✅ | ✅ | ✅
sort_numerically | ✅ | ✅ | ✅ | ✅

See also:

            •   Filters <https://jinja.palletsprojects.com/en/3.1.x/templates/#filters>

  Example

The following template is a simple example of how to render a changelog using the PSR template context to create a changelog in Markdown format.

Configuration: pyproject.toml

            [tool.semantic_release.changelog]
            template_dir = "templates"

Template: templates/CHANGELOG.md.j2

            # CHANGELOG

            {%    for version, release in ctx.history.released.items()
            %}{{
                    "## %s (%s)" | format(version.as_tag(), release.tagged_date.strftime("%Y-%m-%d"))

            }}{%    for type_, commits in release["elements"] if type_ != "unknown" | dictsort
            %}{{
                      "### %s" | format(type_ | title)

            }}{%      for commit in commits
            %}{{
                        "* %s ([`%s`](%s))" | format(
                          commit.descriptions[0] | capitalize,
                          commit.hexsha[:7],
                          commit.hexsha | commit_hash_url,
                        )

            }}{%      endfor
            %}{%    endfor
            %}{%  endfor
            %}

Result: CHANGELOG.md

            # CHANGELOG

            ## v1.1.0 (2022-01-01)

            ### Feature

            * Added a new feature ([`a1b2c3d`](https://github.com/example/repo/commit/a1b2c3d))

            ## v1.0.0 (2021-12-31)

            ### Fix

            * Resolved divide by zero error ([`e4f5g6h`](https://github.com/example/repo/commit/e4f5g6h))

It is important to note that the template utilizes the context variable to extract the project history as well as the commit_hash_url filter to generate a URL to the remote VCS for each commit. Both of these are injected into the template environment by PSR.

  Custom Release Notes

If you would like to customize the appearance of your release notes, you can add a hidden file named .release_notes.md.j2 at the root of your changelog.template_dir <#config-changelog-template-dir>. This file will automatically be detected and used to render the release notes during the cmd-version and cmd-changelog commands.

A similar template rendering mechanism is used to render the release notes as is used for the changelog. There are minor differences in the context available to the release notes template but the template directory structure and modularity is maintained.

Tip:
        When initially starting out at customizing your own release notes template, you should reference the default template embedded within PSR. The release notes template can be found in the directory data/templates/<parser>/md within the PSR package.

  Release Notes Context

All of the changelog's template context is exposed to the Jinja <https://jinja.palletsprojects.com/en/3.1.x/> template when rendering the release notes.

Additionally, the following two globals are available to the template:

    •   release (Release <#semantic_release.changelog.release_history.Release>): contains metadata about the content of the release, as parsed from commit logs

        Introduced in v8.0.0.

    •   version (Version <#semantic_release.version.version.Version>): contains metadata about the software version to be released and its git tag

        Introduced in v8.0.0.

  Example

Below is an example template that can be used to render release notes (it's similar to GitHub's automatically generated release notes <https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes>):

Configuration: pyproject.toml

            [tool.semantic_release.changelog]
            template_dir = "templates"

Template: templates/.release_notes.md.j2

            ## What's Changed
            {%    for type_, commits in release["elements"] | dictsort
            %}{%-   if type_ != "unknown"
            %}{{
                      "### %s" | format(type_ | title)

            }}{%      for commit in commits
            %}{{
                        "* %s by %s in [`%s`](%s)" | format(
                          commit.descriptions[0] | capitalize,
                          commit.commit.author.name,
                          commit.hexsha[:7],
                          commit.hexsha | commit_hash_url,
                        )

            }}{%-     endfor
            %}{%    endif
            %}{%  endfor
            %}

Result: https://github.com/example/repo/releases/tag/v1.1.0

            ## What's Changed

            ### Feature

            * Added a new feature by John Doe in [`a1b2c3d`](https://github.com/example/repo/commit/a1b2c3d)

  Migrating an Existing Changelog

v9.10.0 or greater

Migrating an existing changelog is simple with Python Semantic Release! To preserve your existing changelog, follow these steps:

    1.  Set the changelog.mode to "update" in your configuration file. This will ensure that only the new release information is added to your existing changelog file.

    2.  Set the changelog.insertion_flag to a unique string. You may use the default value or set it to a unique string that is not present in your existing changelog file. This flag is used to determine where the new release information should be inserted into your existing changelog.

    3.  Add the insertion flag to your changelog file. This must match the value you set in step 2. The insertion flag should be placed in the location above where you would like the new release information to be inserted.

Note:
        If you are trying to convert an existing changelog to a new format, you will need to do most of the conversion manually (or rebuild via init and modify) and make sure to include your insertion flag into the format of the new changelog.

Prior to v9.10.0

If you have an existing changelog that you would like to preserve, you will need to add the contents of the changelog file to your changelog template - either directly or via Jinja's include <https://jinja.palletsprojects.com/en/3.1.x/templates/#include> tag.

If you would like only the history from your next release onwards to be rendered into the changelog in addition to the existing changelog, you can add an if statement <https://jinja.palletsprojects.com/en/3.1.x/templates/#if> based upon the versions in the keys of context.released.

  Upgrading Templates

As PSR evolves, new features and improvements are added to the templating engine. If you have created your own custom templates, you may need to update them to take advantage of some new features. Below are some instructions on how to upgrade your templates to gain the benefits of the new features.

  Incrementally Updating Changelog Template

Note:
        This section is only relevant if you are upgrading from a version of PSR greater than v8.0.0 and prior to v9.10.0 and have created your own custom templates.

If you have previously created your own custom templates and would like to gain the benefits of the new updating changelog feature, you will need to make a few changes to your existing templates.

The following steps are a few suggestions to help upgrade your templates but primarily you should review the embedded default templates in the PSR package for a full example. You can find the default templates at data/templates/ <https://github.com/python-semantic-release/python-semantic-release/tree/master/src/semantic_release/data/templates> directory.

    1.  Add a conditional to check the changelog_mode. This will allow you to determine if you should render the entire changelog or just the new release information. See data/templates/*/md/CHANGELOG.md.j2 for reference.

    2.  Use the new read_file filter to read in the existing changelog file ctx.prev_changelog_file. This will allow you to include the existing changelog content in your new changelog file. See data/templates/*/md/.components/changelog_update.md.j2 for reference.

    3.  Split the changelog content based on the insertion flag. This will allow you to insert the new release information after the insertion flag (ctx.changelog_insertion_flag). See data/templates/*/md/.components/changelog_update.md.j2 for reference.

    4.  Print the leading content before the insertion flag. This ensures you maintain any content that should be included before the new release information. See data/templates/*/md/.components/changelog_update.md.j2 for reference.

    5.  Print your insertion flag. This is imperative to ensure that the resulting changelog can be updated in the future. See data/templates/*/md/.components/changelog_update.md.j2 for reference.

    6.  Print the new release information. Be sure to consider both unreleased and released commits during this step because of the cmd-changelog command that can be run at any time. See data/templates/*/md/.components/changelog_update.md.j2 for reference.

    7.  Print the trailing content after the insertion flag. This ensures you maintain any content that should be included after the new release information. See data/templates/*/md/.components/changelog_update.md.j2 for reference.

Tip:
        Modularity of your templates is key to handling both modes of changelog generation. Reference the default templates for examples on how we handle both modes and defensively handle numerous breaking scenarios.

Tip:
        If you are having trouble upgrading your templates, please post a question on the PSR GitHub <https://github.com/python-semantic-release/python-semantic-release/issues>

  Multibranch Releases

Python Semantic Release supports releases from multiple branches within your Git repository. You can elect to have a branch or set of branches create releases or prereleases <https://semver.org/#spec-item-9>. There are no restrictions enforced on how you set up your releases, but be aware that if you create new releases from multiple branches, or prereleases from multiple independent branches using the same prerelease token, there is a chance that Python Semantic Release will calculate the next version to be the same on more than one branch (leading to an error that a Git tag already exists).

Note:
        A "prerelease token" is the string used to suffix onto the 3-digit form of a full semantic version. For example, in the version 1.2.3-beta.1, the prerelease token is "beta"

        Typical strings used for pre-release tokens include "alpha", "beta", "dev" and "rc". These tend to indicate a level of maturity of the software associated with the version, but the specific meaning of each string is up to the project to decide.

        Generally, it's good practice to maintain a single branch from which full releases are made, and one branch at a time for each type of prerelease (alpha, beta, rc, etc).

If you absolutely require tagging and (pre-)releases to take place from multiple branches where there's a risk that tags could conflict between branches, you can use the --build-metadata command line argument to attach additional information (such as the branch name) to the tag in order to uniquely distinguish it from any other tags that might be calculated against other branches. Such a situation may occur in the following scenario:

                             O ----------- O      <---- feature-1
                            /          "feat: abc"
                           /
               O -------- O --------------- O    <---- main
            v1.0.0     v1.1.0
                            \
                             O ----------- O    <---- feature-2
                                       "feat: 123"

Suppose that Python Semantic Release has been configured to use the same prerelease token "alpha" for all feature-* branches, and the default tag format "v{version}". In this case, running a pre-release from branch feature-1 will recognize that since the last release, 1.1.0, a feature has been introduced and therefore the next tag to be applied to feature-1 will be v1.2.0-alpha.1.

However, suppose we then try to run a release against feature-2. This will also recognize that a feature has been introduced against the last released version of v1.1.0 and therefore will try to create the tag v1.2.0-alpha.1, leading to an error as this tag was already created against feature-1.

To get around this issue, you can pass the branch name as part of the build metadata:

            semantic-release version --build-metadata $(git branch --show-current)

This would lead to the tag v1.2.0-alpha.1+feature-1 and v1.2.0-alpha.1+feature-2 being applied to branches feature-1 and feature-2, respectively. Note that "build metadata MUST be ignored <https://semver.org/#spec-item-10>" per the semver specification when comparing two versions, so these two prereleases would be considered equivalent semantic versions, but when merged to the branch configured to produce full releases (main), if released separately the changes from each branch would be released in two versions that would be considered different according to the semver specification.

Note:
        If you have tags in your Git repository that are not valid semantic versions (which have then been formatted into your tag_format <#config-tag-format>), these tags will be ignored for the purposes of calculating the next version.

  Configuring Multibranch Releases

Within your configuration file, you can create one or more groups of branches ("release groups") that produce a certain type of release. Options are configured at the group level, and the group to use is chosen based on the current branch name against which Python Semantic Release is running.

Each release group is configured as a nested mapping under the tool.semantic_release.branches key in pyproject.toml, or the equivalent structure in other formats. the mapping requires a single key that is used as a name for the release group, which can help to identify it in log messages but has no effect on the behavior of the release. For example, Python Semantic Release has only one release group by default with the name main.

Inside each release group, the following key-value pairs can be set:
Key | Required | Default | Description
match | Yes | N/A | A Python regular expression <https://docs.python.org/3/library/re.html> to match against the active branch's name. If the branch name matches the provided regular expression, then this release group is chosen to provide the other configuration settings available.
prerelease | No | false | Whether or not branches in this release group should a prerelease instead of a full release
prerelease_token | No | rc | If creating a prerelease, specify the string to be used as a prerelease token in any new versions created against this branch.

Warning:
        If two release groups have overlapping "match" patterns, i.e. a the name of a branch could theoretically match both patterns, then the release group which is defined first in your configuration file is used.

        Because of this, it's recommended that you place release groups with more specific match patterns higher up in your configuration file than those with patterns that would match a broader range of branch names.

For example, suppose a project currently on version 1.22.4 is working on a new major version. The project wants to create a branch called 2.x.x against which they will develop the new major version, and they would like to create "release candidate" ("rc") prereleases from this branch. There are also a number of new features to integrate, and the project has agreed that all such branches should be named according to the convention next-{developer initials}-{issue number}, leading to branches named similarly to next-bc-prj-123. The project would like to release with tags that include some way to identify the branch and date on which the release was made from the tag.

This project would be able to leverage the following configuration to achieve the above requirements from their release configuration:

            [tool.semantic_release.branches.main]
            match = "(main|master)"
            prerelease = false

            [tool.semantic_release.branches."2.x.x"]
            match = "2.x.x"
            prerelease = true
            prerelease_token = "rc"

            [tool.semantic_release.branches."2.x.x New Features"]
            match = "next-\\w+-prj-\\d+"
            prerelease = true
            prerelease_token = "alpha"

In a CI pipeline, the following command would allow attaching the date and branch name to the versions that are produced (note this example uses the UNIX date command):

            semantic-release version \
               --build-metadata "$(git branch --show-current).$(date +%Y%m%d)"

This would lead to versions such as 1.1.1+main.20221127 or 2.0.0-rc.4+2.x.x.20221201.

Note:
        Remember that is always possible to override the release rules configured by using the cmd-version-option-force-level and cmd-version-option-as-prerelease flags.

  Strict Mode

Strict Mode is enabled by use of the strict parameter to the main command for Python Semantic Release. Strict Mode alters the behavior 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 <#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

Python Semantic Release is highly configurable, allowing you to tailor it to your project's needs. It supports various runtime environments and can be integrated with different CI/CD services.

    1.  Check out our set of configuration guides <#config-guides> to help walk you through the set up of common project customizations.

    2.  Dive in deep and explore the full set of possible customization options <#config>.

    3.  Go Automatic and Configure your CI/CD services <#automatic> to use Python Semantic Release.

  Configuration Guides

This section provides detailed guides on how to configure PSR for various use cases and integrations. It is recommended to complete the Getting Started Guide <#getting-started-guide> first before diving into these more specific configurations.

  Releasing Packages from a Monorepo

A monorepo (mono-repository) is a software development strategy where code for multiple projects is stored in a single source control system. This approach streamlines and consolidates configuration, but introduces complexities when using automated tools like Python Semantic Release (PSR).

Previously, PSR offered limited compatibility with monorepos. As of v10.4.0, PSR introduces the Conventional Commits Monorepo Parser <#commit-parser-builtin-conventional-monorepo>, designed specifically for monorepo environments. To fully leverage this new parser, you must configure your monorepo as described below.

  Configuring PSR

  Example: Simple

Directory Structure: PSR does not yet support a single, workspace-level configuration definition. This means each package in the monorepo requires its own PSR configuration file. A compatible and common monorepo file structure looks like:

            project/
            ├── .git/
            ├── .venv/
            ├── packages/
            │   ├── pkg1/
            │   │   ├── docs/
            │   │   │   └── source/
            │   │   │       ├── conf.py
            │   │   │       └── index.rst
            │   │   │
            │   │   ├── src/
            │   │   │   └── pkg1/
            │   │   │       ├── __init__.py
            │   │   │       ├── __main__.py
            │   │   │       └── py.typed
            │   │   │
            │   │   ├── CHANGELOG.md
            │   │   ├── README.md
            │   │   └── pyproject.toml             <-- PSR Configuration for Package 1
            │   │
            │   └── pkg2/
            │       ├── docs/
            │       │   └── source/
            │       │       ├── conf.py
            │       │       └── index.rst
            │       ├── src/
            │       │   └── pkg2/
            │       │       ├── __init__.py
            │       │       ├── __main__.py
            │       │       └── py.typed
            │       │
            │       ├── CHANGELOG.md
            │       ├── README.md
            │       └── pyproject.toml             <-- PSR Configuration for Package 2
            │
            ├── .gitignore
            └── README.md

This is the most basic monorepo structure, where each package is self-contained with its own configuration files, documentation, and CHANGELOG files. To release a package, change your current working directory to the package directory and execute PSR's cmd-version. PSR will automatically read the package's pyproject.toml, looking for the [tool.semantic_release] section to determine the package's versioning and release configuration, then search up the file tree to find the Git repository.

Because there is no workspace-level configuration, you must duplicate any common PSR configuration in each package's configuration file. Customize each configuration for each package to specify how PSR should distinguish between commits.

With the example file structure above, here is an example configuration file for each package:

            # FILE: pkg1/pyproject.toml
            [project]
            name = "pkg1"
            version = "1.0.0"

            [tool.semantic_release]
            commit_parser = "conventional-monorepo"
            commit_message = """\
            chore(release): pkg1@{version}`

            Automatically generated by python-semantic-release
            """
            tag_format = "pkg1-v{version}"
            version_toml = ["pyproject.toml:project.version"]

            [tool.semantic_release.commit_parser_options]
            path_filters = ["."]
            scope_prefix = "pkg1-"

            # FILE: pkg2/pyproject.toml
            [project]
            name = "pkg2"
            version = "1.0.0"

            [tool.semantic_release]
            commit_parser = "conventional-monorepo"
            commit_message = """\
            chore(release): pkg2@{version}`

            Automatically generated by python-semantic-release
            """
            tag_format = "pkg2-v{version}"
            version_toml = ["pyproject.toml:project.version"]

            [tool.semantic_release.commit_parser_options]
            path_filters = ["."]
            scope_prefix = "pkg2-"

These are the minimum configuration options required for each package. Note the use of tag_format <#config-tag-format> to distinguish tags between packages. The commit parser options are specific to the new Conventional Commits Monorepo Parser <#commit-parser-builtin-conventional-monorepo> and play a significant role in identifying which commits are relevant to each package. Since you are expected to change directories to each package before releasing, file paths in each configuration file should be relative to the package directory.

Each package also defines a slightly different commit_message <#config-commit-message> to reflect the package name in each message. This helps clarify which release number is being updated in the commit history.

  Release Steps

Given the following Git history of a monorepo using a GitHub Flow branching strategy (without CI/CD): [image]

To manually release both packages, run:

            cd packages/pkg1
            semantic-release version
            # 1.0.1 (tag: pkg1-v1.0.1)

            cd ../pkg2
            semantic-release version
            # 1.1.0 (tag: pkg2-v1.1.0)

After releasing both packages, the resulting Git history will look like: [image]

See also:

            •   GitHub Actions with Monorepos <#gh-actions-monorepo>

  Considerations

    1.  Custom Changelogs: Managing changelogs can be tricky depending on where you want to write the changelog files. In this simple example, the changelog is located within each package directory, and the changelog template does not have any package-specific formatting or naming convention. You can use one shared template directory at the root of the project and configure each package to point to the shared template directory.

            # FILE: pkg1/pyproject.toml
            [tool.semantic_release]
            template_dir = "../../config/release-templates"

            # FILE: pkg2/pyproject.toml
            [tool.semantic_release]
            template_dir = "../../config/release-templates"

            project/
            ├── .git/
            ├── config/
            │   └── release-templates/
            │       ├── CHANGELOG.md.j2
            │       └── .release_notes.md.j2
            ├── packages/
            │   ├── pkg1/
            │   │   ├── CHANGELOG.md
            │   │   └── pyproject.toml
            │   │
            │   └── pkg2/
            │       ├── CHANGELOG.md
            │       └── pyproject.toml
            │
            ├── .gitignore
            └── README.md

See also:

            •   For situations with more complex documentation needs, see our Advanced Example.

    2.  Package Prereleases: Creating pre-releases is possible, but it is recommended to use package-prefixed branch names to avoid collisions between packages. For example, to enable alpha pre-releases for new features in both packages, use the following configuration:

            # FILE: pkg1/pyproject.toml
            [tool.semantic_release.branches.alpha-release]
            match = "^pkg1/feat/.+"                       # <-- note pkg1 prefix
            prerelease = true
            prerelease_token = "alpha"

            # FILE: pkg2/pyproject.toml
            [tool.semantic_release.branches.alpha-release]
            match = "^pkg2/feat/.+"                       # <-- note pkg2 prefix
            prerelease = true
            prerelease_token = "alpha"

----

  Example: Advanced

If you want to consolidate documentation into a single top-level directory, the setup becomes more complex. In this example, there is a common documentation folder at the top level, and each package has its own subfolder within the documentation folder.

Due to naming conventions, PSR cannot automatically accomplish this with its default changelog templates. For this scenario, you must copy the internal PSR templates into a custom directory (even if you do not modify them) and add custom scripting to prepare for each release.

The directory structure looks like:

            project/
            ├── .git/
            ├── docs/
            │   ├── source/
            │   │   ├── pkg1/
            │   │   │   ├── changelog.md
            │   │   │   └── README.md
            │   │   ├── pkg2/
            │   │   │   ├── changelog.md
            │   │   │   └── README.md
            │   │   └── index.rst
            │   │
            │   └── templates/
            │       ├── .base_changelog_template/
            │       │   ├── components/
            │       │   │   ├── changelog_header.md.j2
            │       │   │   ├── changelog_init.md.j2
            │       │   │   ├── changelog_update.md.j2
            │       │   │   ├── changes.md.j2
            │       │   │   ├── first_release.md.j2
            │       │   │   ├── macros.md.j2
            │       │   │   ├── unreleased_changes.md.j2
            │       │   │   └── versioned_changes.md.j2
            │       │   └── changelog.md.j2
            │       ├── .gitignore
            │       └── .release_notes.md.j2
            │
            ├── packages/
            │   ├── pkg1/
            │   │   ├── src/
            │   │   │   └── pkg1/
            │   │   │       ├── __init__.py
            │   │   │       └── __main__.py
            │   │   └── pyproject.toml
            │   │
            │   └── pkg2/
            │       ├── src/
            │       │   └── pkg2/
            │       │       ├── __init__.py
            │       │       └── __main__.py
            │       └── pyproject.toml
            │
            └── scripts/
                ├── release-pkg1.sh
                └── release-pkg2.sh

Each package should point to the docs/templates/ directory to use a common release notes template. PSR ignores hidden files and directories when searching for template files to create, allowing you to hide shared templates in the directory for use in your release setup script.

Here is our configuration file for package 1 (package 2 is similarly defined):

            # FILE: pkg1/pyproject.toml
            [project]
            name = "pkg1"
            version = "1.0.0"

            [tool.semantic_release]
            commit_parser = "conventional-monorepo"
            commit_message = """\
            chore(release): Release `pkg1@{version}`

            Automatically generated by python-semantic-release
            """
            tag_format = "pkg1-v{version}"
            version_toml = ["pyproject.toml:project.version"]

            [tool.semantic_release.commit_parser_options]
            path_filters = [
                ".",
                "../../../docs/source/pkg1/**",
            ]
            scope_prefix = "pkg1-"

            [tool.semantic_release.changelog]
            template_dir = "../../../docs/templates"
            mode = "update"
            exclude_commit_patterns = [
                '''^chore(?:\([^)]*?\))?: .+''',
                '''^ci(?:\([^)]*?\))?: .+''',
                '''^refactor(?:\([^)]*?\))?: .+''',
                '''^style(?:\([^)]*?\))?: .+''',
                '''^test(?:\([^)]*?\))?: .+''',
                '''^Initial [Cc]ommit''',
            ]

            [tool.semantic_release.changelog.default_templates]
            # To enable update mode: this value must set here because the default is not the
            # same as the default in the other package & must be the final destination filename
            # for the changelog relative to this file
            changelog_file = "../../../docs/source/pkg1/changelog.md"

Note: In this configuration, we added path filters for additional documentation files related to the package so that the changelog will include documentation changes as well.

Next, define a release script to set up the common changelog templates in the correct directory format so PSR will create the desired files at the proper locations. Following the Custom Changelogs <#changelog-templates-template-rendering> reference, you must define the folder structure from the root of the project within the templates directory so PSR will properly lay down the files across the repository. The script cleans up any previous templates, dynamically creates the necessary directories, and copies over the shared templates into a package-named directory. Now you are prepared to run PSR for a release of pkg1.

            #!/bin/bash
            # FILE: scripts/release-pkg1.sh

            set -euo pipefail

            PROJECT_ROOT="$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")")"
            VIRTUAL_ENV="$PROJECT_ROOT/.venv"

            PACKAGE_NAME="pkg1"

            cd "$PROJECT_ROOT" || exit 1

            # Setup documentation template
            pushd "docs/templates" >/dev/null || exit 1

            rm -rf docs/
            mkdir -p "docs/source/"
            cp -r .base_changelog_template/ "docs/source/$PACKAGE_NAME"

            popd >/dev/null || exit 1

            # Release the package
            pushd "packages/$PACKAGE_NAME" >/dev/null || exit 1

            printf '%s\n' "Releasing $PACKAGE_NAME..."
            "$VIRTUAL_ENV/bin/semantic-release" -v version --no-push

            popd >/dev/null || exit 1

That's it! This example demonstrates how to set up a monorepo with shared changelog templates and a consolidated documentation folder for multiple packages.

See also:

            •   Advanced Example Monorepo: codejedi365/psr-monorepo-poweralpha <https://github.com/codejedi365/psr-monorepo-poweralpha>

  Ultraviolet (uv) Integration

uv <https://docs.astral.sh/uv/> is an extremely fast Python package and project manager that provides a modern alternative to pip <https://pip.pypa.io/en/stable/> and venv <https://docs.python.org/3/library/venv.html>. It provides a lot of features that solve the common problems of Python package management but it also introduces a few quirks that need to be taken into account when using Python Semantic Release.

Important:
        Prerequisite: Make sure you have run through the Getting Started Guide <#getting-started-guide> before proceeding with this guide.

  Updating the uv.lock

One of the best features of uv is that it automatically generates a lock file (uv.lock) that contains the exact versions of all the dependencies used in your project. The lock file is generated when you run the uv install command, and it is used to ensure that CI workflows are repeatable and development environments are consistent.

When creating a new release using Python Semantic Release, PSR will update the version in the project's definition file (e.g., pyproject.toml) to indicate the new version. Unfortunately, this action will cause uv to fail on the next execution because the lock file will be out of sync with the project's definition file. There are two ways to resolve this issue depending on your preference:

    1.  Add a step to your build command: Modify your semantic_release.build_command <#config-build-command> to include the command to update the lock file and stage it for commit. This is commonly used with the GitHub Action <#gh-actions-psr> and other CI/CD tools when you are building the artifact at the time of release.

                [tool.semantic_release]
                build_command = """
                    uv lock --upgrade-package "$PACKAGE_NAME"
                    git add uv.lock
                    uv build
                """

    The intent of the lock upgrade-package call is ONLY to update the version of your project within the lock file after PSR has updated the version in your project's definition file (e.g., pyproject.toml). When you are running PSR, you have already tested the project as is and you don't want to actually update the dependencies if a new one just became available.

    For ease of use, PSR provides the $PACKAGE_NAME environment variable that contains the name of your package from the project's definition file (pyproject.toml:project.name).

    If you are using the PSR GitHub Action <#gh-actions-psr>, you will need to add an installation command for uv to the build_command <#config-build-command> because the action runs in a Docker environment does not include uv by default. The best way to ensure that the correct version of uv is installed is to define the version of uv in an optional dependency list (e.g. build). This will also help with other automated tools like Dependabot or Renovate to keep the version of uv up to date.

                [project.optional-dependencies]
                build = ["uv ~= 0.7.12"]

                [tool.semantic_release]
                build_command = """
                    python -m pip install -e '.[build]'
                    uv lock --upgrade-package "$PACKAGE_NAME"
                    git add uv.lock
                    uv build
                """

    2.  Stamp the code first & then separately run release: If you prefer to not modify the build command, then you will need to run the uv lock --upgrade-package <your-package-name> command prior to actually creating the release. Essentially, you will run PSR twice: (1) once to update the version in the project's definition file, and (2) a second time to generate the release.

        The intent of the uv lock --upgrade-package <your-package-name> command is ONLY to update the version of your project within the lock file after PSR has updated the version in your project's definition file (e.g., pyproject.toml). When you are running PSR, you have already tested the project as is and you don't want to actually update the dependencies if a new one just became available.

                # 1. PSR stamps version into files (nothing else)
                # don't build the changelog (especially in update mode)
                semantic-release -v version --skip-build --no-commit --no-tag --no-changelog

                # 2. run UV lock as pyproject.toml is updated with the next version
                uv lock --upgrade-package <your-package-name>

                # 3. stage the lock file to ensure it is included in the PSR commit
                git add uv.lock

                # 4. run PSR fully to create release
                semantic-release -v version

Advanced Example

Of course, you can mix and match these 2 approaches as needed. If PSR's pipeline was using uv, we would have a mixture of the 2 approaches because we run the build in a separate job from the release. In our case, PSR would also need to carry the lock file as a workflow artifact along the pipeline for the release job to commit it. This advanced workflow would look like this:

            # File: .tool-versions
            uv 0.7.12

            # File: .python-version
            3.11.11

            # File: pyproject.toml
            [project.optional-dependencies]
            build = ["python-semantic-release ~= 10.0"]
            test = ["pytest ~= 8.0"]

            [tool.semantic_release]
            build_command = """
              uv lock --upgrade-package "$PACKAGE_NAME"
              uv build
            """

            # File: .github/workflows/release.yml
            on:
              push:
                branches:
                  - main

            jobs:

              build:
                runs-on: ubuntu-latest
                permissions:
                  contents: read
                env:
                  dist_artifacts_name: dist
                  dist_artifacts_dir: dist
                  lock_file_artifact: uv.lock
                steps:
                  - name: Setup | Checkout Repository at workflow sha
                    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
                    with:
                      ref: ${{ github.sha }}

                  - name: Setup | Force correct release branch on workflow sha
                    run: git checkout -B ${{ github.ref_name }}

                  - name: Setup | Install uv
                    uses: asdf-vm/actions/install@1902764435ca0dd2f3388eea723a4f92a4eb8302  # v4.0.2

                  - name: Setup | Install Python & Project dependencies
                    run: uv sync --extra build

                  - name: Build | Build next version artifacts
                    id: version
                    env:
                      GH_TOKEN: "none"
                    run: uv run semantic-release -v version --no-changelog --no-commit --no-tag

                  - name: Upload | Distribution Artifacts
                    if: ${{ steps.version.outputs.released == 'true' }}
                    uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
                    with:
                      name: ${{ env.dist_artifacts_name }}
                      path: ${{ format('{0}/**', env.dist_artifacts_dir) }}
                      if-no-files-found: error
                      retention-days: 2

                  - name: Upload | Lock File Artifact
                    if: ${{ steps.version.outputs.released == 'true' }}
                    uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
                    with:
                      name: ${{ env.lock_file_artifact }}
                      path: ${{ env.lock_file_artifact }}
                      if-no-files-found: error
                      retention-days: 2

                outputs:
                  new-release-detected: ${{ steps.version.outputs.released }}
                  new-release-version: ${{ steps.version.outputs.version }}
                  new-release-tag: ${{ steps.version.outputs.tag }}
                  new-release-is-prerelease: ${{ steps.version.outputs.is_prerelease }}
                  distribution-artifacts: ${{ env.dist_artifacts_name }}
                  lock-file-artifact: ${{ env.lock_file_artifact }}

              test-e2e:
                needs: build
                runs-on: ubuntu-latest
                steps:
                  - name: Setup | Checkout Repository
                    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
                    with:
                      ref: ${{ github.sha }}
                      fetch-depth: 1

                  - name: Setup | Download Distribution Artifacts
                    uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
                    if: ${{ needs.build.outputs.new-release-detected == 'true' }}
                    id: artifact-download
                    with:
                      name: ${{ needs.build.outputs.distribution-artifacts }}
                      path: ./dist

                  - name: Setup | Install uv
                    uses: asdf-vm/actions/install@1902764435ca0dd2f3388eea723a4f92a4eb8302  # v4.0.2

                  - name: Setup | Install Python & Project dependencies
                    run: uv sync --extra test

                  - name: Setup | Install distribution artifact
                    if: ${{ steps.artifact-download.outcome == 'success' }}
                    run: |
                      uv pip uninstall my-package
                      uv pip install dist/python_semantic_release-*.whl

                  - name: Test | Run pytest
                    run: uv run pytest -vv tests/e2e

              release:
                runs-on: ubuntu-latest
                needs:
                  - build
                  - test-e2e

                if: ${{ needs.build.outputs.new-release-detected == 'true' }}

                concurrency:
                  group: ${{ github.workflow }}-release-${{ github.ref_name }}
                  cancel-in-progress: false

                permissions:
                  contents: write

                steps:
                  - name: Setup | Checkout Repository on Release Branch
                    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
                    with:
                      ref: ${{ github.ref_name }}

                  - name: Setup | Force release branch to be at workflow sha
                    run: git reset --hard ${{ github.sha }}

                  - name: Setup | Install uv
                    uses: asdf-vm/actions/install@1902764435ca0dd2f3388eea723a4f92a4eb8302  # v4.0.2

                  - name: Setup | Install Python & Project dependencies
                    run: uv sync --extra build

                  - name: Setup | Download Build Artifacts
                    uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
                    id: artifact-download
                    with:
                      name: ${{ needs.build.outputs.distribution-artifacts }}
                      path: dist

                  - name: Setup | Download Lock File Artifact
                    uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
                    with:
                      name: ${{ needs.build.outputs.lock-file-artifact }}

                  - name: Setup | Stage Lock File for Version Commit
                    run: git add uv.lock

                  - name: Release | Create Release
                    id: release
                    shell: bash
                    env:
                      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
                    run: |
                      uv run semantic-release -v --strict version --skip-build
                      uv run semantic-release publish

                outputs:
                  released: ${{ steps.release.outputs.released }}
                  new-release-version: ${{ steps.release.outputs.version }}
                  new-release-tag: ${{ steps.release.outputs.tag }}

              deploy:
                name: Deploy
                runs-on: ubuntu-latest
                if: ${{ needs.release.outputs.released == 'true' && github.repository == 'python-semantic-release/my-package' }}
                needs:
                  - build
                  - release

                environment:
                  name: pypi
                  url: https://pypi.org/project/my-package/

                permissions:
                  id-token: write

                steps:
                  - name: Setup | Download Build Artifacts
                    uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
                    id: artifact-download
                    with:
                      name: ${{ needs.build.outputs.distribution-artifacts }}
                      path: dist

                  - name: Publish package distributions to PyPI
                    uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc  # v1.12.4
                    with:
                      packages-dir: dist
                      print-hash: true
                      verbose: true

  Configuration

Configuration is read from a file which can be specified using the \\-\\-config option to cmd-main. 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 <https://github.com/toml-lang/toml/issues/30>. 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 depending 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

Introduced in v9.2.0

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 changed to ``false`` in v10.0.0

Default: false

----

  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 <#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 cmd-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
PACKAGE_NAME | Project name as defined in pyproject.toml:project.name
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

In addition, on windows systems these environment variables are passed:
Variable Name | Description
ALLUSERSAPPDATA | Pass-through ALLUSERAPPDATA if exists in process env, unset otherwise
ALLUSERSPROFILE | Pass-through ALLUSERSPPPROFILE if exists in process env, unset otherwise
APPDATA | Pass-through APPDATA if exists in process env, unset otherwise
COMMONPROGRAMFILES | Pass-through COMMONPROGRAMFILES if exists in process env, unset otherwise
COMMONPROGRAMFILES(X86) | Pass-through COMMONPROGRAMFILES(X86) if exists in process env, unset otherwise
DEFAULTUSERPROFILE | Pass-through DEFAULTUSERPROFILE if exists in process env, unset otherwise
HOMEPATH | Pass-through HOMEPATH if exists in process env, unset otherwise
PATHEXT | Pass-through PATHEXT if exists in process env, unset otherwise
PROFILESFOLDER | Pass-through PROFILESFOLDER if exists in process env, unset otherwise
PROGRAMFILES | Pass-through PROGRAMFILES if exists in process env, unset otherwise
PROGRAMFILES(X86) | Pass-through PROGRAMFILES(X86) if exists in process env, unset otherwise
SYSTEM | Pass-through SYSTEM if exists in process env, unset otherwise
SYSTEM16 | Pass-through SYSTEM16 if exists in process env, unset otherwise
SYSTEM32 | Pass-through SYSTEM32 if exists in process env, unset otherwise
SYSTEMDRIVE | Pass-through SYSTEMDRIVE if exists in process env, unset otherwise
SYSTEMROOT | Pass-through SYSTEMROOT if exists in process env, unset otherwise
TEMP | Pass-through TEMP if exists in process env, unset otherwise
TMP | Pass-through TMP if exists in process env, unset otherwise
USERPROFILE | Pass-through USERPROFILE if exists in process env, unset otherwise
USERSID | Pass-through USERSID if exists in process env, unset otherwise
WINDIR | Pass-through WINDIR if exists in process env, unset otherwise

Default: None (not specified)

----

  build_command_env

Introduced in v9.7.2

Type: Optional[list[str]]

List of environment variables to include or pass-through on to the build command that executes during cmd-version.

This configuration option allows the user to extend the list of environment variables from the table above in build_command. The input is a list of strings where each individual string handles a single variable definition. There are two formats accepted and are detailed in the following table:
FORMAT | Description
VAR_NAME | Detects value from the PSR process environment, and passes value to build_command process
VAR_NAME=value | Sets variable name to value inside of build_command process

Note:
        Although variable name capitalization is not required, it is recommended as to be in-line with the POSIX-compliant recommendation for shell variable names.

Default: None (not specified)

----

  changelog

This section outlines the configuration options available that modify changelog generation.

Note:
        pyproject.toml: [tool.semantic_release.changelog]

        releaserc.toml: [semantic_release.changelog]

        releaserc.json: { "semantic_release": { "changelog": {} } }

----

  changelog_file

Warning:
        Deprecated in v9.11.0. This setting has been moved to changelog.default_templates.changelog_file for a more logical grouping. This setting will be removed in a future major release.

Type: str

Specify the name of the changelog file that will be created. This file will be created or overwritten (if it previously exists) with the rendered default template included with Python Semantic Release.

Depending on the file extension of this setting, the changelog will be rendered in the format designated by the extension. PSR, as of v9.11.0, provides a default changelog template in both Markdown (.md) and reStructuredText (.rst) formats. If the file extension is not recognized, the changelog will be rendered in Markdown format, unless the output_format setting is set.

If you are using the template_dir setting for providing customized templates, this setting is not used. See template_dir for more information.

Default: "CHANGELOG.md"

----

  default_templates

Note:
        This section of the configuration contains options which customize or modify the default changelog templates included with PSR.

        pyproject.toml: [tool.semantic_release.changelog.default_templates]

        releaserc.toml: [semantic_release.changelog.default_templates]

        releaserc.json: { "semantic_release": { "changelog": { "default_templates": {} } } }

----

  changelog_file

Introduced in v9.11.0.

Type: str

Specify the name of the changelog file that will be created. This file will be created or overwritten (if it previously exists) with the rendered default template included with Python Semantic Release.

Depending on the file extension of this setting, the changelog will be rendered in the format designated by the extension. PSR, as of v9.11.0, provides a default changelog template in both Markdown (.md) and reStructuredText (.rst) formats. If the file extension is not recognized, the changelog will be rendered in Markdown format, unless the output_format setting is set.

If you are using the template_dir setting for providing customized templates, this setting is not used. See template_dir for more information.

Default: "CHANGELOG.md"

----

  mask_initial_release

Introduced in v9.14.0

Type: bool

This option toggles the behavior of the changelog and release note templates to mask the release details specifically for the first release. When set to true, the first version release notes will be masked with a generic message as opposed to the usual commit details. When set to false, the release notes will be generated as normal.

The reason for this setting is to improve clarity to your audience. It conceptually does NOT make sense to have a list of changes (i.e. a Changelog) for the first release since nothing has been published yet, therefore in the eyes of your consumers what change is there to document?

The message details can be found in the first_release.md.j2 and first_release.rst.j2 templates of the default changelog template directory.

Default changed to ``true`` in v10.0.0.

Default: true

See also:

            •   Using the Default Changelog <#changelog-templates-default-changelog>

----

  output_format

Introduced in v9.10.0

Type: Literal["md", "rst"]

This setting is used to specify the output format the default changelog template will use when rendering the changelog. PSR supports both Markdown (md) and reStructuredText (rst) formats.

This setting will take precedence over the file extension of the changelog_file setting. If this setting is omitted, the file extension of the changelog_file setting will be used to determine the output format. If the file extension is not recognized, the output format will default to Markdown.

Default: "md"

See also:

            •   changelog_file

----

  environment

Note:
        This section of the configuration contains options which customize the template environment used to render templates such as the changelog. Most options are passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor, and further documentation one these parameters can be found there.
                pyproject.toml: [tool.semantic_release.changelog.environment]

                releaserc.toml: [semantic_release.changelog.environment]

                releaserc.json: { "semantic_release": { "changelog": { "environment": {} } } }

----

  autoescape

Type: Union[str, bool]

If this setting is a string, it should be given in module:attr form; Python Semantic Release will attempt to dynamically import this string, which should represent a path to a suitable callable that satisfies the following:
        As of Jinja 2.4 this can also be a callable that is passed the template name and has to return true or false depending on autoescape should be enabled by default.

The result of this dynamic import is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

If this setting is a boolean, it is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: false

----

  block_start_string

Type: str

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: "{%"

----

  block_end_string

Type: str

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: "%}"

----

  comment_start_string

Type: str

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: {#

----

  comment_end_string

Type: str

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: "#}"

----

  extensions

Type: list[str]

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: []

----

  keep_trailing_newline

Type: bool

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: false

----

  line_comment_prefix

Type: Optional[str]

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: None (not specified)

----

  line_statement_prefix

Type: Optional[str]

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: None (not specified)

----

  lstrip_blocks

Type: bool

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: false

----

  newline_sequence

Type: Literal["\n", "\r", "\r\n"]

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: "\n"

----

  trim_blocks

Type: bool

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: false

----

  variable_start_string

Type: str

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: "{{"

----

  variable_end_string

Type: str

This setting is passed directly to the jinja2.Environment <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> constructor.

Default: "}}"

----

  exclude_commit_patterns

Type: list[str]

Any patterns specified here will be excluded from the commits which are available to your changelog. This allows, for example, automated commits to be removed if desired. Python Semantic Release also removes its own commits from the Changelog via this mechanism; therefore if you change the automated commit message that Python Semantic Release uses when making commits, you may wish to add the old commit message pattern here.

The patterns in this list are treated as regular expressions.

Default: []

----

  mode

Introduced in v9.10.0. Default changed to `update` in v10.0.0.

Type: Literal["init", "update"]

This setting is a flag that is ultimately passed into the changelog context environment. It sets the value of context.changelog_mode to a string value of either init or update.

When used with the provided changelog template, it will determine the behavior of how the changelog is written. When the mode is set to init, the changelog file will be written from scratch, overwriting any existing changelog file. This is the v8 and v9 default behavior.

When the mode is set to update, the changelog file will look for the insertion_flag value in the changelog file (defined by changelog_file) and insert the new version information at that location.

If you are using a custom template directory, the context.changelog_mode value will exist in the changelog context but it is up to your implementation to determine if and/or how to use it.

Default: update

See also:

            •   Using the Default Changelog <#changelog-templates-default-changelog>

----

  insertion_flag

Introduced in v9.10.0

Type: str

A string that will be used to identify where the new version should be inserted into the changelog file (as defined by changelog_file) when the changelog mode is set to update.

If you modify this value in your config, you will need to manually update any saved changelog file to match the new insertion flag if you use the update mode. In init mode, the changelog file will be overwritten as normal.

In v9.11.0, the insertion_flag default value became more dynamic with the introduction of an reStructuredText template. The default value will be set depending on the output_format setting. The default flag values are:
Output Format | Default Insertion Flag
Markdown (md) | <!-- version list -->
reStructuredText | ..\n version list

Default: various, see above

----

  template_dir

Type: str

When files exist within the specified directory, they will be used as templates for the changelog rendering process. Regardless if the directory includes a changelog file, the provided directory will be rendered and files placed relative to the root of the project directory.

No default changelog template or release notes template will be used when this directory exists and the directory is not empty. If the directory is empty, the default changelog template will be used.

This option is discussed in more detail at Version Change Reports <#changelog-templates>

Default: "templates"

----

  commit_author

Type: str

Author used in commits in the format name <email>.

Note:
        If you are using the built-in GitHub Action, the default value is set to github-actions <actions@github.com>. You can modify this with the git_committer_name and git_committer_email inputs.

See also:

            •   GitHub Actions <#gh-actions>

Default: semantic-release <semantic-release>

----

  commit_message

Type: str

Commit message to use when making release commits. The message can use {version} as a format key, in which case the version being released will be formatted into the message.

If at some point in your project's lifetime you change this, you may wish to consider, adding the old message pattern(s) to exclude_commit_patterns.

Default: "{version}\n\nAutomatically generated by python-semantic-release"

----

  commit_parser

Type: str

Specify which commit parser Python Semantic Release should use to parse the commits within the Git repository.

    Built-in parsers:

        •   angular - AngularCommitParser <#commit-parser-builtin-angular> (deprecated in v9.19.0)

        •   conventional - ConventionalCommitParser <#commit-parser-builtin-conventional> (available in v9.19.0+)

        •   conventional-monorepo - ConventionalCommitMonorepoParser <#commit-parser-builtin-conventional-monorepo> (available in v10.4.0+)

        •   emoji - EmojiCommitParser <#commit-parser-builtin-emoji>

        •   scipy - ScipyCommitParser <#commit-parser-builtin-scipy>

        •   tag - TagCommitParser <#commit-parser-builtin-tag> (deprecated in v9.12.0)

You can set any of the built-in parsers by their keyword but you can also specify your own commit parser in path/to/module_file.py:Class or module:Class form.

For more information see Commit Parsing <#commit-parsing>.

Default: "conventional"

----

  commit_parser_options

Type: dict[str, Any]

This set of options are passed directly to the commit parser class specified in the commit parser configuration option.

For more information (to include defaults), see Customization <#commit-parser-builtin-customization>.

Default: ParserOptions { ... }, where ... depends on commit_parser.

----

  logging_use_named_masks

Type: bool

Whether or not to replace secrets identified in logging messages with named masks identifying which secrets were replaced, or use a generic string to mask them.

Default: false

----

  major_on_zero

Type: bool

This flag controls whether or not Python Semantic Release will increment the major version upon a breaking change when the version matches 0.y.z. This value is set to true by default, where breaking changes will increment the 0 major version to 1.0.0 like normally expected.

If set to false, major (breaking) releases will increment the minor digit of the version while the major version is 0, instead of the major digit. This allows for continued breaking changes to be made while the major version remains 0.

From the Semantic Versioning Specification <https://semver.org/spec/v2.0.0.html#spec-item-4>:
        Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

When you are ready to release a stable version, set major_on_zero to true and run Python Semantic Release again. This will increment the major version to 1.0.0.

When allow_zero_version is set to false, this setting is ignored.

Default: true

----

  no_git_verify

Introduced in v9.8.0

Type: bool

This flag is passed along to git upon performing a git commit during cmd-version.

When true, it will bypass any git hooks that are set for the repository when Python Semantic Release makes a version commit. When false, the commit is performed as normal. This option has no effect when there are not any git hooks configured nor when the --no-commit option is passed.

Default: false

----

  publish

This section defines configuration options that modify cmd-publish.

Note:
        pyproject.toml: [tool.semantic_release.publish]

        releaserc.toml: [semantic_release.publish]

        releaserc.json: { "semantic_release": { "publish": {} } }

----

  dist_glob_patterns

Type: list[str]

Upload any files matching any of these globs to your VCS release. Each item in this list should be a string containing a Unix-style glob pattern.

Default: ["dist/*"]

----

  upload_to_vcs_release

Type: bool

If set to true, upload any artifacts matched by the dist_glob_patterns to the release created in the remote VCS corresponding to the latest tag. Artifacts are only uploaded if release artifact uploads are supported by the VCS type.

Default: true

----

  remote

The remote configuration is a group of settings that configure PSR's integration with remote version control systems.

Note:
        pyproject.toml: [tool.semantic_release.remote]

        releaserc.toml: [semantic_release.remote]

        releaserc.json: { "semantic_release": { "remote": {} } }

----

  api_domain

Type: Optional[str | Dict['env', str]]

The hosting domain for the API of your remote HVCS if different than the domain. Generally, this will be used to specify a separate subdomain that is used for API calls rather than the primary domain (ex. api.github.com).

Most on-premise HVCS installations will NOT use this setting! Whether or not this value is used depends on the HVCS configured (and your server administration) in the remote.type setting and used in tandem with the remote.domain setting.

When using a custom remote.domain and a HVCS remote.type that is configured with a separate domain or sub-domain for API requests, this value is used to configure the location of API requests that are sent from PSR.

Most on-premise or self-hosted HVCS environments will use a path prefix to handle inbound API requests, which means this value will ignored.

PSR knows the expected api domains for known cloud services and their associated api domains which means this value is not necessary to explicitly define for services as bitbucket.org, and github.com.

Including the protocol schemes, such as https://, for the API domain is optional. Secure HTTPS connections are assumed unless the setting of remote.insecure is true.

Default: None

----

  domain

Type: Optional[str | Dict['env', str]]

The host domain for your HVCS server. This setting is used to support on-premise installations of HVCS providers with custom domain hosts.

If you are using the official domain of the associated remote.type, this value is not required. PSR will use the default domain value for the remote.type when not specified. For example, when remote.type="github" is specified the default domain of github.com is used.

Including the protocol schemes, such as https://, for the domain value is optional. Secure HTTPS connections are assumed unless the setting of remote.insecure is true.

This setting also supports reading from an environment variable for ease-of-use in CI pipelines. See Environment Variable for more information. Depending on the remote.type, the default environment variable for the default domain's CI pipeline environment will automatically be checked so this value is not required in default environments. For example, when remote.type="gitlab" is specified, PSR will look to the CI_SERVER_URL environment variable when remote.domain is not specified.

Default: None

See also:

            •   remote.api_domain

----

  ignore_token_for_push

Type: bool

If set to true, ignore the authentication token when pushing changes to the remote. This is ideal, for example, if you already have SSH keys set up which can be used for pushing.

Default: false

----

  insecure

Introduced in v9.4.2

Type: bool

Insecure is used to allow non-secure HTTP connections to your HVCS server. If set to true, any domain value passed will assume http:// if it is not specified and allow it. When set to false (implicitly or explicitly), it will force https:// communications.

When a custom domain or api_domain is provided as a configuration, this flag governs the protocol scheme used for those connections. If the protocol scheme is not provided in the field value, then this insecure option defines whether HTTP or HTTPS is used for the connection. If the protocol scheme is provided in the field value, it must match this setting or it will throw an error.

The purpose of this flag is to prevent any typos in provided domain and api_domain values that accidentally specify an insecure connection but allow users to toggle the protection scheme off when desired.

Default: false

----

  name

Type: str

Name of the remote to push to using git push -u $name <branch_name>

Default: "origin"

----

  token

Type: Optional[str | Dict['env', str]]

Environment Variable from which to source the authentication token for the remote VCS. Common examples include "GH_TOKEN", "GITLAB_TOKEN" or "GITEA_TOKEN", however, you may choose to use a custom environment variable if you wish.

Note:
        By default, this is a mandatory environment variable that must be set before using any functionality that requires authentication with your remote VCS. If you are using this token to enable push access to the repository, it must also be set before attempting to push.

        If your push access is enabled via SSH keys instead, then you do not need to set this environment variable in order to push the version increment, changelog and modified source code assets to the remote using cmd-version. However, you will need to disable release creation using the cmd-version-option-vcs-release option, among other options, in order to use Python Semantic Release without configuring the environment variable for your remote VCS authentication token.

The default value for this setting depends on what you specify as remote.type. Review the table below to see what the default token value will be for each remote type.
remote.type |  | Default remote.token
"github" | -> | { env = "GH_TOKEN" }
"gitlab" | -> | { env = "GITLAB_TOKEN" }
"gitea" | -> | { env = "GITEA_TOKEN" }
"bitbucket" | -> | { env = "BITBUCKET_TOKEN" }

Default: { env = "<envvar name>" }, where <envvar name> depends on remote.type as indicated above.

----

  type

Type: Literal["bitbucket", "gitea", "github", "gitlab"]

The type of the remote VCS. Currently, Python Semantic Release supports "github", "gitlab", "gitea" and "bitbucket". Not all functionality is available with all remote types, but we welcome pull requests to help improve this!

Default: "github"

----

  url

Type: Optional[str | Dict['env', str]]

An override setting used to specify the remote upstream location of git push.

Not commonly used! This is used to override the derived upstream location when the desired push location is different than the location the repository was cloned from.

This setting will override the upstream location url that would normally be derived from the remote.name location of your git repository.

Default: None

----

  add_partial_tags

Type: bool

Specify if partial version tags should be handled when creating a new version. If set to true, a major and a major.minor tag will be created or updated, using the format specified in tag_format. If version has build metadata, a major.minor.patch tag will also be created or updated.

Partial version tags are disabled for pre-release versions.

Example

            [semantic_release]
            tag_format = "v{version}"
            add_partial_tags = true

This configuration with the next version of 1.2.3 will result in:

            git log --decorate --oneline --graph --all
            # * 4d4cb0a (tag: v1.2.3, tag: v1.2, tag: v1, origin/main, main) 1.2.3
            # * 3a2b1c0 fix: some bug
            # * 2b1c0a9 (tag: v1.2.2) 1.2.2
            # ...

If build-metadata is used, the next version of 1.2.3+20251109 will result in:

            git log --decorate --oneline --graph --all
            # * 4d4cb0a (tag: v1.2.3+20251109, tag: v1.2.3, tag: v1.2, tag: v1, origin/main, main) 1.2.3+20251109
            # * 3a2b1c0 chore: add partial tags to PSR configuration
            # * 2b1c0a9 (tag: v1.2.3+20251031) 1.2.3+20251031
            # ...

Default: false

----

  tag_format

Type: str

Specify the format to be used for the Git tag that will be added to the repo during a release invoked via cmd-version. The string is used as a template for the tag name, and must include the {version} format key.

This format will also be used for parsing tags already present in the repository into semantic versions; therefore if the tag format changes at some point in the repository's history, historic versions that no longer match this pattern will not be considered as versions.
Format Key | Mandatory | Contents
{version} | Yes | The new semantic version number, for example 1.2.3, or 2.1.0-alpha.1+build.1234

Tags which do not match this format will not be considered as versions of your project.

This is critical for Monorepo projects where the tag format defines which package the version tag belongs to. Generally, the tag format for each package of the monorepo will include the package name as the prefix of the tag format. For example, if the package is named pkg1, the tag format would be pkg1-v{version} and in the other package pkg2, the tag format would be pkg2-v{version}. This allows PSR to determine which tags to use to determine the version for each package.

Default: "v{version}"

----

  version_toml

Type: list[str]

This configuration option is similar to version_variables, but it uses a TOML parser to interpret the data structure before, inserting the version. This allows users to use dot-notation to specify the version via the logical structure within the TOML file, which is more accurate than a pattern replace.

The version_toml option is commonly used to update the version number in the project definition file: pyproject.toml as seen in the example below.

As of v9.20.0, the version_toml option accepts a colon-separated definition with either 2 or 3 parts. The 2-part definition includes the file path and the version parameter (in dot-notation). Newly with v9.20.0, it also accepts an optional 3rd part to allow configuration of the format type.

Available Format Types

    •   nf: Number format (ex. 1.2.3)

    •   tf: Tag Format (ex. v1.2.3)

If the format type is not specified, it will default to the number format.

Example

            [semantic_release]
            version_toml = [
                # "file:variable:[format_type]"
                "pyproject.toml:tool.poetry.version",  # Implied Default: Number format
                "definition.toml:project.version:nf",  # Number format
                "definition.toml:project.release:tf",  # Tag format
            ]

This configuration will result in the following changes:

            diff a/pyproject.toml b/pyproject.toml

              [tool.poetry]
            - version = "0.1.0"
            + version = "0.2.0"

            diff a/definition.toml b/definition.toml

              [project]
              name = "example"

            - version = "0.1.0"
            + version = "0.1.0"

            - release = "v0.1.0"
            + release = "v0.2.0"

Default: []

----

  version_variables

Type: list[str]

The version_variables configuration option is a list of string definitions that defines where the version number should be updated in the repository, when a new version is released.

As of v9.20.0, the version_variables option accepts a colon-separated definition with either 2 or 3 parts. The 2-part definition includes the file path and the variable name. Newly with v9.20.0, it also accepts an optional 3rd part to allow configuration of the format type.

Available Format Types

    •   nf: Number format (ex. 1.2.3)

    •   tf: Tag Format (ex. v1.2.3)

If the format type is not specified, it will default to the number format.

Prior to v9.20.0, PSR only supports entries with the first 2-parts as the tag format type was not available and would only replace numeric version numbers.

Example

            [semantic_release]
            tag_format = "v{version}"
            version_variables = [
                # "file:variable:format_type"
                "src/semantic_release/__init__.py:__version__",  # Implied Default: Number format
                "docs/conf.py:version:nf",                       # Number format for sphinx docs
                "kustomization.yml:newTag:tf",                   # Tag format
            ]

First, the __version__ variable in src/semantic_release/__init__.py will be updated with the next version using the SemVer <https://semver.org/> number format.

            diff a/src/semantic_release/__init__.py b/src/semantic_release/__init__.py

            - __version__ = "0.1.0"
            + __version__ = "0.2.0"

Then, the version variable in docs/conf.py will be updated with the next version with the next version using the SemVer <https://semver.org/> number format because of the explicit nf.

            diff a/docs/conf.py b/docs/conf.py

            - version = "0.1.0"
            + version = "0.2.0"

Lastly, the newTag variable in kustomization.yml will be updated with the next version with the next version using the configured tag_format because the definition included tf.

            diff a/kustomization.yml b/kustomization.yml

              images:
                - name: repo/image
            -     newTag: v0.1.0
            +     newTag: v0.2.0

How It works

Each version variable will be transformed into a Regular Expression that will be used to substitute the version number in the file. The replacement algorithm is ONLY a pattern match and replace. It will NOT evaluate the code nor will PSR understand any internal object structures (ie. file:object.version will not work).

The regular expression generated from the version_variables definition will:

    1.  Look for the specified variable name in the file. The variable name can be enclosed by single (') or double (") quotation marks but they must match.

    2.  The variable name defined by variable and the version must be separated by an operand symbol (=, :, :=, or @). Whitespace is optional around the symbol. As of v10.0.0, a double-equals (==) operator is also supported as a valid operand symbol. As of v10.5.0, PSR can omit all operands as long as there is at least one whitespace character between the variable name and the version.

    3.  The value of the variable must match a SemVer <https://semver.org/> regular expression and can be enclosed by single (') or double (") quotation marks but they must match. However, the enclosing quotes of the value do not have to match the quotes surrounding the variable name.

    4.  If the format type is set to tf then the variable value must have the matching prefix and suffix of the tag_format setting around the SemVer <https://semver.org/> version number.

Given the pattern matching nature of this feature, the Regular Expression is able to support most file formats because of the similarity of variable declaration across programming languages. PSR specifically supports Python, YAML, and JSON as these have been the most commonly requested formats. This configuration option will also work regardless of file extension because it looks for a matching pattern string.

Note:
        This will also work for TOML but we recommend using version_toml for TOML files as it actually will interpret the TOML file and replace the version number before writing the file back to disk.

This is a comprehensive list (but not all variations) of examples where the following versions will be matched and replaced by the new version:

            # Common variable declaration formats
            version='1.2.3'
            version = "1.2.3"
            release = "v1.2.3"     # if tag_format is set

            # YAML
            version: 1.2.3

            # JSON
            "version": "1.2.3"

            # NPM & GitHub Actions YAML
            version@1.2.3
            version@v1.2.3        # if tag_format is set

            # Walrus Operator
            version := "1.2.3"

            # Excessive whitespace
            version        =    '1.2.3'

            # Mixed Quotes
            "version" = '1.2.3'

            # Custom Tag Format with tag_format set (monorepos)
            __release__ = "module-v1.2.3"

            # requirements.txt
            my-package == 1.2.3

            # C-Macro style (no operand only whitespace required)
            #define VERSION "1.2.3"

Important:
        The Regular Expression expects a version value to exist in the file to be replaced. It cannot be an empty string or a non-semver compliant string. If this is the very first time you are using PSR, we recommend you set the version to 0.0.0.

        This may become more flexible in the future with resolution of issue #941 <https://github.com/python-semantic-release/python-semantic-release/issues/941>.

Warning:
        If the file (ex. JSON) you are replacing has two of the same variable name in it, this pattern match will not be able to differentiate between the two and will replace both. This is a limitation of the pattern matching and not a bug.

Default: []

  Automated 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.

  Guides

  Travis CI

This guide expects you to have activated the repository on Travis CI. If this is not the case, please refer to Travis documentation <https://docs.travis-ci.com/> on how to do that.

  1. Add python-semantic-release settings

See Configuration <> for details on how to configure Python Semantic Release. Make sure that at least you have set version_variables <#config-version-variables> before continuing.

  2. Add environment variables

You will need to set up an environment variable in Travis. An easy way to do that is to go to the settings page for your package and add it there. Make sure that the secret toggle is set correctly.

You need to set the GH_TOKEN <#config-remote-token> environment variable with a personal access token for Github. It will need either repo or public_repo scope depending on whether the repository is private or public.

More information on how to set environment variables can be found on Travis documentation on environment variables <https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings>.

  3. Add travis configuration

The following should be added to your .travis.yml file.

            after_success:
            - git config --global user.name "semantic-release (via TravisCI)"
            - git config --global user.email "semantic-release@travis"
            - pip install python-semantic-release
            - semantic-release version && semantic-release publish

The first line tells Travis that we want to run the listed tasks after a successful build. The two first lines in after_success will configure git so that python-semantic-release will be able to commit on Travis. The third installs the latest version of python-semantic-release. The last will run the publish command, which will publish a new version if the changes indicate that one is due.

  4. Push some changes

You are now ready to release automatically on Travis CI on every change to your master branch.

Happy coding!

  GitHub Actions

There are two official GitHub Actions for Python Semantic Release:

    1.

        python-semantic-release/python-semantic-release@TAG
            This is the main action that runs the version CLI command. It is used to (1) determine the next version number, (2) stamp the version number, (3) run the build command, (4) build the changelog, (5) commit the changes, (6) tag the commit, (7) publish the commit & tag and lastly (8) create a GitHub release. For more information review the version command documentation and see below for the Action configuration options.

    2.

        python-semantic-release/publish-action@TAG
            This action is used to execute the publish CLI command. It is used to upload files, such as distribution artifacts and other assets, to a GitHub release.

Included in this documentation are some recommended examples below if you want to get started quickly. These examples are not exhaustive and you will need to adjust them for your specific project needs especially if you are using a monorepo.

    •   GitHub Actions Example Workflows

    •   GitHub Actions with Monorepos

Note:
        These GitHub Actions are only simplified wrappers around the python-semantic-release CLI. Ultimately, they download and install the published package from PyPI so if you find that you are trying to do something more advanced or less common, you may need to install and use the CLI directly.

  Python Semantic Release Action

The official Python Semantic Release GitHub Action <https://github.com/marketplace/actions/python-semantic-release> is a GitHub Docker Action <https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action>, which means at the beginning of the job it will build a Docker image that contains the Python Semantic Release package and its dependencies. It will then run the job step inside the Docker Container. This is done to ensure that the environment is consistent across all GitHub Runners regardless of platform. With this choice, comes some limitations of non-configurable options like a pre-defined python version, lack of installed build tools, and an inability to utilize caching.

The primary benefit of using the GitHub Action is that it is easy to set up and use for most projects. We handle a lot of the git configuration under the hood, so you don't have to handle it yourself. There are a plenty of customization options available which are detailed individually below.

Most importantly your project's configuration file will be used as normal, as your project will be mounted into the container for the action to use.

See also:
        action.yml <https://github.com/python-semantic-release/python-semantic-release/blob/master/action.yml>: the code definition of the action

  Inputs

GitHub Action inputs are used for select configuration and provide the necessary information to execute the action. The inputs are passed to the action using the with keyword in the workflow file. Many inputs will mirror the command line options available in the version command. This section outlines each supported input and its purpose.

----

  build

Type: Literal["true", "false"]

Override whether the action should execute the build command or not. This option is equivalent to adding the command line switch --skip-build (when false) to the version command. If set to true, no command line switch is passed and the default behavior of the version is used.

Required: false

Note:
        If not set or set to true, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-skip_build option for the version command.

----

  build_metadata

Type: string

Explicitly set the build metadata of the version. This is equivalent to running the command:

            semantic-release version --build-metadata <metadata>

Required: false

See also:

            •   cmd-version-option-build-metadata option for the version command

----

  changelog

Type: Literal["true", "false"]

Override whether the action should generate a changelog or not. This option is equivalent to adding either --changelog (on true) or --no-changelog (on false) to the version command.

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-changelog options for the version command

----

  commit

Type: Literal["true", "false"]

Override whether the action should commit any changes to the local repository. Changes include the version stamps, changelog, and any other files that are modified and added to the index during the build command. This option is equivalent to adding either --commit (on true) or --no-commit (on false) to the version command.

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-commit options for the version command

----

  config_file

Path to a custom semantic-release configuration file. By default, an empty string will look for to the pyproject.toml file in the current directory. This is the same as passing the -c or --config parameter to semantic-release.

Required: false

Default: ""

See also:

            •   cmd-main-option-config for the semantic-release command

----

  directory

If the project is not at the root of the repository (like in monorepos), you can specify a sub-directory to change into before running semantic-release.

Required: false

Default: .

----

  force

Type: Literal["prerelease", "patch", "minor", "major"]

Force the next version to be a specific bump type. This is equivalent to running the command:

            semantic-release version --<type>

            # Ex: force a patch level version bump
            semantic-release version --patch

Required: false

See also:

            •   cmd-version-option-force-level options for the version command

----

  git_committer_email

The email of the account used to commit. If customized, it must be associated with the provided token.

Required: false

----

  git_committer_name

The name of the account used to commit. If customized, it must be associated with the provided token.

Required: false

----

  github_token

The GitHub Token is essential for access to your GitHub repository to allow the push of commits & tags as well as to create a release. Not only do you need to provide the token as an input but you also need to ensure that the token has the correct permissions.

The token should have the following permissions <https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions>:

    •   id-token: write

    •   contents: write

Required: true

----

  no_operation_mode

If set to true, the github action will pass the --noop parameter to semantic-release. This will cause semantic-release to run in "no operation" mode.

This is useful for testing the action without making any permanent changes to the repository.

Required: false

Default: false

See also:

            •   cmd-main-option-noop option for the semantic-release command

----

  prerelease

Force the version to be a prerelease version when set to true. This is equivalent to running the command:

            semantic-release version --as-prerelease

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-as-prerelease option for the version command

----

  prerelease_token

Override any prerelease token in the configuration file with this value, if it is a pre-release. This will override the matching release branch configuration's prerelease_token value. If you always want it to be a prerelease then you must also set the prerelease input to true.

This option is equivalent to running the command:

            semantic-release version --prerelease-token <token>

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-prerelease-token option for the version command

----

  push

Type: Literal["true", "false"]

Override whether the action should push any commits or tags from the local repository to the remote repository. This option is equivalent to adding either --push (on true) or --no-push (on false) to the version command.

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-push options for the version command

----

  root_options

Important:
        This option has been removed in v10.0.0 and newer because of a command injection vulnerability. Please update as to v10.0.0 as soon as possible. See Upgrading to v10 <#upgrade-v10-root-options> for more information.

Additional options for the main semantic-release command, which will come before the version subcommand.
        Example

                    - uses: python-semantic-release/python-semantic-release@v9
                      with:
                        root_options: "-vv --noop"

        This configuration would cause the command to be semantic-release -vv --noop version, which would run the version command verbosely but in no-operation mode.

Required: false

Default: -v

See also:

            •   Options for the semantic-release command

----

  ssh_public_signing_key

The public key associated with the private key used in signing a commit and tag.

Required: false

----

  ssh_private_signing_key

The private key used to sign a commit and tag.

Required: false

----

  strict

If set to true, the github action will pass the --strict parameter to semantic-release.

See also:

            •   cmd-main-option-strict option for the semantic-release command

----

  tag

Type: Literal["true", "false"]

Override whether the action should create a version tag in the local repository. This option is equivalent to adding either --tag (on true) or --no-tag (on false) to the version command.

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-tag options for the version command

----

  vcs_release

Type: Literal["true", "false"]

Override whether the action should create a release on the VCS. This option is equivalent to adding either --vcs-release (on true) or --no-vcs-release (on false) to the version command.

Required: false

Note:
        If not set, the default behavior is defined by the version command and any user configurations <#config-root>.

See also:

            •   cmd-version-option-vcs-release options for the version command

----

  verbosity

Set the verbosity level of the output as the number of -v's to pass to semantic-release. 0 is no extra output, 1 is info level output, 2 is debug output, and 3 is a silly amount of debug output.

Required: false

Default: "1"

See also:

            •   cmd-main-option-verbosity for the semantic-release command

----

  Outputs

The Python Semantic Release Action also provides outputs that can be used in subsequent steps of the workflow. These outputs are used to provide information about the release and any actions that were taken.

----

  commit_sha

Type: string

The commit SHA of the release if a release was made, otherwise an empty string.

Example upon release: d4c3b2a1e0f9c8b7a6e5d4c3b2a1e0f9c8b7a6e5 Example when no release was made: ""

----

  is_prerelease

Type: Literal["true", "false"]

A boolean value indicating whether the released version is a prerelease.

----

  link

Type: string

The URL link to the release if a release was made, otherwise an empty string.

Example upon release: https://github.com/user/repo/releases/tag/v1.2.3 Example when no release was made: ""

----

  previous_version

Type: string

The previous version before the release, if a release was or will be made. If no release is detected, this will be the current version or an empty string if no previous version exists.

----

  released

Type: Literal["true", "false"]

A boolean value indicating whether a release was made.

----

  release_notes

Type: string

The release notes generated by the release, if any. If no release was made, this will be an empty string.

----

  version

Type: string

The newly released SemVer version string if one was made, otherwise the current version.

Example: 1.2.3

----

  tag

Type: string

The Git tag corresponding to the version output but in the tag format dictated by your configuration.

Example: v1.2.3

----

  Python Semantic Release Publish Action

The official Python Semantic Release Publish Action <https://github.com/marketplace/actions/python-semantic-release-publish> is a GitHub Docker Action <https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action>, which means at the beginning of the job it will build a Docker image that contains the Python Semantic Release package and its dependencies. It will then run the job step inside the Docker Container. This is done to ensure that the environment is consistent across all GitHub Runners regardless of platform. With this choice, comes some limitations of non-configurable options like a pre-defined python version, lack of additional 3rd party tools, and an inability to utilize caching.

The primary benefit of using the GitHub Action is that it is easy to set up and use for most projects. We handle some additional configuration under the hood, so you don't have to handle it yourself. We do however provide a few customization options which are detailed individually below.

Most importantly your project's configuration file will be used as normal, as your project will be mounted into the container for the action to use.

If you have issues with the action, please open an issue on the python-semantic-release/publish-action <https://github.com/python-semantic-release/publish-action/issues> repository.

See also:

            •   action.yml <https://github.com/python-semantic-release/publish-action/blob/main/action.yml>: the code definition for the publish action

  Inputs

GitHub Action inputs are used for select configuration and provide the necessary information to execute the action. The inputs are passed to the action using the with keyword in the workflow file. Many inputs will mirror the command line options available in the publish command and others will be specific to adjustment of the action environment. This section outlines each supported input and its purpose.

----

  config_file

Path to a custom semantic-release configuration file. By default, an empty string will look for to the pyproject.toml file in the current directory. This is the same as passing the -c or --config parameter to semantic-release.

Required: false

Default: ""

See also:

            •   cmd-main-option-config for the semantic-release command

----

  directory

If the project is not at the root of the repository (like in monorepos), you can specify a sub-directory to change into before running semantic-release.

Required: false

Default: .

----

  github_token

The GitHub Token is essential for access to your GitHub repository to allow the publish of assets to a release. Not only do you need to provide the token as an input but you also need to ensure that the token has the correct permissions.

The token should have the following permissions <https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions>:

    •   contents: write: Required for modifying a GitHub Release

Required: true

----

  no_operation_mode

If set to true, the github action will pass the --noop parameter to semantic-release. This will cause semantic-release to run in "no operation" mode.

This is useful for testing the action without actually publishing anything.

Required: false

Default: false

See also:

            •   cmd-main-option-noop option for the semantic-release command

----

  root_options

Important:
        This option has been removed in v10.0.0 and newer because of a command injection vulnerability. Please update as to v10.0.0 as soon as possible. See Upgrading to v10 <#upgrade-v10-root-options> for more information.

Additional options for the main semantic-release command, which will come before the publish subcommand.
        Example

                    - uses: python-semantic-release/publish-action@v9
                      with:
                        root_options: "-vv --noop"

        This configuration would cause the command to be semantic-release -vv --noop publish, which would run the publish command verbosely but in no-operation mode.

Required: false

Default: -v

See also:

            •   Options for the semantic-release command

----

  tag

Type: string

The tag corresponding to the GitHub Release that the artifacts should be published to. This option is equivalent to running the command:

            semantic-release publish --tag <tag>

Python Semantic Release will automatically determine the latest release if no --tag option is provided.

Required: false

See also:

            •   cmd-publish-option-tag option for the publish command

----

  verbosity

Set the verbosity level of the output as the number of -v's to pass to semantic-release. 0 is no extra output, 1 is info level output, 2 is debug output, and 3 is a silly amount of debug output.

Required: false

Default: "1"

See also:

            •   cmd-main-option-verbosity for the semantic-release command

----

  Outputs

There are no outputs provided by the Python Semantic Release Publish Action at this time.

Note:
        If you would like outputs to be provided by this action, please open an issue on the python-semantic-release/publish-action <https://github.com/python-semantic-release/publish-action/issues> repository.

----

  Examples

  Common Workflow Example

The following is a simple common workflow example that uses both the Python Semantic Release Action and the Python Semantic Release Publish Action. This workflow will run on every push to the main branch and will create a new release upon a successful version determination. If a version is released, the workflow will then publish the package to PyPI and upload the package to the GitHub Release Assets as well.

            name: Continuous Delivery

            on:
              push:
                branches:
                  - main

            # default: least privileged permissions across all jobs
            permissions:
              contents: read

            jobs:
              release:
                runs-on: ubuntu-latest
                concurrency:
                  group: ${{ github.workflow }}-release-${{ github.ref_name }}
                  cancel-in-progress: false

                permissions:
                  contents: write

                steps:
                  # Note: We checkout the repository at the branch that triggered the workflow.
                  # Python Semantic Release will automatically convert shallow clones to full clones
                  # if needed to ensure proper history evaluation. However, we forcefully reset the
                  # branch to the workflow sha because it is possible that the branch was updated
                  # while the workflow was running, which prevents accidentally releasing un-evaluated
                  # changes.
                  - name: Setup | Checkout Repository on Release Branch
                    uses: actions/checkout@v4
                    with:
                      ref: ${{ github.ref_name }}

                  - name: Setup | Force release branch to be at workflow sha
                    run: |
                      git reset --hard ${{ github.sha }}

                  - name: Action | Semantic Version Release
                    id: release
                    # Adjust tag with desired version if applicable.
                    uses: python-semantic-release/python-semantic-release@v10.5.3
                    with:
                      github_token: ${{ secrets.GITHUB_TOKEN }}
                      git_committer_name: "github-actions"
                      git_committer_email: "actions@users.noreply.github.com"

                  - name: Publish | Upload to GitHub Release Assets
                    uses: python-semantic-release/publish-action@v10.5.3
                    if: steps.release.outputs.released == 'true'
                    with:
                      github_token: ${{ secrets.GITHUB_TOKEN }}
                      tag: ${{ steps.release.outputs.tag }}

                  - name: Upload | Distribution Artifacts
                    uses: actions/upload-artifact@v4
                    with:
                      name: distribution-artifacts
                      path: dist
                      if-no-files-found: error

                outputs:
                  released: ${{ steps.release.outputs.released || 'false' }}

              deploy:
                # 1. Separate out the deploy step from the publish step to run each step at
                #    the least amount of token privilege
                # 2. Also, deployments can fail, and its better to have a separate job if you need to retry
                #    and it won't require reversing the release.
                runs-on: ubuntu-latest
                needs: release
                if: ${{ needs.release.outputs.released == 'true' }}

                permissions:
                  contents: read
                  id-token: write

                steps:
                  - name: Setup | Download Build Artifacts
                    uses: actions/download-artifact@v4
                    id: artifact-download
                    with:
                      name: distribution-artifacts
                      path: dist

                  # ------------------------------------------------------------------- #
                  # Python Semantic Release is not responsible for publishing your      #
                  # python artifacts to PyPI. Use the official PyPA publish action      #
                  # instead. The following steps are an example but is not guaranteed   #
                  # to work as the action is not maintained by the                      #
                  # python-semantic-release team.                                       #
                  # ------------------------------------------------------------------- #

                  # see https://docs.pypi.org/trusted-publishers/
                  - name: Publish package distributions to PyPI
                    uses: pypa/gh-action-pypi-publish@@SHA1_HASH  # vX.X.X
                    with:
                      packages-dir: dist
                      print-hash: true
                      verbose: true

Important:
        The concurrency <https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idconcurrency> directive is used on the job to prevent race conditions of more than one release job in the case if there are multiple pushes to main in a short period of time.

Warning:
        The GITHUB_TOKEN secret is automatically configured by GitHub, with the same permissions role as the user who triggered the workflow run. This causes a problem if your default branch is protected to specific users.

        You can work around this by storing an administrator's Personal Access Token as a separate secret and using that instead of GITHUB_TOKEN. In this case, you will also need to pass the new token to actions/checkout (as the token input) in order to gain push access.

Note:
        As of v10.5.0, Python Semantic Release automatically detects and converts shallow clones to full clones when needed. While you can still use fetch-depth: 0 with actions/checkout@v4 to fetch the full history upfront, it is no longer required. If you use the default shallow clone, Python Semantic Release will automatically fetch the full history before evaluating commits. If you are using an older version of PSR, you will need to unshallow the repository prior to use.

Note:
        As of v10.5.0, the verify upstream step is no longer required as it has been integrated into PSR directly. If you are using an older version of PSR, you will need to review the older documentation for that step. See Issue #1201 <https://github.com/python-semantic-release/python-semantic-release/issues/1201> for more details.

  Version Overrides Example

In the case where you want to provide multiple command line options to the version command, you provide them through the with directive in the workflow file. In this example, we want to force a patch version bump, not produce a changelog, and provide specialized build metadata. As a regular CLI command, this would look like:

            semantic-release version --patch --no-changelog --build-metadata abc123

The equivalent GitHub Action configuration would be:

            # snippet

            - name: Action | Semantic Version Release
              # Adjust tag with desired version if applicable.
              uses: python-semantic-release/python-semantic-release@v10.5.3
              with:
                github_token: ${{ secrets.GITHUB_TOKEN }}
                force: patch
                changelog: false
                build_metadata: abc123

See also:

            •   Publish Action Manual Release Workflow <https://github.com/python-semantic-release/publish-action/blob/main/.github/workflows/release.yml>: To maintain the Publish Action at the same version as Python Semantic Release, we use a Manual release workflow which forces the matching bump type as the root project. Check out this workflow to see how you can manually provide input that triggers the desired version bump.

  Actions with Monorepos

While python-semantic-release does NOT have full monorepo support, if you have multiple projects stored within a single repository (or your project is not at the root of the repository), you can pass the directory input to the action to change directory before semantic-release execution.

For multiple packages, you would need to run the action multiple times, to release each project. The following example demonstrates how to release two projects in a monorepo.

Remember that for each release of each submodule you will then need to handle publishing each package separately as well. This is dependent on the result of your build commands. In the example below, we assume a simple build module command to build a sdist and wheel artifacts into the submodule's dist directory.

The directory input directive is also available for the Python Semantic Release Publish Action.

            jobs:

              release:

                env:
                  SUBMODULE_1_DIR: project1
                  SUBMODULE_2_DIR: project2

                steps:

                  # ------------------------------------------------------------------- #
                  # Note the use of different IDs to distinguish which submodule was    #
                  # identified to be released. The subsequent actions then reference    #
                  # their specific release ID to determine if a release occurred.       #
                  # ------------------------------------------------------------------- #

                  - name: Release submodule 1
                    id: release-submod-1
                    uses: python-semantic-release/python-semantic-release@v10.5.3
                    with:
                      directory: ${{ env.SUBMODULE_1_DIR }}
                      github_token: ${{ secrets.GITHUB_TOKEN }}

                  - name: Release submodule 2
                    id: release-submod-2
                    uses: python-semantic-release/python-semantic-release@v10.5.3
                    with:
                      directory: ${{ env.SUBMODULE_2_DIR }}
                      github_token: ${{ secrets.GITHUB_TOKEN }}

                  # ------------------------------------------------------------------- #
                  # For each submodule, you will have to publish the package separately #
                  # and only attempt to publish if the release for that submodule was   #
                  # deemed a release (and the release was successful).                  #
                  # ------------------------------------------------------------------- #

                  - name: Publish | Upload package 1 to GitHub Release Assets
                    uses: python-semantic-release/publish-action@v10.5.3
                    if: steps.release-submod-1.outputs.released == 'true'
                    with:
                      directory: ${{ env.SUBMODULE_1_DIR }}
                      github_token: ${{ secrets.GITHUB_TOKEN }}
                      tag: ${{ steps.release-submod-1.outputs.tag }}

                  - name: Publish | Upload package 2 to GitHub Release Assets
                    uses: python-semantic-release/publish-action@v10.5.3
                    if: steps.release-submod-2.outputs.released == 'true'
                    with:
                      directory: ${{ env.SUBMODULE_2_DIR }}
                      github_token: ${{ secrets.GITHUB_TOKEN }}
                      tag: ${{ steps.release-submod-2.outputs.tag }}

                  # ------------------------------------------------------------------- #
                  # Python Semantic Release is not responsible for publishing your      #
                  # python artifacts to PyPI. Use the official PyPA publish action      #
                  # instead. The following steps are an example but is not guaranteed   #
                  # to work as the action is not maintained by the                      #
                  # python-semantic-release team.                                       #
                  # ------------------------------------------------------------------- #

                  - name: Publish | Upload package 1 to PyPI
                    uses: pypa/gh-action-pypi-publish@SHA1_HASH  # vX.X.X
                    if: steps.release-submod-1.outputs.released == 'true'
                    with:
                      packages-dir: ${{ format('{}/dist', env.SUBMODULE_1_DIR) }}

                  - name: Publish | Upload package 2 to PyPI
                    uses: pypa/gh-action-pypi-publish@SHA1_HASH  # vX.X.X
                    if: steps.release-submod-2.outputs.released == 'true'
                    with:
                      packages-dir: ${{ format('{}/dist', env.SUBMODULE_2_DIR) }}

  Cron Job Publishing

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.

    1.  Create a virtualenv:

                virtualenv semantic_release -p `which python3`

    2.  Install python-semantic-release:

                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 version && $VENV/semantic-release publish
              cd ..
            }

            publish <package1>
            publish <package2>

    4.  Add cronjob:

                /bin/bash -c "cd <path> && source semantic_release/bin/activate && ./publish 2>&1 >> releases.log"

  Upgrading PSR

Upgrading PSR is a process that may involve several steps, depending on the version you are upgrading from and to. This section provides a guide for upgrading from older versions of PSR to the latest version.

Important:
        If you are upgrading across more than one major version, you should incrementally upgrade through each major version and its configuration update guide to ensure a smooth transition.

        For example, if you are upgrading from v7 to v10, you should first upgrade to v8 and then to v9, and then lastly to v10 while following the upgrade guide for each version. At each step you should confirm execution works as expected before proceeding to the next version.

  Upgrading to v10

The upgrade to v10 is primarily motivated by a command injection security vulnerability found in the GitHub Actions configuration interpreter (see details below). We also bundled a number of other changes, including new default configuration values and most importantly, a return to 1-line commit subjects in the default changelog format.

For more specific change details for v10, please refer to the v10.0.0 (2025-05-25) <#changelog-v10-0-0> section of the CHANGELOG <#changelog>.

  Security Fix: Command Injection Vulnerability (GitHub Actions)

In the previous versions of the GitHub Actions configuration, we used a single root_options parameter to pass any options you wanted to pass to the semantic-release main command. This parameter was interpreted as a string and passed directly to the command line, which made it vulnerable to command injection attacks. An attacker could exploit this by crafting a malicious string as the root_options <#gh-actions-psr-inputs-root-options> input, and then it would be executed as part of the command line, potentially allowing them to run arbitrary commands within the GitHub Actions Docker container. The ability to exploit this vulnerability is limited to people whom can modify the GitHub Actions workflow file, which is typically only the repository maintainers unless you are pointing at an organizational workflow file or another third-party workflow file.

To mitigate this vulnerability, we have removed the root_options parameter completely and replaced it with individual boolean flag inputs which are then used to select the proper cli parameters for the semantic-release command. Additionally, users can protect themselves by limiting the access to secrets in their GitHub Actions workflows and the permissions of the GitHub Actions CI TOKEN.

This vulnerability existed in both the python-semantic-release/python-semantic-release <#gh-actions-psr> and python-semantic-release/publish-action <#gh-actions-publish> actions.

For the main python-semantic-release/python-semantic-release <#gh-actions-psr> action, the following inputs are now available (in place of the old root_options parameter): config_file <#gh-actions-psr-inputs-config-file>, no_operation_mode <#gh-actions-psr-inputs-noop>, strict <#gh-actions-psr-inputs-strict>, and verbosity <#gh-actions-psr-inputs-verbosity>.
        Example migration

        If you previously had the following in your GitHub Actions workflow file:

                    - uses: python-semantic-release/python-semantic-release@v9
                      with:
                        root_options: "-vv --strict"

        It would be updated to:

                    - uses: python-semantic-release/python-semantic-release@v10
                      with:
                        strict: true
                        verbosity: 2

For the python-semantic-release/publish-action <#gh-actions-publish> action, the following inputs are now available (in place of the old root_options parameter): config_file <#gh-actions-publish-inputs-config-file>, no_operation_mode <#gh-actions-publish-inputs-noop>, and verbosity <#gh-actions-publish-inputs-verbosity>.
        Example migration

        If you previously had the following in your GitHub Actions workflow file:

                    - uses: python-semantic-release/publish-action@v9
                      with:
                        root_options: "-v -c /path/to/releaserc.yaml"

        It would be updated to:

                    - uses: python-semantic-release/publish-action@v10
                      with:
                        config_file: /path/to/releaserc.yaml
                        verbosity: 1

  Changelog Format: 1-Line Commit Subjects

In v10, the default changelog format has been changed to use 1-line commit subjects instead of including the full commit message. This change was made to improve the readability of the changelog as many commit messages are long and contain unnecessary details for the changelog.

Important:
        If you use a squash commit merge strategy, it is recommended that you use the default parse_squash_commits commit parser option to ensure that all the squashed commits are parsed for version bumping and changelog generation. This is the default behavior in v10 across all supported commit parsers. If you are upgrading, you likely will need to manually set this option in your configuration file to ensure that the changelog is generated correctly.

        If you do not enable parse_squash_commits, then version will only be determined by the commit subject line and the changelog will only include the commit subject line as well.

  Changelog Format: Mask Initial Release

In v10, the default behavior for the changelog generation has been changed to mask the initial release in the changelog. This means that the first release will not contain a break down of the different types of changes (e.g., features, fixes, etc.), but instead it will just simply state that this is the initial release.

  Changelog Format: Commit Parsing

We have made some minor changes to the commit parsing logic in v10 to separate out components of the commit message more clearly. You will find that the ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> object's descriptions list will no longer contain any Breaking Change footers, Release Notice footers, PR/MR references, or Issue Closure footers. These were all previously extracted and placed into their own attributes but were still included in the descriptions list. In v10, the descriptions list will only contain the actual commit subject line and any additional commit body text that is not part of the pre-defined footers.

If you were relying on the descriptions list to contain these footers, you will need to update your code and changelog templates to reference the specific attributes you want to use.

  Default Configuration Changes

The following table summarizes the changes to the default configuration values in v10:
# | Configuration Option | Previous Default Value | New Default Value
1 | allow_zero_version <#config-allow-zero-version> | true | false
2 | changelog.mode <#config-changelog-mode> | init | update
3 | changelog.default_templates.mask_initial_release <#config-changelog-default-templates-mask-initial-release> | false | true
4 | commit_parser_options.parse_squash_commits <#config-commit-parser-options> | false | true
5 | commit_parser_options.ignore_merge_commits <#config-commit-parser-options> | false | true

  Deprecations & Removals

No additional deprecations were made in v10, but the following are staged for removal in v11:

  Deprecated Features & Functions
# | Component | Deprecated | Planned Removal | Notes
1 | GitHub Actions root_options <#gh-actions-psr-inputs-root-options> | v10.0.0 | v10.0.0 | Replaced with individual boolean flag inputs. See above for details.
2 | Angular Commit Parser <#commit-parser-builtin-angular> | v9.19.0 | v11.0.0 | Replaced by the Conventional Commit Parser <#commit-parser-builtin-conventional>.
3 | Tag Commit Parser <#commit-parser-builtin-tag> | v9.12.0 | v11.0.0 | Replaced by the Emoji Commit Parser <#commit-parser-builtin-emoji>.

Note:
        For the most up-to-date information on the next version deprecations and removals, please refer to the issue #1066 <https://github.com/python-semantic-release/python-semantic-release/issues/1066>.

  Upgrading to v9

You are in luck! The upgrade to v9 is a simple one.

The breaking change for this version is the removal of support for Python 3.7, as it has passed End-Of-Life (EOL). This means that if you are using Python 3.7, you will need to upgrade to at least Python 3.8 in order to use v9. This will be permanent as all future versions of python-semantic-release will require Python 3.8 or later.

  Upgrading to v8

Python Semantic Release v8.0.0 introduced a number of breaking changes. The internals have been changed significantly to better support highly-requested features and to streamline the maintenance of the project.

As a result, certain things have been removed, reimplemented differently, or now exhibit different behavior to earlier versions of Python Semantic Release. This page is a guide to help projects to pip install python-semantic-release>=8.0.0 with fewer surprises.

  Python Semantic Release GitHub Action

  GitHub Action no longer publishes artifacts to PyPI or GitHub Releases

Python Semantic Release no longer uploads distributions to PyPI - see Repurposing of version and publish commands. If you are using Python Semantic Release to publish release notes and artifacts to GitHub releases, there is a new GitHub Action upload-to-gh-release <https://github.com/python-semantic-release/upload-to-gh-release> which will perform this action for you.

This means the following workflows perform the same actions, and if you are using the former, you will need to modify your workflow to include the steps in the latter.

This workflow is written to use Python Semantic Release v7.33.5:

            ---
            name: Semantic Release

            on:
              push:
                branches:
                  - main

            jobs:
              release:
                runs-on: ubuntu-latest
                concurrency: release

                steps:
                - uses: actions/checkout@v3
                  with:
                    fetch-depth: 0

                # This action uses Python Semantic Release v7
                - name: Python Semantic Release
                  uses: python-semantic-release/python-semantic-release@v7.33.5
                  with:
                    github_token: ${{ secrets.GITHUB_TOKEN }}
                    repository_username: __token__
                    repository_password: ${{ secrets.PYPI_TOKEN }}

The following workflow achieves the same result using Python Semantic Release v8, the upload-to-gh-release <https://github.com/python-semantic-release/upload-to-gh-release> GitHub Action, and the pypa/gh-action-pypi-publish <https://github.com/pypa/gh-action-pypi-publish> GitHub Action:

            ---
            name: Semantic Release

            on:
              push:
                branches:
                  - main

            jobs:
              release:
                runs-on: ubuntu-latest
                concurrency: release
                permissions:
                  id-token: write

                steps:
                - uses: actions/checkout@v3
                  with:
                    fetch-depth: 0

                # This action uses Python Semantic Release v8
                - name: Python Semantic Release
                  id: release
                  uses: python-semantic-release/python-semantic-release@v8.7.0
                  with:
                    github_token: ${{ secrets.GITHUB_TOKEN }}

                - name: Publish package distributions to PyPI
                  uses: pypa/gh-action-pypi-publish@v1
                  # NOTE: DO NOT wrap the conditional in ${{ }} as it will always evaluate to true.
                  # See https://github.com/actions/runner/issues/1173
                  if: steps.release.outputs.released == 'true'

                - name: Publish package distributions to GitHub Releases
                  uses: python-semantic-release/upload-to-gh-release@v8.7.0
                  if: steps.release.outputs.released == 'true'
                  with:
                    github_token: ${{ secrets.GITHUB_TOKEN }}

  Removal of pypi_token, repository_username and repository_password inputs

Since the library no longer supports publishing to PyPI, the pypi_token, repository_username and repository_password inputs of the GitHub action have all been removed. See the above section for how to publish to PyPI using the official GitHub Action from the Python Packaging Authority (PyPA).

  Rename additional_options to root_options

Because the purposes of the cmd-version and cmd-publish commands have changed, the GitHub action now performs both commands in sequence. For this reason, and because the usage of the CLI has changed, additional_options has been renamed to root_options to reflect the fact that the options are for the main cmd-main command group.

  Commands

  Repurposing of version and publish commands

Python Semantic Release's primary purpose is to enable automation of correct semantic versioning for software projects. Over the years, this automation has been extended to include other actions such as building/publishing the project and its artifacts to artefact repositories, creating releases in remote version control systems, and writing changelogs.

In Python Semantic Release <8.0.0, the publish command was a one-stop-shop for performing every piece of automation provided. This has been changed - the version command now handles determining the next version, applying the changes to the project metadata according to the configuration, writing a changelog, and committing/pushing changes to the remote Git repository. It also handles creating a release in the remote VCS. It does not publish software artifacts to remote repositories such as PyPI; the rationale behind this decision is simply that under the hood, Python Semantic Release used twine <https://twine.readthedocs.io/en/stable> to upload artifacts to package indexes such as PyPI, and it's recommended to use twine directly via the command-line. From the twine documentation <https://twine.readthedocs.io/en/stable/contributing.html#architectural-overview>:
        Twine is a command-line tool for interacting with PyPI securely over HTTPS.

As a result Python Semantic Release no longer depends on twine internals.

The publish command now handles publishing software artifacts to releases in the remote version control system.

To achieve a similar flow of logic such as

            1.  Determine the next version

            2.  Write this version to the configured metadata locations

            3.  Write the changelog

            4.  Push the changes to the metadata and changelog to the remote repository

            5.  Create a release in the remote version control system

            6.  Build a wheel

            7.  Publish the wheel to PyPI

            8.  Publish the distribution artifacts to the release in the remote VCS

You should run:

            semantic-release version
            twine upload dist/*  # or whichever path your distributions are placed in
            semantic-release publish

With steps 1-6 being handled by the cmd-version command, step 7 being left to the developer to handle, and lastly step 8 to be handled by the cmd-publish command.

  Removal of -D/--define command-line option

It is no longer possible to override arbitrary configuration values using the -D/ --define option. You should provide the appropriate values via a configuration file using cmd-main-option-config or via the available command-line options.

This simplifies the command-line option parsing significantly and is less error-prone, which has resulted in previous issues (e.g. #600 <https://github.com/python-semantic-release/python-semantic-release/issues/600>) with overrides on the command-line. Some of the configuration values expected by Python Semantic Release use complex data types such as lists or nested structures, which would be tedious and error-prone to specify using just command-line options.

  Removal of CI verifications

Prior to v8, Python Semantic Release would perform some prerequisite verification of environment variables before performing any version changes using the publish command. It's not feasible for Python Semantic Release to verify any possible CI environment fully, and these checks were only triggered if certain environment variables were set - they wouldn't fail locally.

These checks previously raised :py:class:semantic_release.CiVerificationError, and were the only place in which this custom exception was used. Therefore, this exception has also been removed from Python Semantic Release in v8.

If you were relying on this functionality, it's recommended that you add the following shell commands before invoking semantic-release to verify your environment:

Note:
        In the following, $RELEASE_BRANCH refers to the git branch against which you run your releases using Python Semantic Release. You will need to ensure it is set properly (e.g. via export RELEASE_BRANCH=main and/or replace the variable with the branch name you want to verify the CI environment for.

  Travis

Condition: environment variable TRAVIS=true

Replacement:

            if ! [[
                  $TRAVIS_BRANCH == $RELEASE_BRANCH  && \
                  $TRAVIS_PULL_REQUEST == 'false'
                ]]; then
              exit 1
            fi

  Semaphore

Condition: environment variable SEMAPHORE=true

Replacement:

            if ! [[
                    $BRANCH_NAME == $RELEASE_BRANCH && \
                    $SEMAPHORE_THREAD_RESULT != 'failed' && \
                    -n $PULL_REQUEST_NUMBER
                ]]; then
              exit 1
            fi

  Frigg

Condition: environment variable FRIGG=true

Replacement:

            if ! [[
                  $FRIGG_BUILD_BRANCH == $RELEASE_BRANCH && \
                  -n $FRIGG_PULL_REQUEST
                ]]; then
              exit 1
            fi

  Circle CI

Condition: environment variable CIRCLECI=true

Replacement:

            if ! [[
                  $CIRCLE_BRANCH == $RELEASE_BRANCH && \
                  -n $CI_PULL_REQUEST
                ]]; then
              exit 1
            fi

  GitLab CI

Condition: environment variable GITLAB_CI=true

Replacement:

            if ! [[ $CI_COMMIT_REF_NAME == $RELEASE_BRANCH ]]; then
              exit 1
            fi

Condition: environment variable BITBUCKET_BUILD_NUMBER is set

Replacement:

            if ! [[
                  $BITBUCKET_BRANCH == $RELEASE_BRANCH && \
                  -n $BITBUCKET_PR_ID
                ]]; then
              exit 1
            fi

  Jenkins

Condition: environment variable JENKINS_URL is set

Replacement:

            if [[ -z $BRANCH_NAME ]]; then
              BRANCH_NAME=$BRANCH_NAME
            elif [[ -z $GIT_BRANCH ]]; then
              BRANCH_NAME=$GIT_BRANCH
            fi

            if ! [[
                  $BRANCH_NAME == $RELEASE_BRANCH && \
                  -n $CHANGE_ID
                ]]; then
              exit 1
            fi

  Removal of Build Status Checking

Prior to v8, Python Semantic Release contained a configuration option, check_build_status, which would attempt to prevent a release being made if it was possible to identify that a corresponding build pipeline was failing. For similar reasons to those motivating the removal of CI Checks, this feature has also been removed.

If you are leveraging this feature in Python Semantic Release v7, the following bash commands will replace the functionality, and you can add these to your pipeline. You will need to install jq and curl to run these commands; they can be easily installed through your system's package manager, for example on Ubuntu:

            sudo apt update && sudo apt upgrade
            sudo apt install -y curl jq

On Windows, you can refer to the installation guide for jq <https://jqlang.github.io/jq/download/>, and if curl is not already installed, you can download it from the curl website <https://curl.se/>

  GitHub

            export RESP="$(
              curl \
                 -H "Authorization: token $GITHUB_TOKEN" \
                 -fSsL https://$GITHUB_API_DOMAIN/repos/$REPO_OWNER/$REPO_NAME/commits/$(git rev-parse HEAD)/status || exit 1
            )"

            if [ $(jq -r '.state' <<< "$RESP") != "success" ]; then
               echo "Build status is not success" >&2
               exit 1
            fi

Note that $GITHUB_API_DOMAIN is typically api.github.com unless you are using GitHub Enterprise with a custom domain name.

  Gitea

            export RESP="$(
              curl \
                 -H "Authorization: token $GITEA_TOKEN" \
                 -fSsL https://$GITEA_DOMAIN/repos/$REPO_OWNER/$REPO_NAME/statuses/$(git rev-parse HEAD) || exit 1
            )"

            if [ $(jq -r '.state' <<< "$RESP") != "success" ]; then
               echo "Build status is not success" >&2
               exit 1
            fi

  Gitlab

             export RESP="$(
               curl \
                  -H "Authorization: token $GITLAB_TOKEN" \
                  -fSsL https://$GITLAB_DOMAIN/api/v4/projects/$PROJECT_ID/repository/commits/$(git rev-parse HEAD)/statuses
             )"

             for line in $(jq -r '.[] | [.name, .status, .allow_failure] | join("|")' <<<"$RESP"); do
               IFS="|" read -r job_name job_status allow_failure <<<"$line"

               if [ "$job_status" == "pending" ]; then
                  echo "job $job_name is pending" >&2
                  exit 1
               elif [ "$job_status" == "failed" ] && [ ! "$allow_failure" == "true" ]; then
                  echo "job $job_name failed" >&2
                  exit 1
               fi
            done

  Multibranch releases

Prior to v8, Python Semantic Release would perform git checkout to switch to your configured release branch and determine if a release would need to be made. In v8 this has been changed - you must manually check out the branch which you would like to release against, and if you would like to create releases against this branch you must also ensure that it belongs to a release group <#multibranch-releases-configuring>.

  changelog command

A new option, cmd-changelog-option-post-to-release-tag has been added. If you omit this argument on the command line then the changelog rendering process, which is described in more detail at Custom Changelogs <#changelog-templates-template-rendering>, will be triggered, but the new changelog will not be posted to any release. If you use this new command-line option, it should be set to a tag within the remote which has a corresponding release. For example, to update the changelog and post it to the release corresponding to the tag v1.1.4, you should run:

            semantic-release changelog --post-to-release-tag v1.1.4

  Changelog customization

A number of options relevant to customizing the changelog have been removed. This is because Python Semantic Release now supports authoring a completely custom Jinja <https://jinja.palletsprojects.com/en/3.1.x/> template with the contents of your changelog. Historically, the number of options added to Python Semantic Release in order to allow this customization has grown significantly; it now uses templates in order to fully open up customizing the changelog's appearance.

  Configuration

The configuration structure has been completely reworked, so you should read Configuration <#configuration> carefully during the process of upgrading to v8+. However, some common pitfalls and potential sources of confusion are summarized here.

  setup.cfg is no longer supported

Python Semantic Release no longer supports configuration via setup.cfg. This is because the Python ecosystem is centering around pyproject.toml as universal tool and project configuration file, and TOML allows expressions via configuration, such as the mechanism for declaring configuration via environment variables, which introduce much greater complexity to support in the otherwise equivalent ini-format configuration.

You can use cmd-generate-config to generate new-format configuration that can be added to pyproject.toml, and adjust the default settings according to your needs.

Warning:
        If you don't already have a pyproject.toml configuration file, pip can change its behavior once you add one, as a result of PEP-517 <https://peps.python.org/pep-0517/#evolutionary-notes>. If you find that this breaks your packaging, you can add your Python Semantic Release configuration to a separate file such as semantic-release.toml, and use the --config option to reference this alternative configuration file.

        More detail about this issue can be found in this pip issue <https://github.com/pypa/pip/issues/8437#issuecomment-805313362>.

  Commit parser options

Options such as major_emoji, parser_angular_patch_types or parser_angular_default_level_bump have been removed. Instead, these have been replaced with a single set of recognized commit parser options, allowed_tags, major_tags, minor_tags, and patch_tags, though the interpretation of these is up to the specific parsers in use. You can read more detail about using commit parser options in commit_parser_options <#config-commit-parser-options>, and if you need to parse multiple commit styles for a single project it's recommended that you create a parser following Custom Parsers <#commit-parser-custom-parser> that is tailored to the specific needs of your project.

  version_variable

This option has been renamed to version_variables <#config-version-variables> as it refers to a list of variables which can be updated.

  version_pattern

This option has been removed. It's recommended to use an alternative tool to perform substitution using arbitrary regular expressions, such as sed. You can always use Python Semantic Release to identify the next version to be created for a project and store this in an environment variable like so:

            export VERSION=$(semantic-release version --print)

  version_toml

This option will no longer accept a string or comma-separated string of version locations to be updated in TOML files. Instead, you must supply a List[str]. For existing configurations using a single location in this option, you can simply wrap the value in []:

            # Python Semantic Release v7 configuration
            [tool.semantic_release]
            version_toml = "pyproject.toml:tool.poetry.version"

            # Python Semantic Release v8 configuration
            [tool.semantic_release]
            version_toml = ["pyproject.toml:tool.poetry.version"]

  tag_format

This option has the same effect as it did in Python Semantic Release prior to v8, but Python Semantic Release will now verify that it has a {version} format key and raise an error if this is not the case.

  upload_to_release

This option has been renamed to upload_to_vcs_release <#config-publish-upload-to-vcs-release>.

  Custom Commit Parsers

Previously, a custom commit parser had to satisfy the following criteria:

            •   It should be import-able from the virtual environment where the semantic-release is run

            •   It should be a function which accepts the commit message as its only argument and returns a semantic_release.history.parser_helpers.ParsedCommit if the commit is parsed successfully, or raise a semantic_release.UnknownCommitMessageStyleError if parsing is unsuccessful.

It is still possible to implement custom commit parsers, but the interface for doing so has been modified with stronger support for Python type annotations and broader input provided to the parser to enable capturing more information from each commit, such as the commit's date and author, if desired. A full guide to implementing a custom commit parser can be found at Custom Parsers <#commit-parser-custom-parser>.

  Troubleshooting

    •   Check your configuration file for Configuration <#configuration>

    •   Check your Git tags match your tag_format <#config-tag-format>; tags using other formats are ignored during calculation of the next version.

  Increasing Verbosity

If you are having trouble with Python Semantic Release or would like to see additional information about the actions that it is taking, you can use the top-level cmd-main-option-verbosity option. This can be supplied multiple times to increase the logging verbosity of the cmd-main command or any of its subcommands during their execution. You can supply this as many times as you like, but supplying more than twice has no effect.

Supply cmd-main-option-verbosity once for INFO output, and twice for DEBUG.

For example:

            semantic-release -vv version --print

Note:
        The cmd-main-option-verbosity option must be supplied to the top-level semantic-release command, before the name of any sub-command.

Warning:
        The volume of logs when using DEBUG verbosity may be significantly increased, compared to INFO or the default WARNING, and as a result executing commands with semantic-release may be significantly slower than when using DEBUG.

Note:
        The provided GitHub action sets the verbosity level to INFO by default.

  src

  semantic_release package

Python Semantic Release

    semantic_release.setup_hook(argv: list[str]) -> None
        A hook to be used in setup.py to enable python setup.py publish.

        Parameters
            argv -- sys.argv

  Subpackages

  semantic_release.changelog package

  Submodules

  semantic_release.changelog.context module

    class semantic_release.changelog.context.ChangelogContext(repo_name: 'str', repo_owner: 'str', hvcs_type: 'str', history: 'ReleaseHistory', changelog_mode: "Literal['update', 'init']", prev_changelog_file: 'str', changelog_insertion_flag: 'str', mask_initial_release: 'bool', filters: 'tuple[Callable[..., Any], ...]' = ())
        Bases: object

        bind_to_environment(env: Environment) -> Environment

        changelog_insertion_flag: str

        changelog_mode: Literal['update', 'init']

        filters: tuple[Callable[..., Any], ...] = ()

        history: ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>

        hvcs_type: str

        mask_initial_release: bool

        prev_changelog_file: str

        repo_name: str

        repo_owner: str

    class semantic_release.changelog.context.ChangelogMode(*values)
        Bases: Enum

        INIT = 'init'

        UPDATE = 'update'

    class semantic_release.changelog.context.ReleaseNotesContext(repo_name: 'str', repo_owner: 'str', hvcs_type: 'str', version: 'Version', release: 'Release', mask_initial_release: 'bool', license_name: 'str', filters: 'tuple[Callable[..., Any], ...]' = ())
        Bases: object

        bind_to_environment(env: Environment) -> Environment

        filters: tuple[Callable[..., Any], ...] = ()

        hvcs_type: str

        license_name: str

        mask_initial_release: bool

        release: Release <#semantic_release.changelog.release_history.Release>

        repo_name: str

        repo_owner: str

        version: Version <#semantic_release.version.version.Version>

    semantic_release.changelog.context.autofit_text_width(text: str, maxwidth: int = 100, indent_size: int = 0) -> str
        Format the description text to fit within a specified width

    semantic_release.changelog.context.convert_md_to_rst(md_content: str) -> str

    semantic_release.changelog.context.create_pypi_url(package_name: str, version: str = '') -> str

    semantic_release.changelog.context.make_changelog_context(hvcs_client: HvcsBase, release_history: ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>, mode: ChangelogMode <#semantic_release.changelog.context.ChangelogMode>, prev_changelog_file: Path, insertion_flag: str, mask_initial_release: bool) -> ChangelogContext <#semantic_release.changelog.context.ChangelogContext>

    semantic_release.changelog.context.read_file(filepath: str) -> str

  semantic_release.changelog.release_history module

    class semantic_release.changelog.release_history.Release
        Bases: TypedDict

        committer: Actor

        elements: dict[str, list[ParseResult]]

        tagged_date: datetime

        tagger: Actor

        version: Version <#semantic_release.version.version.Version>

    class semantic_release.changelog.release_history.ReleaseHistory(unreleased: dict[str, list[ParseResult]], released: dict[Version <#semantic_release.version.version.Version>, Release <#semantic_release.changelog.release_history.Release>])
        Bases: object

        classmethod from_git_history(repo: Repo, translator: VersionTranslator <#semantic_release.version.translator.VersionTranslator>, commit_parser: CommitParser[ParseResult, ParserOptions], exclude_commit_patterns: Iterable[Pattern[str]] = ()) -> ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>

        release(version: Version <#semantic_release.version.version.Version>, tagger: Actor, committer: Actor, tagged_date: datetime) -> ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>

  semantic_release.changelog.template module

    class semantic_release.changelog.template.ComplexDirectorySandboxedEnvironment(*args: Any, **kwargs: Any)
        Bases: SandboxedEnvironment

        join_path(template: str, parent: str) -> str
            Add support for complex directory structures in the template directory.

            This method overrides the default functionality of the SandboxedEnvironment where all 'include' keywords expect to be in the same directory as the calling template, however this is unintuitive when using a complex directory structure.

            This override simulates the changing of directories when you include the template from a child directory. When the child then includes a template, it will make the path relative to the child directory rather than the top level template directory.

    semantic_release.changelog.template.environment(template_dir: Path | str = '.', block_start_string: str = '{%', block_end_string: str = '%}', variable_start_string: str = '{{', variable_end_string: str = '}}', comment_start_string: str = '{#', comment_end_string: str = '#}', line_statement_prefix: str | None = None, line_comment_prefix: str | None = None, trim_blocks: bool = False, lstrip_blocks: bool = False, newline_sequence: Literal['\n', '\r', '\r\n'] = '\n', keep_trailing_newline: bool = False, extensions: Iterable[str] = (), autoescape: bool | str = True) -> SandboxedEnvironment
        Create a jinja2.sandbox.SandboxedEnvironment with certain parameter resrictions.

        For example the Loader is fixed to FileSystemLoader, although the searchpath is configurable.

        autoescape can be a string in which case it should follow the convention module:attr, in this instance it will be dynamically imported. See <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment> for full parameter descriptions

    semantic_release.changelog.template.recursive_render(template_dir: Path, environment: Environment, _root_dir: str | os.PathLike[str] = '.') -> list[str]

  semantic_release.cli package

  Subpackages

  semantic_release.cli.commands package

  Submodules

  semantic_release.cli.commands.changelog module

    semantic_release.cli.commands.changelog.get_license_name_for_release(tag_name: str, project_root: Path) -> str

    semantic_release.cli.commands.changelog.post_release_notes(release_tag: str, release_notes: str, prerelease: bool, hvcs_client: RemoteHvcsBase <#semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase>, noop: bool = False) -> None

  semantic_release.cli.commands.generate_config module

  semantic_release.cli.commands.main module

    class semantic_release.cli.commands.main.Cli(name: str | None = None, invoke_without_command: bool = False, no_args_is_help: bool | None = None, subcommand_metavar: str | None = None, chain: bool = False, result_callback: Callable[[...], Any] | None = None, **attrs: Any)
        Bases: MultiCommand

        Root MultiCommand for the semantic-release CLI

        class SubCmds(*values)
            Bases: Enum

            Subcommand import definitions

            CHANGELOG = 'semantic_release.cli.commands.changelog'

            GENERATE_CONFIG = 'semantic_release.cli.commands.generate_config'

            PUBLISH = 'semantic_release.cli.commands.publish'

            VERSION = 'semantic_release.cli.commands.version'

        get_command(_ctx: Context, name: str) -> Command | None
            Given a context and a command name, this returns a Command object if it exists or returns None.

        list_commands(_ctx: Context) -> list[str]
            Returns a list of subcommand names in the order they should appear.

  semantic_release.cli.commands.publish module

    semantic_release.cli.commands.publish.publish_distributions(tag: str, hvcs_client: RemoteHvcsBase <#semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase>, dist_glob_patterns: tuple[str, ...], noop: bool = False) -> None

  semantic_release.cli.commands.version module

    semantic_release.cli.commands.version.apply_version_to_source_files(repo_dir: Path, version_declarations: Sequence[IVersionReplacer <#semantic_release.version.declarations.i_version_replacer.IVersionReplacer>], version: Version <#semantic_release.version.version.Version>, noop: bool = False) -> list[str]

    semantic_release.cli.commands.version.build_distributions(build_command: str | None, build_command_env: Mapping[str, str] | None = None, noop: bool = False) -> None
        Run the build command to build the distributions.

        Parameters

            •   build_command -- The build command to run.

            •   build_command_env -- The environment variables to use when running the build command.

            •   noop -- Whether or not to run the build command.

        Raises
            BuildDistributionsError: if the build command fails

    semantic_release.cli.commands.version.get_windows_env() -> Mapping[str, str | None]

    semantic_release.cli.commands.version.is_forced_prerelease(as_prerelease: bool, forced_level_bump: LevelBump <#semantic_release.enums.LevelBump> | None, prerelease: bool) -> bool
        Determine if this release is forced to have prerelease on/off. If force_prerelease is set then yes. Otherwise if we are forcing a specific level bump without force_prerelease, it's False. Otherwise (force_level is None) use the value of prerelease

    semantic_release.cli.commands.version.is_windows() -> bool

    semantic_release.cli.commands.version.last_released(repo_dir: Path, tag_format: str, add_partial_tags: bool = False) -> tuple[Tag, Version <#semantic_release.version.version.Version>] | None

    semantic_release.cli.commands.version.shell(cmd: str, *, env: Mapping[str, str] | None = None, check: bool = True) -> subprocess.CompletedProcess

    semantic_release.cli.commands.version.version_from_forced_level(repo_dir: Path, forced_level_bump: LevelBump <#semantic_release.enums.LevelBump>, translator: VersionTranslator <#semantic_release.version.translator.VersionTranslator>) -> Version <#semantic_release.version.version.Version>

  Submodules

  semantic_release.cli.changelog_writer module

    semantic_release.cli.changelog_writer.apply_user_changelog_template_directory(template_dir: Path, environment: Environment, destination_dir: Path, noop: bool = False) -> list[str]

    semantic_release.cli.changelog_writer.generate_release_notes(hvcs_client: HvcsBase, release: Release <#semantic_release.changelog.release_history.Release>, template_dir: Path, history: ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>, style: str, mask_initial_release: bool, license_name: str = '') -> str

    semantic_release.cli.changelog_writer.get_default_tpl_dir(style: str, sub_dir: str | None = None) -> Path

    semantic_release.cli.changelog_writer.render_default_changelog_file(output_format: ChangelogOutputFormat <#semantic_release.cli.config.ChangelogOutputFormat>, changelog_context: ChangelogContext <#semantic_release.changelog.context.ChangelogContext>, changelog_style: str) -> str

    semantic_release.cli.changelog_writer.render_release_notes(release_notes_template_file: str, template_env: Environment) -> str

    semantic_release.cli.changelog_writer.write_changelog_files(runtime_ctx: RuntimeContext <#semantic_release.cli.config.RuntimeContext>, release_history: ReleaseHistory <#semantic_release.changelog.release_history.ReleaseHistory>, hvcs_client: HvcsBase, noop: bool = False) -> list[str]

    semantic_release.cli.changelog_writer.write_default_changelog(changelog_file: Path, destination_dir: Path, output_format: ChangelogOutputFormat <#semantic_release.cli.config.ChangelogOutputFormat>, changelog_context: ChangelogContext <#semantic_release.changelog.context.ChangelogContext>, changelog_style: str, noop: bool = False) -> str

  semantic_release.cli.cli_context module

    class semantic_release.cli.cli_context.CliContextObj(ctx: click.Context, logger: logging.Logger, global_opts: GlobalCommandLineOptions <#semantic_release.cli.config.GlobalCommandLineOptions>)
        Bases: object

        property raw_config: RawConfig <#semantic_release.cli.config.RawConfig>

        property runtime_ctx: RuntimeContext <#semantic_release.cli.config.RuntimeContext>
            Lazy load the runtime context. This is done to avoid configuration loading when the command is not run. This is useful for commands like --help and --version

  semantic_release.cli.config module

    class semantic_release.cli.config.BranchConfig(*, match: str = '(main|master)', prerelease_token: str = 'rc', prerelease: bool = False)
        Bases: BaseModel

        match: str

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        prerelease: bool

        prerelease_token: str

        classmethod validate_match(match: str) -> str

    class semantic_release.cli.config.ChangelogConfig(*, changelog_file: str = '', default_templates: ~semantic_release.cli.config.DefaultChangelogTemplatesConfig = DefaultChangelogTemplatesConfig(changelog_file='CHANGELOG.md', output_format=<ChangelogOutputFormat.MARKDOWN: 'md'>, mask_initial_release=True), environment: ~semantic_release.cli.config.ChangelogEnvironmentConfig = ChangelogEnvironmentConfig(block_start_string='{%', block_end_string='%}', variable_start_string='{{', variable_end_string='}}', comment_start_string='{#', comment_end_string='#}', line_statement_prefix=None, line_comment_prefix=None, trim_blocks=False, lstrip_blocks=False, newline_sequence='\n', keep_trailing_newline=False, extensions=(), autoescape=False), exclude_commit_patterns: ~typing.Tuple[str, ...] = (), mode: ~semantic_release.changelog.context.ChangelogMode = ChangelogMode.UPDATE, insertion_flag: str = '', template_dir: str = 'templates')
        Bases: BaseModel

        changelog_file: str
            Deprecated! Moved to 'default_templates.changelog_file'

        classmethod changelog_file_deprecation_warning(val: str) -> str

        default_templates: DefaultChangelogTemplatesConfig <#semantic_release.cli.config.DefaultChangelogTemplatesConfig>

        environment: ChangelogEnvironmentConfig <#semantic_release.cli.config.ChangelogEnvironmentConfig>

        exclude_commit_patterns: Tuple[str, ...]

        insertion_flag: str

        load_default_insertion_flag_on_missing() -> Self

        mode: ChangelogMode <#semantic_release.changelog.context.ChangelogMode>

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        move_changelog_file() -> Self

        template_dir: str

        classmethod validate_match(patterns: Tuple[str, ...]) -> Tuple[str, ...]

    class semantic_release.cli.config.ChangelogEnvironmentConfig(*, block_start_string: str = '{%', block_end_string: str = '%}', variable_start_string: str = '{{', variable_end_string: str = '}}', comment_start_string: str = '{#', comment_end_string: str = '#}', line_statement_prefix: str | None = None, line_comment_prefix: str | None = None, trim_blocks: bool = False, lstrip_blocks: bool = False, newline_sequence: Literal['\n', '\r', '\r\n'] = '\n', keep_trailing_newline: bool = False, extensions: Tuple[str, ...] = (), autoescape: bool | str = False)
        Bases: BaseModel

        autoescape: bool | str

        block_end_string: str

        block_start_string: str

        comment_end_string: str

        comment_start_string: str

        extensions: Tuple[str, ...]

        keep_trailing_newline: bool

        line_comment_prefix: str | None

        line_statement_prefix: str | None

        lstrip_blocks: bool

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        newline_sequence: Literal['\n', '\r', '\r\n']

        trim_blocks: bool

        variable_end_string: str

        variable_start_string: str

    class semantic_release.cli.config.ChangelogOutputFormat(*values)
        Bases: str, Enum

        Supported changelog output formats when using the default templates.

        MARKDOWN = 'md'

        NONE = ''

        RESTRUCTURED_TEXT = 'rst'

    class semantic_release.cli.config.DefaultChangelogTemplatesConfig(*, changelog_file: str = 'CHANGELOG.md', output_format: ChangelogOutputFormat <#semantic_release.cli.config.ChangelogOutputFormat> = ChangelogOutputFormat.NONE, mask_initial_release: bool = True)
        Bases: BaseModel

        changelog_file: str

        interpret_output_format() -> Self

        mask_initial_release: bool

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        output_format: ChangelogOutputFormat <#semantic_release.cli.config.ChangelogOutputFormat>

    class semantic_release.cli.config.EnvConfigVar(*, env: str, default: str | None = None, default_env: str | None = None)
        Bases: BaseModel

        default: str | None

        default_env: str | None

        env: str

        getvalue() -> str | None

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

    class semantic_release.cli.config.GlobalCommandLineOptions(noop: bool = False, verbosity: int = 0, config_file: str = 'pyproject.toml', strict: bool = False)
        Bases: object

        A dataclass to hold all the command line options that should be set in the RuntimeContext

        config_file: str = 'pyproject.toml'

        noop: bool = False

        strict: bool = False

        verbosity: int = 0

    class semantic_release.cli.config.HvcsClient(*values)
        Bases: str, Enum

        BITBUCKET = 'bitbucket'

        GITEA = 'gitea'

        GITHUB = 'github'

        GITLAB = 'gitlab'

    class semantic_release.cli.config.PublishConfig(*, dist_glob_patterns: Tuple[str, ...] = ('dist/*',), upload_to_vcs_release: bool = True)
        Bases: BaseModel

        dist_glob_patterns: Tuple[str, ...]

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        upload_to_vcs_release: bool

    class semantic_release.cli.config.RawConfig(*, assets: ~typing.List[str] = [], branches: ~typing.Dict[str, ~semantic_release.cli.config.BranchConfig] = {'main': BranchConfig(match='(main|master)', prerelease_token='rc', prerelease=False)}, build_command: str | None = None, build_command_env: ~typing.List[str] = [], changelog: ~semantic_release.cli.config.ChangelogConfig = ChangelogConfig(changelog_file='', default_templates=DefaultChangelogTemplatesConfig(changelog_file='CHANGELOG.md', output_format=<ChangelogOutputFormat.MARKDOWN: 'md'>, mask_initial_release=True), environment=ChangelogEnvironmentConfig(block_start_string='{%', block_end_string='%}', variable_start_string='{{', variable_end_string='}}', comment_start_string='{#', comment_end_string='#}', line_statement_prefix=None, line_comment_prefix=None, trim_blocks=False, lstrip_blocks=False, newline_sequence='\n', keep_trailing_newline=False, extensions=(), autoescape=False), exclude_commit_patterns=(), mode=<ChangelogMode.UPDATE: 'update'>, insertion_flag='<!-- version list -->', template_dir='templates'), commit_author: ~semantic_release.cli.config.EnvConfigVar | str = EnvConfigVar(env='GIT_COMMIT_AUTHOR', default='semantic-release <semantic-release>', default_env=None), commit_message: str = '{version}\n\nAutomatically generated by python-semantic-release', commit_parser: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)] = 'conventional', commit_parser_options: ~typing.Dict[str, ~typing.Any] = {}, logging_use_named_masks: bool = False, major_on_zero: bool = True, allow_zero_version: bool = False, repo_dir: ~pathlib.Path = PosixPath('.'), remote: ~semantic_release.cli.config.RemoteConfig = RemoteConfig(name='origin', token=None, url=None, type=<HvcsClient.GITHUB: 'github'>, domain=None, api_domain=None, ignore_token_for_push=False, insecure=False), no_git_verify: bool = False, tag_format: str = 'v{version}', add_partial_tags: bool = False, publish: ~semantic_release.cli.config.PublishConfig = PublishConfig(dist_glob_patterns=('dist/*', ), upload_to_vcs_release=True), version_toml: ~typing.Tuple[str, ...] | None = None, version_variables: ~typing.Tuple[str, ...] | None = None)
        Bases: BaseModel

        add_partial_tags: bool

        allow_zero_version: bool

        classmethod angular_commit_parser_deprecation_warning(val: str) -> str

        assets: List[str]

        branches: Dict[str, BranchConfig <#semantic_release.cli.config.BranchConfig>]

        build_command: str | None

        build_command_env: List[str]

        changelog: ChangelogConfig <#semantic_release.cli.config.ChangelogConfig>

        commit_author: MaybeFromEnv

        commit_message: str

        commit_parser: NonEmptyString

        commit_parser_options: Dict[str, Any]

        classmethod convert_str_to_path(value: Any) -> Path

        logging_use_named_masks: bool

        major_on_zero: bool

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        no_git_verify: bool

        publish: PublishConfig <#semantic_release.cli.config.PublishConfig>

        remote: RemoteConfig <#semantic_release.cli.config.RemoteConfig>

        classmethod remove_whitespace(val: list[str]) -> list[str]

        repo_dir: Annotated[Path, Field(validate_default=True)]

        set_default_opts() -> Self

        classmethod tag_commit_parser_deprecation_warning(val: str) -> str

        tag_format: str

        classmethod verify_git_repo_dir(dir_path: Path) -> Path

        version_toml: Tuple[str, ...] | None

        version_variables: Tuple[str, ...] | None

    class semantic_release.cli.config.RemoteConfig(*, name: str = 'origin', token: str | None = None, url: str | None = None, type: HvcsClient <#semantic_release.cli.config.HvcsClient> = HvcsClient.GITHUB, domain: str | None = None, api_domain: str | None = None, ignore_token_for_push: bool = False, insecure: bool = False)
        Bases: BaseModel

        api_domain: str | None

        check_insecure_flag(url_str: str, field_name: str) -> None

        check_url_scheme() -> Self

        domain: str | None

        ignore_token_for_push: bool

        insecure: bool

        model_config: ClassVar[ConfigDict] = {}
            Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

        name: str

        classmethod resolve_env_vars(val: Any) -> str | None

        set_default_token() -> Self

        token: str | None

        type: HvcsClient <#semantic_release.cli.config.HvcsClient>

        url: str | None

    class semantic_release.cli.config.RuntimeContext(project_metadata: 'dict[str, Any]', repo_dir: 'Path', commit_parser: 'CommitParser[ParseResult, ParserOptions]', version_translator: 'VersionTranslator', major_on_zero: 'bool', allow_zero_version: 'bool', prerelease: 'bool', no_git_verify: 'bool', assets: 'List[str]', commit_author: 'Actor', commit_message: 'str', changelog_excluded_commit_patterns: 'Tuple[Pattern[str], ...]', version_declarations: 'Tuple[IVersionReplacer, ...]', hvcs_client: 'hvcs.HvcsBase', changelog_insertion_flag: 'str', changelog_mask_initial_release: 'bool', changelog_mode: 'ChangelogMode', changelog_file: 'Path', changelog_style: 'str', changelog_output_format: 'ChangelogOutputFormat', ignore_token_for_push: 'bool', template_environment: 'Environment', template_dir: 'Path', build_command: 'Optional[str]', build_command_env: 'dict[str, str]', dist_glob_patterns: 'Tuple[str, ...]', upload_to_vcs_release: 'bool', global_cli_options: 'GlobalCommandLineOptions', masker: 'MaskingFilter')
        Bases: object

        allow_zero_version: bool

        apply_log_masking(masker: MaskingFilter <#semantic_release.cli.masking_filter.MaskingFilter>) -> MaskingFilter <#semantic_release.cli.masking_filter.MaskingFilter>

        assets: List[str]

        build_command: str | None

        build_command_env: dict[str, str]

        changelog_excluded_commit_patterns: Tuple[Pattern[str], ...]

        changelog_file: Path

        changelog_insertion_flag: str

        changelog_mask_initial_release: bool

        changelog_mode: ChangelogMode <#semantic_release.changelog.context.ChangelogMode>

        changelog_output_format: ChangelogOutputFormat <#semantic_release.cli.config.ChangelogOutputFormat>

        changelog_style: str

        commit_author: Actor

        commit_message: str

        commit_parser: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, ParserOptions]

        dist_glob_patterns: Tuple[str, ...]

        classmethod from_raw_config(raw: RawConfig <#semantic_release.cli.config.RawConfig>, global_cli_options: GlobalCommandLineOptions <#semantic_release.cli.config.GlobalCommandLineOptions>) -> RuntimeContext <#semantic_release.cli.config.RuntimeContext>

        global_cli_options: GlobalCommandLineOptions <#semantic_release.cli.config.GlobalCommandLineOptions>

        hvcs_client: HvcsBase

        ignore_token_for_push: bool

        major_on_zero: bool

        masker: MaskingFilter <#semantic_release.cli.masking_filter.MaskingFilter>

        no_git_verify: bool

        prerelease: bool

        project_metadata: dict[str, Any]

        repo_dir: Path

        static resolve_from_env(param: EnvConfigVar <#semantic_release.cli.config.EnvConfigVar> | str | None) -> str | None

        static select_branch_options(choices: Dict[str, BranchConfig <#semantic_release.cli.config.BranchConfig>], active_branch: str) -> BranchConfig <#semantic_release.cli.config.BranchConfig>

        template_dir: Path

        template_environment: Environment

        upload_to_vcs_release: bool

        version_declarations: Tuple[IVersionReplacer <#semantic_release.version.declarations.i_version_replacer.IVersionReplacer>, ...]

        version_translator: VersionTranslator <#semantic_release.version.translator.VersionTranslator>

  semantic_release.cli.const module

  semantic_release.cli.github_actions_output module

    class semantic_release.cli.github_actions_output.PersistenceMode(*values)
        Bases: Enum

        PERMANENT = 'permanent'

        TEMPORARY = 'temporary'

    class semantic_release.cli.github_actions_output.VersionGitHubActionsOutput(gh_client: Github <#semantic_release.hvcs.github.Github> | None = None, mode: PersistenceMode <#semantic_release.cli.github_actions_output.PersistenceMode> = PersistenceMode.PERMANENT, released: bool | None = None, version: Version <#semantic_release.version.version.Version> | None = None, commit_sha: str | None = None, release_notes: str | None = None, prev_version: Version <#semantic_release.version.version.Version> | None = None)
        Bases: object

        OUTPUT_ENV_VAR = 'GITHUB_OUTPUT'

        property commit_sha: str | None

        property gh_client: Github <#semantic_release.hvcs.github.Github>

        property is_prerelease: bool | None

        property prev_version: Version <#semantic_release.version.version.Version> | None

        property release_notes: str | None

        property released: bool | None

        property tag: str | None

        to_output_text() -> str

        property version: Version <#semantic_release.version.version.Version> | None

        write_if_possible(filename: str | None = None) -> None

  semantic_release.cli.masking_filter module

    class semantic_release.cli.masking_filter.MaskingFilter(_use_named_masks: bool = False, **patterns: Iterable[str | re.Pattern[str]])
        Bases: Filter

        REPLACE_STR = '****'

        add_mask_for(data: str, name: str = 'redacted') -> MaskingFilter <#semantic_release.cli.masking_filter.MaskingFilter>

        filter(record: LogRecord) -> bool
            Determine if the specified record is to be logged.

            Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

        mask(msg: str) -> str

  semantic_release.cli.util module

Utilities for command-line functionality

    semantic_release.cli.util.indented(msg: str, prefix: str = ' ') -> str
        Convenience function for text-formatting for the console.

        Ensures the least indented line of the msg string is indented by prefix with consistent alignment of the remainder of msg irrespective of the level of indentation in the Python source code

    semantic_release.cli.util.load_raw_config_file(config_file: Path | str) -> dict[Any, Any]
        Load raw configuration as a dict from the filename specified by config_filename, trying the following parsing methods:

        1.  try to parse with tomli.load (guessing it's a TOML file)

        2.  try to parse with json.load (guessing it's a JSON file)

        3.  raise InvalidConfiguration if none of the above parsing methods work

    This function will also raise FileNotFoundError if it is raised while trying to read the specified configuration file

    semantic_release.cli.util.noop_report(msg: str) -> None
        Rich-prints a msg with a standard prefix to report when an action is not being taken due to a "noop" flag

    semantic_release.cli.util.parse_toml(raw_text: str) -> dict[Any, Any]
        Attempts to parse raw configuration for semantic_release using tomlkit.loads, raising InvalidConfiguration if the TOML is invalid or there's no top level "semantic_release" or "tool.semantic_release" keys

    semantic_release.cli.util.rprint(msg: str) -> None
        Rich-prints to stderr so that redirection of command output isn't cluttered

  semantic_release.commit_parser package

  Subpackages

  semantic_release.commit_parser.conventional package

  Submodules

  semantic_release.commit_parser.conventional.options module

    class semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions(minor_tags: Tuple[str, ...] = ('feat',), patch_tags: Tuple[str, ...] = ('fix', 'perf'), other_allowed_tags: Tuple[str, ...] = ('build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test'), allowed_tags: Tuple[str, ...] = ('feat', 'fix', 'perf', 'build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test'), default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = LevelBump.NO_RELEASE, parse_squash_commits: bool = True, ignore_merge_commits: bool = True)
        Bases: ParserOptions

        Options dataclass for the ConventionalCommitParser.

        allowed_tags: Tuple[str, ...] = ('feat', 'fix', 'perf', 'build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test')
            All commit-type prefixes that are allowed.

            These are used to identify a valid commit message. If a commit message does not start with one of these prefixes, it will not be considered a valid commit message.

        default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = 0
            The minimum bump level to apply to valid commit message.

        ignore_merge_commits: bool = True
            Toggle flag for whether or not to ignore merge commits

        minor_tags: Tuple[str, ...] = ('feat',)
            Commit-type prefixes that should result in a minor release bump.

        other_allowed_tags: Tuple[str, ...] = ('build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test')
            Commit-type prefixes that are allowed but do not result in a version bump.

        parse_squash_commits: bool = True
            Toggle flag for whether or not to parse squash commits

        patch_tags: Tuple[str, ...] = ('fix', 'perf')
            Commit-type prefixes that should result in a patch release bump.

        property tag_to_level: dict[str, LevelBump <#semantic_release.enums.LevelBump>]
            A mapping of commit tags to the level bump they should result in.

  semantic_release.commit_parser.conventional.options_monorepo module

    class semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions(minor_tags: Tuple[str, ...] = ('feat',), patch_tags: Tuple[str, ...] = ('fix', 'perf'), other_allowed_tags: Tuple[str, ...] = ('build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test'), allowed_tags: Tuple[str, ...] = ('feat', 'fix', 'perf', 'build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test'), default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = LevelBump.NO_RELEASE, parse_squash_commits: bool = True, ignore_merge_commits: bool = True, path_filters: Annotated[Tuple[str, ...], Field(validate_default=True)] = ('.',), scope_prefix: str = '')
        Bases: ConventionalCommitParserOptions <#semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions>

        Options dataclass for ConventionalCommitMonorepoParser.

        classmethod convert_strs_to_paths(value: Any) -> tuple[str, ...]

        path_filters: Annotated[Tuple[str, ...], Field(validate_default=True)] = ('.',)
            A set of relative paths to filter commits by. Only commits with file changes that match these file paths or its subdirectories will be considered valid commits.

            Syntax is similar to .gitignore with file path globs and inverse file match globs via ! prefix. Paths should be relative to the current working directory.

        classmethod resolve_path(dir_path_strs: tuple[str, ...]) -> tuple[str, ...]

        scope_prefix: str = ''
            A prefix that will be striped from the scope when parsing commit messages.

            If set, it will cause unscoped commits to be ignored. Use this in tandem with the path_filters option to filter commits by directory and scope. This will be fed into a regular expression so you must escape any special characters that are meaningful in regular expressions (e.g. ., *, ?, +, etc.) if you want to match them literally.

        classmethod validate_scope_prefix(scope_prefix: str) -> str

  semantic_release.commit_parser.conventional.parser module

    class semantic_release.commit_parser.conventional.parser.ConventionalCommitParser(options: ConventionalCommitParserOptions <#semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions> | None = None)
        Bases: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, ConventionalCommitParserOptions <#semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions>]

        A commit parser for projects conforming to the conventional commits specification.

        See <https://www.conventionalcommits.org/en/v1.0.0/>

        commit_body_components_separator(accumulator: dict[str, list[str]], text: str) -> dict[str, list[str]]

        common_commit_msg_filters: ClassVar[dict[str, tuple[Pattern[str], str]]] = {'git-header-author': (re.compile('^[\\t ]*Author: .+$\\n?', re.MULTILINE), ''), 'git-header-commit': (re.compile('^[\\t ]*commit [0-9a-f]+$\\n?', re.MULTILINE), ''), 'git-header-date': (re.compile('^[\\t ]*Date: .+$\\n?', re.MULTILINE), ''), 'git-squash-heading': (re.compile('^[\\t ]*Squashed commit of the following:.*$\\n?', re.MULTILINE), ''), 'typo-extra-spaces': (re.compile('(\\S) +(\\S)'), '\\1 \\2')}

        create_parsed_message_result(match: Match[str]) -> ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult>

        get_default_options() -> ConventionalCommitParserOptions <#semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions>

        static is_merge_commit(commit: Commit) -> bool

        issue_selector = re.compile('^(?:clos(?:e|es|ed|ing)|fix(?:es|ed|ing)?|resolv(?:e|es|ed|ing)|implement(?:s|ed|ing)?):[\\t ]+(?P<issue_predicate>.+)[\\t ]*$', re.IGNORECASE|re.MULTILINE)

        log_parse_error(commit: Commit, error: str) -> ParseError <#semantic_release.commit_parser.token.ParseError>

        mr_selector = re.compile('[\\t ]+\\((?:pull request )?(?P<mr_number>[#!]\\d+)\\)[\\t ]*$')

        notice_selector = re.compile('^NOTICE: (?P<notice>.+)$')

        parse(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError> | list[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>]
            Parse a commit message

            If the commit message is a squashed merge commit, it will be split into multiple commits, each of which will be parsed separately. Single commits will be returned as a list of a single ParseResult.

        parse_commit(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>

        parse_message(message: str) -> ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult> | None

        parser_options
            alias of ConventionalCommitParserOptions <#semantic_release.commit_parser.conventional.options.ConventionalCommitParserOptions>

        unsquash_commit(commit: Commit) -> list[Commit]

        unsquash_commit_message(message: str) -> list[str]

  semantic_release.commit_parser.conventional.parser_monorepo module

    class semantic_release.commit_parser.conventional.parser_monorepo.ConventionalCommitMonorepoParser(options: ConventionalCommitMonorepoParserOptions <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions> | None = None)
        Bases: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, ConventionalCommitMonorepoParserOptions <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions>]

        get_default_options() -> ConventionalCommitMonorepoParserOptions <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions>

        logged_parse_error(commit: Commit, error: str) -> ParseError <#semantic_release.commit_parser.token.ParseError>

        parse(commit: Commit) -> ParseResult | list[ParseResult]

        parse_commit(commit: Commit) -> ParseResult
            Attempt to parse the commit message with a regular expression into a ParseResult.

        parse_message(message: str, strict_scope: bool = False) -> ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult> | None

        parser_options
            alias of ConventionalCommitMonorepoParserOptions <#semantic_release.commit_parser.conventional.options_monorepo.ConventionalCommitMonorepoParserOptions>

        unsquash_commit_message(message: str) -> list[str]

  Submodules

  semantic_release.commit_parser.angular module

Angular commit style parser <https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines>

    class semantic_release.commit_parser.angular.AngularCommitParser(options: AngularParserOptions <#semantic_release.commit_parser.angular.AngularParserOptions> | None = None)
        Bases: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, AngularParserOptions]

        A commit parser for projects conforming to the angular style of conventional commits. See <https://www.conventionalcommits.org/en/v1.0.0-beta.4/>

        commit_body_components_separator(accumulator: dict[str, list[str]], text: str) -> dict[str, list[str]]

        static get_default_options() -> AngularParserOptions <#semantic_release.commit_parser.angular.AngularParserOptions>

        static is_merge_commit(commit: Commit) -> bool

        parse(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError> | list[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>]
            Parse a commit message

            If the commit message is a squashed merge commit, it will be split into multiple commits, each of which will be parsed separately. Single commits will be returned as a list of a single ParseResult.

        parse_commit(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>

        parse_message(message: str) -> ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult> | None

        parser_options
            alias of AngularParserOptions

        unsquash_commit(commit: Commit) -> list[Commit]

        unsquash_commit_message(message: str) -> list[str]

    class semantic_release.commit_parser.angular.AngularParserOptions(minor_tags: Tuple[str, ...] = ('feat',), patch_tags: Tuple[str, ...] = ('fix', 'perf'), other_allowed_tags: Tuple[str, ...] = ('build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test'), allowed_tags: Tuple[str, ...] = ('feat', 'fix', 'perf', 'build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test'), default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = LevelBump.NO_RELEASE, parse_squash_commits: bool = False, ignore_merge_commits: bool = False)
        Bases: ParserOptions

        Options dataclass for AngularCommitParser

        allowed_tags: Tuple[str, ...] = ('feat', 'fix', 'perf', 'build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test')
            All commit-type prefixes that are allowed.

            These are used to identify a valid commit message. If a commit message does not start with one of these prefixes, it will not be considered a valid commit message.

        default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = 0
            The minimum bump level to apply to valid commit message.

        ignore_merge_commits: bool = False
            Toggle flag for whether or not to ignore merge commits

        minor_tags: Tuple[str, ...] = ('feat',)
            Commit-type prefixes that should result in a minor release bump.

        other_allowed_tags: Tuple[str, ...] = ('build', 'chore', 'ci', 'docs', 'style', 'refactor', 'test')
            Commit-type prefixes that are allowed but do not result in a version bump.

        parse_squash_commits: bool = False
            Toggle flag for whether or not to parse squash commits

        patch_tags: Tuple[str, ...] = ('fix', 'perf')
            Commit-type prefixes that should result in a patch release bump.

        property tag_to_level: dict[str, LevelBump <#semantic_release.enums.LevelBump>]
            A mapping of commit tags to the level bump they should result in.

  semantic_release.commit_parser.emoji module

Commit parser which looks for emojis to determine the type of commit

    class semantic_release.commit_parser.emoji.EmojiCommitParser(options: EmojiParserOptions <#semantic_release.commit_parser.emoji.EmojiParserOptions> | None = None)
        Bases: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, EmojiParserOptions]

        Parse a commit using an emoji in the subject line. When multiple emojis are encountered, the one with the highest bump level is used. If there are multiple emojis on the same level, the we use the one listed earliest in the configuration. If the message does not contain any known emojis, then the level to bump will be 0 and the type of change "Other". This parser never raises UnknownCommitMessageStyleError. Emojis are not removed from the description, and will appear alongside the commit subject in the changelog.

        commit_body_components_separator(accumulator: dict[str, list[str]], text: str) -> dict[str, list[str]]

        static get_default_options() -> EmojiParserOptions <#semantic_release.commit_parser.emoji.EmojiParserOptions>

        static is_merge_commit(commit: Commit) -> bool

        parse(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError> | list[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>]
            Parse a commit message

            If the commit message is a squashed merge commit, it will be split into multiple commits, each of which will be parsed separately. Single commits will be returned as a list of a single ParseResult.

        parse_commit(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>

        parse_message(message: str) -> ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult>

        parser_options
            alias of EmojiParserOptions

        unsquash_commit(commit: Commit) -> list[Commit]

        unsquash_commit_message(message: str) -> list[str]

    class semantic_release.commit_parser.emoji.EmojiParserOptions(major_tags: Tuple[str, ...] = (':boom:',), minor_tags: Tuple[str, ...] = (':sparkles:', ':children_crossing:', ':lipstick:', ':iphone:', ':egg:', ':chart_with_upwards_trend:'), patch_tags: Tuple[str, ...] = (':ambulance:', ':lock:', ':bug:', ':zap:', ':goal_net:', ':alien:', ':wheelchair:', ':speech_balloon:', ':mag:', ':apple:', ':penguin:', ':checkered_flag:', ':robot:', ':green_apple:'), other_allowed_tags: Tuple[str, ...] = (':memo:', ':checkmark:'), allowed_tags: Tuple[str, ...] = (':boom:', ':sparkles:', ':children_crossing:', ':lipstick:', ':iphone:', ':egg:', ':chart_with_upwards_trend:', ':ambulance:', ':lock:', ':bug:', ':zap:', ':goal_net:', ':alien:', ':wheelchair:', ':speech_balloon:', ':mag:', ':apple:', ':penguin:', ':checkered_flag:', ':robot:', ':green_apple:', ':memo:', ':checkmark:'), default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = LevelBump.NO_RELEASE, parse_linked_issues: bool = False, parse_squash_commits: bool = True, ignore_merge_commits: bool = True)
        Bases: ParserOptions

        Options dataclass for EmojiCommitParser

        allowed_tags: Tuple[str, ...] = (':boom:', ':sparkles:', ':children_crossing:', ':lipstick:', ':iphone:', ':egg:', ':chart_with_upwards_trend:', ':ambulance:', ':lock:', ':bug:', ':zap:', ':goal_net:', ':alien:', ':wheelchair:', ':speech_balloon:', ':mag:', ':apple:', ':penguin:', ':checkered_flag:', ':robot:', ':green_apple:', ':memo:', ':checkmark:')
            All commit-type prefixes that are allowed.

        default_bump_level: LevelBump <#semantic_release.enums.LevelBump> = 0
            The minimum bump level to apply to valid commit message.

        ignore_merge_commits: bool = True
            Toggle flag for whether or not to ignore merge commits

        major_tags: Tuple[str, ...] = (':boom:',)
            Commit-type prefixes that should result in a major release bump.

        minor_tags: Tuple[str, ...] = (':sparkles:', ':children_crossing:', ':lipstick:', ':iphone:', ':egg:', ':chart_with_upwards_trend:')
            Commit-type prefixes that should result in a minor release bump.

        other_allowed_tags: Tuple[str, ...] = (':memo:', ':checkmark:')
            Commit-type prefixes that are allowed but do not result in a version bump.

        parse_linked_issues: bool = False
            Whether to parse linked issues from the commit message.

            Issue identification is not defined in the Gitmoji specification, so this parser will not attempt to parse issues by default. If enabled, the parser will use the same identification as GitHub, GitLab, and BitBucket use for linking issues, which is to look for a git commit message footer starting with "Closes:", "Fixes:", or "Resolves:" then a space, and then the issue identifier. The line prefix can be singular or plural and it is not case-sensitive but must have a colon and a whitespace separator.

        parse_squash_commits: bool = True
            Toggle flag for whether or not to parse squash commits

        patch_tags: Tuple[str, ...] = (':ambulance:', ':lock:', ':bug:', ':zap:', ':goal_net:', ':alien:', ':wheelchair:', ':speech_balloon:', ':mag:', ':apple:', ':penguin:', ':checkered_flag:', ':robot:', ':green_apple:')
            Commit-type prefixes that should result in a patch release bump.

        property tag_to_level: dict[str, LevelBump <#semantic_release.enums.LevelBump>]
            A mapping of commit tags to the level bump they should result in.

  semantic_release.commit_parser.scipy module

Parses commit messages using scipy tags <scipy-style> 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

    class semantic_release.commit_parser.scipy.ScipyCommitParser(options: ScipyParserOptions <#semantic_release.commit_parser.scipy.ScipyParserOptions> | None = None)
        Bases: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, ScipyParserOptions]

        Parser for scipy-style commit messages

        commit_body_components_separator(accumulator: dict[str, list[str]], text: str) -> dict[str, list[str]]

        static get_default_options() -> ScipyParserOptions <#semantic_release.commit_parser.scipy.ScipyParserOptions>

        static is_merge_commit(commit: Commit) -> bool

        parse(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError> | list[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>]
            Parse a commit message

            If the commit message is a squashed merge commit, it will be split into multiple commits, each of which will be parsed separately. Single commits will be returned as a list of a single ParseResult.

        parse_commit(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>

        parse_message(message: str) -> ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult> | None

        parser_options
            alias of ScipyParserOptions

        unsquash_commit(commit: Commit) -> list[Commit]

        unsquash_commit_message(message: str) -> list[str]

    class semantic_release.commit_parser.scipy.ScipyParserOptions(major_tags: Tuple[str, ...] = ('API', 'DEP'), minor_tags: Tuple[str, ...] = ('ENH', 'FEAT'), patch_tags: Tuple[str, ...] = ('BLD', 'BUG', 'MAINT'), other_allowed_tags: Tuple[str, ...] = ('DEV', 'BENCH', 'DOC', 'STY', 'TST', 'REL', 'TEST'), allowed_tags: Tuple[str, ...] = ('API', 'DEP', 'ENH', 'FEAT', 'BLD', 'BUG', 'MAINT', 'DEV', 'BENCH', 'DOC', 'STY', 'TST', 'REL', 'TEST'), default_level_bump: LevelBump <#semantic_release.enums.LevelBump> = LevelBump.NO_RELEASE, parse_squash_commits: bool = True, ignore_merge_commits: bool = True)
        Bases: ParserOptions

        Options dataclass for ScipyCommitParser

        Scipy-style commit messages follow the same format as Angular-style commit just with different tag names.

        allowed_tags: Tuple[str, ...] = ('API', 'DEP', 'ENH', 'FEAT', 'BLD', 'BUG', 'MAINT', 'DEV', 'BENCH', 'DOC', 'STY', 'TST', 'REL', 'TEST')
            All commit-type prefixes that are allowed.

            These are used to identify a valid commit message. If a commit message does not start with one of these prefixes, it will not be considered a valid commit message.

        default_level_bump: LevelBump <#semantic_release.enums.LevelBump> = 0
            The minimum bump level to apply to valid commit message.

        ignore_merge_commits: bool = True
            Toggle flag for whether or not to ignore merge commits

        major_tags: Tuple[str, ...] = ('API', 'DEP')
            Commit-type prefixes that should result in a major release bump.

        minor_tags: Tuple[str, ...] = ('ENH', 'FEAT')
            Commit-type prefixes that should result in a minor release bump.

        other_allowed_tags: Tuple[str, ...] = ('DEV', 'BENCH', 'DOC', 'STY', 'TST', 'REL', 'TEST')
            Commit-type prefixes that are allowed but do not result in a version bump.

        parse_squash_commits: bool = True
            Toggle flag for whether or not to parse squash commits

        patch_tags: Tuple[str, ...] = ('BLD', 'BUG', 'MAINT')
            Commit-type prefixes that should result in a patch release bump.

        property tag_to_level: dict[str, LevelBump <#semantic_release.enums.LevelBump>]
            A mapping of commit tags to the level bump they should result in.

  semantic_release.commit_parser.tag module

Legacy commit parser from Python Semantic Release 1.0

    class semantic_release.commit_parser.tag.TagCommitParser(options: _OPTS | None = None)
        Bases: CommitParser[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>, TagParserOptions]

        Parse a commit message according to the 1.0 version of python-semantic-release. It expects a tag of some sort in the commit message and will use the rest of the first line as changelog content.

        static get_default_options() -> TagParserOptions <#semantic_release.commit_parser.tag.TagParserOptions>

        parse(commit: Commit) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError> | list[ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit> | ParseError <#semantic_release.commit_parser.token.ParseError>]

        parser_options
            alias of TagParserOptions

    class semantic_release.commit_parser.tag.TagParserOptions(minor_tag: str = ':sparkles:', patch_tag: str = ':nut_and_bolt:')
        Bases: ParserOptions

        minor_tag: str = ':sparkles:'

        patch_tag: str = ':nut_and_bolt:'

  semantic_release.commit_parser.token module

    class semantic_release.commit_parser.token.ParseError(commit: Commit, error: str)
        Bases: NamedTuple

        A read-only named tuple object representing an error that occurred while parsing a commit message.

        commit: Commit
            The original commit object (a class defined by GitPython) that was parsed

        error: str
            A string with a description for why the commit parsing failed.

        property hexsha: str
            A hex representation of the hash value of the commit.

            This is a pass through property for convience to access the hexsha attribute of the commit.

        is_merge_commit() -> bool

        property message: str
            A string representation of the commit message.

            This is a pass through property for convience to access the message attribute of the commit object.

            If the message is of type bytes then it will be decoded to a UTF-8 string.

        raise_error() -> NoReturn
            A convience method to raise a CommitParseError with the error message.

        property short_hash: str
            A short representation of the hash value (in hex) of the commit.

    class semantic_release.commit_parser.token.ParsedCommit(bump: LevelBump <#semantic_release.enums.LevelBump>, type: str, scope: str, descriptions: list[str], breaking_descriptions: list[str], commit: Commit, release_notices: tuple[str, ...] = (), linked_issues: tuple[str, ...] = (), linked_merge_request: str = '', include_in_changelog: bool = True)
        Bases: NamedTuple

        A read-only named tuple object representing the result of parsing a commit message.

        breaking_descriptions: list[str]
            A list of paragraphs which are deemed to identify and describe breaking changes by the parser.

            An example would be a paragraph which begins with the text BREAKING CHANGE: in the commit message but the parser gennerally strips the prefix and includes the rest of the paragraph in this list.

        bump: LevelBump <#semantic_release.enums.LevelBump>
            A LevelBump enum value indicating what type of change this commit introduces.

        commit: Commit
            The original commit object (a class defined by GitPython) that was parsed

        descriptions: list[str]
            A list of paragraphs from the commit message.

            Paragraphs are generally delimited by a double-newline since git commit messages are sometimes manually wordwrapped with a single newline, but this is up to the parser to implement.

        static from_parsed_message_result(commit: Commit, parsed_message_result: ParsedMessageResult <#semantic_release.commit_parser.token.ParsedMessageResult>) -> ParsedCommit <#semantic_release.commit_parser.token.ParsedCommit>
            A convience method to create a ParsedCommit object from a ParsedMessageResult object and a Commit object.

        property hexsha: str
            A hex representation of the hash value of the commit.

            This is a pass through property for convience to access the hexsha attribute of the commit.

        include_in_changelog: bool
            A boolean value indicating whether this commit should be included in the changelog.

            This enables parsers to flag commits which are not user-facing or are otherwise not relevant to the changelog to be filtered out by PSR's internal algorithms.

        is_merge_commit() -> bool

        linked_issues: tuple[str, ...]
            A tuple of issue numbers as strings, if the commit is contains issue references.

            If there are no issue references, this should be an empty tuple. Although, we generally refer to them as "issue numbers", it generally should be a string to adhere to the prefixes used by the VCS (ex. # for GitHub, GitLab, etc.) or issue tracker (ex. JIRA uses AAA-###).

        linked_merge_request: str
            A pull request or merge request definition, if the commit is labeled with a pull/merge request number.

            This is a string value which includes any special character prefix used by the VCS (e.g. # for GitHub, ! for GitLab).

        property linked_pull_request: str
            An alias to the linked_merge_request attribute.

        property message: str
            A string representation of the commit message.

            This is a pass through property for convience to access the message attribute of the commit object.

            If the message is of type bytes then it will be decoded to a UTF-8 string.

        release_notices: tuple[str, ...]
            A tuple of release notices, which are additional information about the changes that affect the user.

            An example would be a paragraph which begins with the text NOTICE: in the commit message but the parser generally strips the prefix and includes the rest of the paragraph in this list.

        scope: str
            The scope, as a string, parsed from the commit.

            Generally an optional field based on the commit message style which means it very likely can be an empty string. Commit styles which do not have a meaningful concept of "scope" usually fill this field with an empty string.

        property short_hash: str
            A short representation of the hash value (in hex) of the commit.

        type: str
            The type of the commit as a string, per the commit message style.

            This is up to the parser to implement; for example, the EmojiCommitParser parser fills this field with the emoji representing the most significant change for the commit.

    class semantic_release.commit_parser.token.ParsedMessageResult(bump: LevelBump <#semantic_release.enums.LevelBump>, type: str, category: str, scope: str, descriptions: tuple[str, ...], breaking_descriptions: tuple[str, ...] = (), release_notices: tuple[str, ...] = (), linked_issues: tuple[str, ...] = (), linked_merge_request: str = '', include_in_changelog: bool = True)
        Bases: NamedTuple

        A read-only named tuple object representing the result from parsing a commit message.

        Essentially this is a data structure which holds the parsed information from a commit message without the actual commit object itself. Very helpful for unit testing.

        Most of the fields will replicate the fields of a ParsedCommit

        breaking_descriptions: tuple[str, ...]
            Alias for field number 5

        bump: LevelBump <#semantic_release.enums.LevelBump>
            Alias for field number 0

        category: str
            Alias for field number 2

        descriptions: tuple[str, ...]
            Alias for field number 4

        include_in_changelog: bool
            Alias for field number 9

        linked_issues: tuple[str, ...]
            Alias for field number 7

        linked_merge_request: str
            Alias for field number 8

        release_notices: tuple[str, ...]
            Alias for field number 6

        scope: str
            Alias for field number 3

        type: str
            Alias for field number 1

  semantic_release.commit_parser.util module

    semantic_release.commit_parser.util.deep_copy_commit(commit: Commit) -> dict[str, Any]

    semantic_release.commit_parser.util.force_str(msg: str | bytes | bytearray | memoryview) -> str

    semantic_release.commit_parser.util.parse_paragraphs(text: str) -> list[str]
        This will take a text block and return a list containing each paragraph with single line breaks collapsed into spaces.

        To handle Windows line endings, carriage returns 'r' are removed before separating into paragraphs.

        It will attempt to detect Git footers and they will not be condensed.

        Parameters
            text -- The text string to be divided.

        Returns
            A list of condensed paragraphs, as strings.

  semantic_release.hvcs package

  Submodules

  semantic_release.hvcs.bitbucket module

Helper code for interacting with a Bitbucket remote VCS

    class semantic_release.hvcs.bitbucket.Bitbucket(remote_url: str, *, hvcs_domain: str | None = None, hvcs_api_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)
        Bases: RemoteHvcsBase <#semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase>

        Bitbucket HVCS interface for interacting with BitBucket repositories

        This class supports the following products:

                •   BitBucket Cloud

                •   BitBucket Data Center Server (on-premises installations)

    This interface does its best to detect which product is configured based on the provided domain. If it is the official bitbucket.org, the default domain, then it is considered as BitBucket Cloud which uses the subdomain api.bitbucket.org/2.0 for api communication.

    If the provided domain is anything else, than it is assumed to be communicating with an on-premise or 3rd-party maintained BitBucket instance which matches with the BitBucket Data Center Server product. The on-prem server product uses a path prefix for handling api requests which is configured to be server.domain/rest/api/1.0 based on the documentation in April 2024.

        DEFAULT_API_PATH_CLOUD = '/2.0'

        DEFAULT_API_PATH_ONPREM = '/rest/api/1.0'

        DEFAULT_API_SUBDOMAIN_PREFIX = 'api'

        DEFAULT_API_URL_CLOUD = 'https://api.bitbucket.org/2.0'

        DEFAULT_DOMAIN = 'bitbucket.org'

        DEFAULT_ENV_TOKEN_NAME = 'BITBUCKET_TOKEN'

        OFFICIAL_NAME = 'Bitbucket'

        commit_hash_url(commit_hash: str) -> str

        compare_url(from_rev: str, to_rev: str) -> str
            Get the Bitbucket comparison link between two version tags. :param from_rev: The older version to compare. :param to_rev: The newer version to compare. :return: Link to view a comparison between the two versions.

        create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) -> int | str
            Create or update a release for the given tag in a remote VCS, attaching the given changelog, if supported

        create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None, noop: bool = False) -> int | str
            Create a release in a remote VCS, if supported

            Which includes uploading any assets as part of the release

        static format_w_official_vcs_name(format_str: str) -> str

        get_changelog_context_filters() -> tuple[Callable[..., Any], ...]
            Return a list of functions that can be used as filters in a Jinja2 template

            ex. filters to convert text to URLs for issues and commits

        pull_request_url(pr_number: str | int) -> str

        remote_url(use_token: bool = True) -> str
            Get the remote url including the token for authentication if requested

        upload_dists(tag: str, dist_glob: str) -> int
            Upload built distributions to a release on a remote VCS that supports such uploads

  semantic_release.hvcs.gitea module

Helper code for interacting with a Gitea remote VCS

    class semantic_release.hvcs.gitea.Gitea(remote_url: str, *, hvcs_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **_kwargs: Any)
        Bases: RemoteHvcsBase <#semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase>

        Gitea helper class

        DEFAULT_API_PATH = '/api/v1'

        DEFAULT_DOMAIN = 'gitea.com'

        DEFAULT_ENV_TOKEN_NAME = 'GITEA_TOKEN'

        OFFICIAL_NAME = 'Gitea'

        asset_upload_url(release_id: str) -> str
            Get the correct upload url for a release <https://gitea.com/api/swagger#/repository/repoCreateReleaseAttachment> :param release_id: ID of the release to upload to

        commit_hash_url(commit_hash: str) -> str

        create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) -> int
            Post release changelog :param version: The version number :param changelog: The release notes for this version

            Returns
                The status of the request

        create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None, noop: bool = False) -> int
            Create a new release

            Ref: <https://gitea.com/api/swagger#/repository/repoCreateRelease>

            Parameters

                •   tag -- Tag to create release for

                •   release_notes -- The release notes for this version

                •   prerelease -- Whether or not this release should be specified as a prerelease

            Returns
                Whether the request succeeded

        create_release_url(tag: str = '') -> str

        edit_release_notes(release_id: int, release_notes: str) -> int
            Edit a release with updated change notes <https://gitea.com/api/swagger#/repository/repoEditRelease> :param id: ID of release to update :param release_notes: The release notes for this version

            Returns
                The ID of the release that was edited

        static format_w_official_vcs_name(format_str: str) -> str

        get_changelog_context_filters() -> tuple[Callable[..., Any], ...]
            Return a list of functions that can be used as filters in a Jinja2 template

            ex. filters to convert text to URLs for issues and commits

        get_release_id_by_tag(tag: str) -> int | None
            Get a release by its tag name <https://gitea.com/api/swagger#/repository/repoGetReleaseByTag> :param tag: Tag to get release for

            Returns
                ID of found release

        issue_url(issue_num: str | int) -> str

        pull_request_url(pr_number: str | int) -> str

        remote_url(use_token: bool = True) -> str
            Get the remote url including the token for authentication if requested

        upload_dists(tag: str, dist_glob: str) -> int
            Upload distributions to a release :param tag: Tag to upload for :param path: Path to the dist directory

            Returns
                The number of distributions successfully uploaded

        upload_release_asset(release_id: int, file: str, label: str | None = None) -> bool
            Upload an asset to an existing release <https://gitea.com/api/swagger#/repository/repoCreateReleaseAttachment> :param release_id: ID of the release to upload to :param file: Path of the file to upload :param label: this parameter has no effect

            Returns
                The status of the request

  semantic_release.hvcs.github module

Helper code for interacting with a GitHub remote VCS

    class semantic_release.hvcs.github.Github(remote_url: str, *, hvcs_domain: str | None = None, hvcs_api_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **_kwargs: Any)
        Bases: RemoteHvcsBase <#semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase>

        GitHub HVCS interface for interacting with GitHub repositories

        This class supports the following products:

                •   GitHub Free, Pro, & Team

                •   GitHub Enterprise Cloud

                •   GitHub Enterprise Server (on-premises installations)

    This interface does its best to detect which product is configured based on the provided domain. If it is the official github.com, the default domain, then it is considered as GitHub Enterprise Cloud which uses the subdomain api.github.com for api communication.

    If the provided domain is anything else, than it is assumed to be communicating with an on-premise or 3rd-party maintained GitHub instance which matches with the GitHub Enterprise Server product. The on-prem server product uses a path prefix for handling api requests which is configured to be server.domain/api/v3 based on the documentation in April 2024.

        DEFAULT_API_DOMAIN = 'api.github.com'

        DEFAULT_API_PATH_CLOUD = '/'

        DEFAULT_API_PATH_ONPREM = '/api/v3'

        DEFAULT_API_SUBDOMAIN_PREFIX = 'api'

        DEFAULT_API_URL_CLOUD = 'https://api.github.com'

        DEFAULT_DOMAIN = 'github.com'

        DEFAULT_ENV_TOKEN_NAME = 'GH_TOKEN'

        OFFICIAL_NAME = 'GitHub'

        asset_upload_url(release_id: str) -> str | None
            Get the correct upload url for a release <https://docs.github.com/en/enterprise-server@3.5/rest/releases/releases#get-a-release> :param release_id: ID of the release to upload to :return: URL to upload for a release if found, else None

        commit_hash_url(commit_hash: str) -> str

        compare_url(from_rev: str, to_rev: str) -> str
            Get the GitHub comparison link between two version tags. :param from_rev: The older version to compare. :param to_rev: The newer version to compare. :return: Link to view a comparison between the two versions.

        create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) -> int
            Post release changelog :param tag: The version number :param release_notes: The release notes for this version :param prerelease: Whether or not this release should be created as a prerelease :return: The status of the request

        create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None, noop: bool = False) -> int
            Create a new release

            REF: <https://docs.github.com/rest/reference/repos#create-a-release>

            Parameters

                •   tag -- Tag to create release for

                •   release_notes -- The release notes for this version

                •   prerelease -- Whether or not this release should be created as a prerelease

                •   assets -- a list of artifacts to upload to the release

            Returns
                the ID of the release

        create_release_url(tag: str = '') -> str

        edit_release_notes(release_id: int, release_notes: str) -> int
            Edit a release with updated change notes <https://docs.github.com/rest/reference/repos#update-a-release> :param release_id: ID of release to update :param release_notes: The release notes for this version :return: The ID of the release that was edited

        static format_w_official_vcs_name(format_str: str) -> str

        get_changelog_context_filters() -> tuple[Callable[..., Any], ...]
            Return a list of functions that can be used as filters in a Jinja2 template

            ex. filters to convert text to URLs for issues and commits

        get_release_id_by_tag(tag: str) -> int | None
            Get a release by its tag name <https://docs.github.com/rest/reference/repos#get-a-release-by-tag-name> :param tag: Tag to get release for :return: ID of release, if found, else None

        issue_url(issue_num: str | int) -> str

        pull_request_url(pr_number: str | int) -> str

        remote_url(use_token: bool = True) -> str
            Get the remote url including the token for authentication if requested

        upload_dists(tag: str, dist_glob: str) -> int
            Upload distributions to a release :param tag: Version to upload for :param dist_glob: Path to the dist directory :return: The number of distributions successfully uploaded

        upload_release_asset(release_id: int, file: str, label: str | None = None) -> bool
            Upload an asset to an existing release <https://docs.github.com/rest/reference/repos#upload-a-release-asset> :param release_id: ID of the release to upload to :param file: Path of the file to upload :param label: Optional custom label for this file :return: The status of the request

  semantic_release.hvcs.gitlab module

Helper code for interacting with a Gitlab remote VCS

    class semantic_release.hvcs.gitlab.Gitlab(remote_url: str, *, hvcs_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **_kwargs: Any)
        Bases: RemoteHvcsBase <#semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase>

        Gitlab HVCS interface for interacting with Gitlab repositories

        DEFAULT_DOMAIN = 'gitlab.com'

        DEFAULT_ENV_TOKEN_NAME = 'GITLAB_TOKEN'

        OFFICIAL_NAME = 'GitLab'

        commit_hash_url(commit_hash: str) -> str

        compare_url(from_rev: str, to_rev: str) -> str

        create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) -> str
            Create or update a release for the given tag in a remote VCS.

            Parameters

                •   tag -- The tag to create or update the release for

                •   release_notes -- The changelog description for this version only

                •   prerelease -- This parameter has no effect in GitLab

            Returns
                The release id

            Raises

                •   ValueError -- If the release could not be created or updated

                •   gitlab.exceptions.GitlabAuthenticationError -- If the user is not authenticated

                •   GitlabUpdateError -- If the server cannot perform the request

        create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None, noop: bool = False) -> str
            Create a release in a remote VCS, adding any release notes and assets to it

            Parameters

                •   tag -- The tag to create the release for

                •   release_notes -- The changelog description for this version only

                •   prerelease -- This parameter has no effect in GitLab

                •   assets -- A list of paths to files to upload as assets (TODO: not implemented)

                •   noop -- If True, do not perform any actions, only logger intents

            Returns
                The tag of the release

            Raises
                GitlabAuthenticationError: If authentication is not correct

            Raises
                GitlabCreateError: If the server cannot perform the request

        create_release_url(tag: str = '') -> str

        edit_release_notes(release: ProjectRelease, release_notes: str) -> str
            Update the release notes for a given release.

            Parameters

                •   release -- The release object to update

                •   release_notes -- The new release notes

            Returns
                The release id

            Raises
                GitlabAuthenticationError: If authentication is not correct

            Raises
                GitlabUpdateError: If the server cannot perform the request

        static format_w_official_vcs_name(format_str: str) -> str

        get_changelog_context_filters() -> tuple[Callable[..., Any], ...]
            Return a list of functions that can be used as filters in a Jinja2 template

            ex. filters to convert text to URLs for issues and commits

        get_release_by_tag(tag: str) -> ProjectRelease | None
            Get a release by its tag name.

            Parameters
                tag -- The tag name to get the release for

            Returns
                gitlab.v4.objects.ProjectRelease or None if not found

            Raises
                gitlab.exceptions.GitlabAuthenticationError: If the user is not authenticated

        issue_url(issue_num: str | int) -> str

        merge_request_url(mr_number: str | int) -> str

        property project: GitLabProject

        pull_request_url(pr_number: str | int) -> str

        remote_url(use_token: bool = True) -> str
            Get the remote url including the token for authentication if requested

        upload_dists(tag: str, dist_glob: str) -> int
            Upload built distributions to a release on a remote VCS that supports such uploads

  semantic_release.hvcs.remote_hvcs_base module

Common functionality and interface for interacting with Git remote VCS

    class semantic_release.hvcs.remote_hvcs_base.RemoteHvcsBase(remote_url: str, *_args: Any, **_kwargs: Any)
        Bases: HvcsBase

        Interface for subclasses interacting with a remote VCS

        This abstract class is defined to provide common helper functions and a set of basic methods that all remote VCS environments usually support.

        If the remote vcs implementation (via subclass) does not support a functionality then it can just call super()'s method which defaults as a non-supported log message and empty results. This is more straightforward than checking for NotImplemented around every function call in the core library code.

        DEFAULT_ENV_TOKEN_NAME = 'HVCS_TOKEN'

        property api_url: Url

        create_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) -> str

        abstractmethod create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) -> int | str
            Create or update a release for the given tag in a remote VCS, attaching the given changelog, if supported

        abstractmethod create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None, noop: bool = False) -> int | str
            Create a release in a remote VCS, if supported

            Which includes uploading any assets as part of the release

        create_repo_url(repo_path: str, query: str | None = None, fragment: str | None = None) -> str

        create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) -> str

        property hvcs_domain: Url

        abstractmethod upload_dists(tag: str, dist_glob: str) -> int
            Upload built distributions to a release on a remote VCS that supports such uploads

  semantic_release.hvcs.token_auth module

    class semantic_release.hvcs.token_auth.TokenAuth(token: str)
        Bases: AuthBase

        requests Authentication for token based authorization. This allows us to attach the Authorization header with a token to a session.

  semantic_release.hvcs.util module

    semantic_release.hvcs.util.build_requests_session(raise_for_status: bool = True, retry: bool | int | Retry = True, auth: TokenAuth <#semantic_release.hvcs.token_auth.TokenAuth> | None = None) -> Session
        Create a requests session.

        Parameters

            •   raise_for_status -- If True, a hook to invoke raise_for_status be installed

            •   retry -- If true, it will use default Retry configuration. if an integer, it will use default Retry configuration with given integer as total retry count. if Retry instance, it will use this instance.

            •   auth -- Optional TokenAuth instance to be used to provide the Authorization header to the session

        Returns
            configured requests Session

    semantic_release.hvcs.util.suppress_http_error_for_codes(*codes: int) -> Callable[[Callable[[...], _R]], Callable[[...], _R | None]]
        For the codes given, return a decorator that will suppress HTTPErrors that are raised from responses that came with one of those status codes. The function will return False instead of raising the HTTPError

    semantic_release.hvcs.util.suppress_not_found(func: Callable[[...], _R]) -> Callable[[...], _R | None]

  semantic_release.version package

  Subpackages

  semantic_release.version.declarations package

  Submodules

  semantic_release.version.declarations.enum module

    class semantic_release.version.declarations.enum.VersionStampType(*values)
        Bases: str, Enum

        Enum for the type of version declaration

        NUMBER_FORMAT = 'nf'

        TAG_FORMAT = 'tf'

  semantic_release.version.declarations.i_version_replacer module

    class semantic_release.version.declarations.i_version_replacer.IVersionReplacer
        Bases: object

        Interface for subclasses that replace a version string in a source file.

        Methods generally have a base implementation are implemented here but likely just provide a not-supported message but return gracefully

        This class cannot be instantiated directly but must be inherited from and implement the designated abstract methods.

        abstractmethod parse() -> set[Version <#semantic_release.version.version.Version>]
            Return a set of the versions which can be parsed from the file. Because a source can match in multiple places, this method returns a set of matches. Generally, there should only be one element in this set (i.e. even if the version is specified in multiple places, it should be the same version in each place), but enforcing that condition is not mandatory or expected.

        abstractmethod replace(new_version: Version <#semantic_release.version.version.Version>) -> str
            Replace the version in the source content with new_version, and return the updated content.

            Parameters
                new_version -- The new version number as a Version instance

        abstractmethod update_file_w_version(new_version: Version <#semantic_release.version.version.Version>, noop: bool = False) -> Path | None
            This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file.

            Parameters
                new_version -- The new version number as a Version instance

  semantic_release.version.declarations.pattern module

    class semantic_release.version.declarations.pattern.PatternVersionDeclaration(path: Path | str, search_text: str, stamp_format: VersionStampType <#semantic_release.version.declarations.enum.VersionStampType>)
        Bases: IVersionReplacer <#semantic_release.version.declarations.i_version_replacer.IVersionReplacer>

        VersionDeclarationABC implementation representing a version number in a particular file. The version number is identified by a regular expression, which should be provided in search_text.

        property content: str
            A cached property that stores the content of the configured source file.

        classmethod from_string_definition(replacement_def: str, tag_format: str) -> PatternVersionDeclaration <#semantic_release.version.declarations.pattern.PatternVersionDeclaration>
            create an instance of self from a string representing one item of the "version_variables" list in the configuration

        parse() -> set[Version <#semantic_release.version.version.Version>]
            Return the versions matching this pattern. Because a pattern can match in multiple places, this method returns a set of matches. Generally, there should only be one element in this set (i.e. even if the version is specified in multiple places, it should be the same version in each place), but it falls on the caller to check for this condition.

            Deprecated since version 9.20.0: Function is unused and will be removed in a future release

        replace(new_version: Version <#semantic_release.version.version.Version>) -> str
            Replace the version in the source content with new_version, and return the updated content.

            Parameters
                new_version -- The new version number as a Version instance

        update_file_w_version(new_version: Version <#semantic_release.version.version.Version>, noop: bool = False) -> Path | None
            This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file.

            Parameters
                new_version -- The new version number as a Version instance

    class semantic_release.version.declarations.pattern.VersionSwapper(new_version_str: str, group_match_name: str)
        Bases: object

        Callable to replace a version number in a string with a new version number.

  semantic_release.version.declarations.toml module

    class semantic_release.version.declarations.toml.TomlVersionDeclaration(path: Path | str, search_text: str, stamp_format: VersionStampType <#semantic_release.version.declarations.enum.VersionStampType>)
        Bases: IVersionReplacer <#semantic_release.version.declarations.i_version_replacer.IVersionReplacer>

        property content: str
            A cached property that stores the content of the configured source file.

        classmethod from_string_definition(replacement_def: str) -> TomlVersionDeclaration <#semantic_release.version.declarations.toml.TomlVersionDeclaration>
            create an instance of self from a string representing one item of the "version_toml" list in the configuration

        parse() -> set[Version <#semantic_release.version.version.Version>]
            Look for the version in the source content

            Deprecated since version 9.20.0: Function is unused and will be removed in a future release

        replace(new_version: Version <#semantic_release.version.version.Version>) -> str
            Replace the version in the source content with new_version, and return the updated content.

        update_file_w_version(new_version: Version <#semantic_release.version.version.Version>, noop: bool = False) -> Path | None
            This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file.

            Parameters
                new_version -- The new version number as a Version instance

  Submodules

  semantic_release.version.algorithm module

    semantic_release.version.algorithm.next_version(repo: Repo, translator: VersionTranslator <#semantic_release.version.translator.VersionTranslator>, commit_parser: CommitParser[ParseResult, ParserOptions], allow_zero_version: bool, major_on_zero: bool, prerelease: bool = False) -> Version <#semantic_release.version.version.Version>
        Evaluate the history within repo, and based on the tags and commits in the repo history, identify the next semantic version that should be applied to a release

    semantic_release.version.algorithm.tags_and_versions(tags: Iterable[Tag], translator: VersionTranslator <#semantic_release.version.translator.VersionTranslator>) -> list[tuple[Tag, Version <#semantic_release.version.version.Version>]]
        Return a list of 2-tuples, where each element is a tuple (tag, version) from the tags in the Git repo and their corresponding Version according to Version.from_tag. The returned list is sorted according to semver ordering rules.

        Tags which are not matched by translator are ignored.

  semantic_release.version.declaration module

    class semantic_release.version.declaration.VersionDeclarationABC(*args, **kwargs)
        Bases: ABC

        ABC for classes representing a location in which a version is declared somewhere within the source tree of the repository

        Deprecated since version 9.20.0: Refactored to composition paradigm using the new IVersionReplacer interface. This class will be removed in a future release

        property content: str
            The content of the source file in which the version is stored. This property is cached in the instance variable _content

        abstractmethod parse() -> set[Version <#semantic_release.version.version.Version>]
            Return a set of the versions which can be parsed from the file. Because a source can match in multiple places, this method returns a set of matches. Generally, there should only be one element in this set (i.e. even if the version is specified in multiple places, it should be the same version in each place), but enforcing that condition is not mandatory or expected.

        abstractmethod replace(new_version: Version <#semantic_release.version.version.Version>) -> str
            Update the versions. This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file. :param new_version: The new version number as a Version instance

        write(content: str) -> None
            Write new content back to the source path. Use alongside .replace(): >>> class MyVD(VersionDeclarationABC): ... def parse(self): ... ... def replace(self, new_version: Version): ... ... def write(self, content: str): ...

                >>> new_version = Version.parse("1.2.3")
                >>> vd = MyVD("path", r"__version__ = (?P<version>\d+\d+\d+)")
                >>> vd.write(vd.replace(new_version))

  semantic_release.version.translator module

    class semantic_release.version.translator.VersionTranslator(tag_format: str = 'v{version}', prerelease_token: str = 'rc', add_partial_tags: bool = False)
        Bases: object

        Class to handle translation from Git tags into their corresponding Version instances.

        from_string(version_str: str) -> Version <#semantic_release.version.version.Version>
            Return a Version instance from a string. Delegates directly to Version.parse, using the translator's own stored values for tag_format and prerelease

        from_tag(tag: str) -> Version <#semantic_release.version.version.Version> | None
            Return a Version instance from a Git tag, if tag_format matches the format which would have generated the tag from a version. Otherwise return None. For example, a tag of 'v1.2.3' should be matched if tag_format = 'v{version}, but not if tag_format = staging--v{version}.

        str_to_tag(version_str: str) -> str
            Formats a version string into a tag name

  semantic_release.version.version module

    class semantic_release.version.version.Version(major: int, minor: int, patch: int, *, prerelease_token: str = 'rc', prerelease_revision: int | None = None, build_metadata: str = '', tag_format: str = 'v{version}')
        Bases: object

        as_major_tag() -> str

        as_minor_tag() -> str

        as_patch_tag() -> str

        as_semver_tag() -> str

        as_tag() -> str

        bump(level: LevelBump <#semantic_release.enums.LevelBump>) -> Version <#semantic_release.version.version.Version>
            Return a new Version instance according to the level specified to bump. Note this will intentionally drop the build metadata - that should be added elsewhere for the specific build producing this version.

        finalize_version() -> Version <#semantic_release.version.version.Version>

        property is_prerelease: bool

        classmethod parse(version_str: str, tag_format: str = 'v{version}', prerelease_token: str = 'rc') -> Version <#semantic_release.version.version.Version>
            Parse version string to a Version instance. Inspired by semver.version:VersionInfo.parse, this implementation doesn't allow optional minor and patch versions.

            Parameters
                prerelease_token -- will be ignored if the version string is a prerelease, the parsed token from version_str will be used instead.

        property tag_format: str

        to_prerelease(token: str | None = None, revision: int | None = None) -> Version <#semantic_release.version.version.Version>

  Submodules

  semantic_release.const module

  semantic_release.enums module

    class semantic_release.enums.LevelBump(*values)
        Bases: IntEnum

        IntEnum representing valid types of bumps for a version. We use an IntEnum to enable ordering of levels.

        MAJOR = 4

        MINOR = 3

        NO_RELEASE = 0

        PATCH = 2

        PRERELEASE_REVISION = 1

        classmethod from_string(val: str) -> LevelBump <#semantic_release.enums.LevelBump>
            Get the level from string representation. For backwards-compatibility, dashes are replaced with underscores so that: >>> LevelBump.from_string("no-release") == LevelBump.NO_RELEASE Equally, >>> LevelBump.from_string("minor") == LevelBump.MINOR

    class semantic_release.enums.SemanticReleaseLogLevels(*values)
        Bases: IntEnum

        IntEnum representing the log levels used by semantic-release.

        CRITICAL = 50

        DEBUG = 10

        ERROR = 40

        FATAL = 50

        INFO = 20

        SILLY = 5

        WARNING = 30

  semantic_release.errors module

Custom Errors

    exception semantic_release.errors.AssetUploadError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure uploading an asset to a remote hvcs's release artifact storage.

    exception semantic_release.errors.BuildDistributionsError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to build the distribution files.

    exception semantic_release.errors.CommitParseError
        Bases: SemanticReleaseBaseError

        Raised when a commit cannot be parsed by a commit parser. Custom commit parsers should also raise this Exception

    exception semantic_release.errors.DetachedHeadGitError
        Bases: SemanticReleaseBaseError

        Raised when the git repository is in a detached HEAD state

    exception semantic_release.errors.GitAddError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to add files to the git index.

    exception semantic_release.errors.GitCommitEmptyIndexError
        Bases: SemanticReleaseBaseError

        Raised when there is an attempt to commit an empty index.

    exception semantic_release.errors.GitCommitError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to commit the changes.

    exception semantic_release.errors.GitFetchError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to fetch from the git remote.

    exception semantic_release.errors.GitPushError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to push to the git remote.

    exception semantic_release.errors.GitTagError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to tag the release.

    exception semantic_release.errors.IncompleteReleaseError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure amongst one of the api requests when creating a release on a remote hvcs.

    exception semantic_release.errors.InternalError
        Bases: SemanticReleaseBaseError

        Raised when an internal error occurs, which should never happen

    exception semantic_release.errors.InvalidConfiguration
        Bases: SemanticReleaseBaseError

        Raised when configuration is deemed invalid

    exception semantic_release.errors.InvalidParserOptions
        Bases: InvalidConfiguration

        Raised when the parser options are invalid

    exception semantic_release.errors.InvalidVersion
        Bases: ValueError, SemanticReleaseBaseError

        Raised when Version.parse attempts to parse a string containing an invalid version.

    exception semantic_release.errors.LocalGitError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure with local git operations.

    exception semantic_release.errors.MissingGitRemote
        Bases: SemanticReleaseBaseError

        Raised when repository is missing the configured remote origin or upstream

    exception semantic_release.errors.MissingMergeBaseError
        Bases: SemanticReleaseBaseError

        Raised when the merge base cannot be found with the current history. Generally because of a shallow git clone.

    exception semantic_release.errors.NotAReleaseBranch
        Bases: InvalidConfiguration

        Raised when semantic_release is invoked on a branch which isn't configured for releases

    exception semantic_release.errors.ParserLoadError
        Bases: SemanticReleaseBaseError

        Raised when there is a failure to find, load, or instantiate a custom parser definition.

    exception semantic_release.errors.SemanticReleaseBaseError
        Bases: Exception

        Base Exception from which all other custom Exceptions defined in semantic_release inherit

    exception semantic_release.errors.UnexpectedResponse
        Bases: SemanticReleaseBaseError

        Raised when an HTTP response cannot be parsed properly or the expected structure is not found.

    exception semantic_release.errors.UnknownUpstreamBranchError
        Bases: SemanticReleaseBaseError

        Raised when the upstream branch cannot be determined.

    exception semantic_release.errors.UpstreamBranchChangedError
        Bases: SemanticReleaseBaseError

        Raised when the upstream branch has changed before pushing.

  semantic_release.gitproject module

Module for git related operations.

    class semantic_release.gitproject.GitProject(directory: Path | str = '.', commit_author: Actor | None = None, credential_masker: MaskingFilter <#semantic_release.cli.masking_filter.MaskingFilter> | None = None)
        Bases: object

        git_add(paths: Sequence[Path | str], force: bool = False, strict: bool = False, noop: bool = False) -> None

        git_commit(message: str, date: int | None = None, commit_all: bool = False, no_verify: bool = False, noop: bool = False) -> None

        git_push_branch(remote_url: str, branch: str, noop: bool = False) -> None

        git_push_tag(remote_url: str, tag: str, noop: bool = False, force: bool = False) -> None

        git_tag(tag_name: str, message: str, isotimestamp: str, force: bool = False, noop: bool = False) -> None

        git_unshallow(noop: bool = False) -> None
            Convert a shallow clone to a full clone by fetching the full history.

            Parameters
                noop -- Whether or not to actually run the unshallow command

        is_dirty() -> bool

        is_shallow_clone() -> bool
            Check if the repository is a shallow clone.

            Returns
                True if the repository is a shallow clone, False otherwise

        property logger: Logger

        property project_root: Path

        verify_upstream_unchanged(local_ref: str = 'HEAD', upstream_ref: str = 'origin', remote_url: str | None = None, noop: bool = False) -> None
            Verify that the upstream branch has not changed since the given local reference.

            Parameters

                •   local_ref -- The local reference to compare against upstream (default: HEAD)

                •   upstream_ref -- The name of the upstream remote or specific remote branch (default: origin)

                •   remote_url -- Optional authenticated remote URL to use for fetching (default: None, uses configured remote)

                •   noop -- Whether to skip the actual verification (for dry-run mode)

            Raises
                UpstreamBranchChangedError <#semantic_release.errors.UpstreamBranchChangedError> -- If the upstream branch has changed

  semantic_release.globals module

Semantic Release Global Variables.

    semantic_release.globals.log_level: SemanticReleaseLogLevels <#semantic_release.enums.SemanticReleaseLogLevels> = SemanticReleaseLogLevels.WARNING
        int: Logging level for semantic-release

    semantic_release.globals.logger: Logger = <Logger semantic_release (WARNING)>
        Logger for semantic-release

  semantic_release.helpers module

    class semantic_release.helpers.ParsedGitUrl(scheme: str, netloc: str, namespace: str, repo_name: str)
        Bases: NamedTuple

        Container for the elements parsed from a git URL

        namespace: str
            Alias for field number 2

        netloc: str
            Alias for field number 1

        repo_name: str
            Alias for field number 3

        scheme: str
            Alias for field number 0

    semantic_release.helpers.check_tag_format(tag_format: str) -> None

    semantic_release.helpers.dynamic_import(import_path: str) -> Any
        Dynamically import an object from a conventionally formatted "module:attribute" string

    semantic_release.helpers.format_arg(value: Any) -> str
        Helper to format an argument an argument for logging

    semantic_release.helpers.get_number_from_str(string: str, default: int = -1, interpret_hex: bool = False) -> int

    semantic_release.helpers.logged_function(logger: Logger) -> Callable[[_FuncType[_R]], _FuncType[_R]]
        Decorator which adds debug logging of a function's input arguments and return value.

        The input arguments are logged before the function is called, and the return value is logged once it has completed.

        Parameters
            logger -- Logger to send output to.

    semantic_release.helpers.parse_git_url(url: str) -> ParsedGitUrl <#semantic_release.helpers.ParsedGitUrl>
        Attempt to parse a string as a git url http[s]://, git://, file://, or ssh format, into a ParsedGitUrl.

        supported examples:
            <http://git.mycompany.com/username/myproject.git> <https://github.com/username/myproject.git> <https://gitlab.com/group/subgroup/myproject.git> <https://git.mycompany.com:4443/username/myproject.git> git://host.xz/path/to/repo.git/ git://host.xz:9418/path/to/repo.git/ git@github.com:username/myproject.git <-- assumes ssh:// ssh://git@github.com:3759/myproject.git <-- non-standard, but assume user 3759 ssh://git@github.com:username/myproject.git ssh://git@bitbucket.org:7999/username/myproject.git git+ssh://git@github.com:username/myproject.git /Users/username/dev/remote/myproject.git <-- Posix File paths file:///Users/username/dev/remote/myproject.git C:/Users/username/dev/remote/myproject.git <-- Windows File paths file:///C:/Users/username/dev/remote/myproject.git

    REFERENCE: <https://stackoverflow.com/questions/31801271/what-are-the-supported-git-url-formats>

    Raises ValueError if the url can't be parsed.

    semantic_release.helpers.sort_numerically(iterable: Iterable[str], reverse: bool = False, allow_hex: bool = False) -> list[str]

    semantic_release.helpers.text_reducer(text: str, filter_pair: tuple[Pattern[str], str]) -> str
        Reduce function to apply mulitple filters to a string

    semantic_release.helpers.validate_types_in_sequence(sequence: Sequence, types: type | tuple[type, ...]) -> bool
        Validate that all elements in a sequence are of a specific type

  Contributing

Love Python Semantic Release? Want to help out? There are many ways you can contribute to the project!

You can help by:

    •   Reporting bugs and issues

    •   Suggesting new features

    •   Improving the documentation

    •   Reviewing pull requests

    •   Contributing code

    •   Helping with translations

    •   Spreading the word about Python Semantic Release

    •   Participating in discussions

    •   Testing new features and providing feedback

No matter how you choose to contribute, please check out our Contributing Guidelines <#contributing-guide> and know we appreciate your help!

Check out all the folks whom already contributed to Python Semantic Release and become one of them today!

Contributors <https://github.com/python-semantic-release/python-semantic-release/graphs/contributors>

  Contributing

If you want to contribute that is awesome. Remember to be nice to others in issues and reviews.

Please remember to write tests for the cool things you create or fix.

Unsure about something? No worries, open an issue <https://github.com/python-semantic-release/python-semantic-release/issues/new>.

  Commit messages

Since python-semantic-release is released with python-semantic-release we need the commit messages to adhere to the Conventional Commits Specification <https://www.conventionalcommits.org/en/v1.0.0>. Although scopes are optional, scopes are expected where applicable. Changes should be committed separately with the commit type they represent, do not combine them all into one commit.

If you are unsure how to describe the change correctly just try and ask about it in your pr. If we think it should be something else or there is a pull-request without tags we will help out in adding or changing them.

  Releases

This package is released by python-semantic-release on each master build, thus if there are changes that should result in a new release it will happen if the build is green.

  Development

Install this module and the development dependencies

            pip install -e .[dev,mypy,test]

And if you'd like to build the documentation locally

            pip install -e .[docs]
            sphinx-autobuild --open-browser docs docs/_build/html

  Testing

To test your modifications locally:

            # Run type-checking, all tests across all supported Python versions
            tox

            # Run all tests for your current installed Python version (with full error output)
            pytest -vv --comprehensive

            # Run unit tests for your current installed Python version
            pytest
            # or
            pytest -vv -m unit

            # Run end-to-end tests for your current installed Python version (with full error output)
            pytest -vv -m e2e [--comprehensive]

The --comprehensive flag is optional and will run all the variations of tests and it does take significantly longer to run.

  Building

This project is designed to be versioned and built by itself using the tool.semantic_release configuration in pyproject.toml. The setting tool.semantic_release.build_command defines the command to run to build the package.

The following is a copy of the build_command setting which can be run manually to build the package locally:

            pip install -e .[build]
            python -m build .

----

GETTING STARTED

If you haven't done so already, install Python Semantic Release locally following the installation instructions.

If you are using a CI/CD service, you may not have to add Python Semantic Release to your project's dependencies permanently, but for the duration of this guide for the initial setup, you will need to have it installed locally.

  Configuring PSR

Python Semantic Release ships with a reasonable default configuration but some aspects MUST be customized to your project. To view the default configuration, run the following command:

            semantic-release generate-config

The output of the above command is the default configuration in TOML format without any modifications. If this is fine for your project, then you do not need to configure anything else.

PSR accepts overrides to the default configuration keys individually. If you don't define the key-value pair in your configuration file, the default value will be used.

By default, Python Semantic Release will look for configuration overrides in pyproject.toml under the TOML table [tool.semantic_release]. You may specify a different file using the -c/--config option, for example:

            # In TOML format with top level table [semantic_release]
            semantic-release -c releaserc.toml

            # In JSON format with top level object key {"semantic_release": {}}
            semantic-release -c releaserc.json

The easiest way to get started is to output the default configuration to a file, delete keys you do not need to override, and then edit the remaining keys to suit your project.

To set up in pyproject.toml, run the following command:

            # In file redirect in bash
            semantic-release generate-config --pyproject >> pyproject.toml

            # Open your editor to edit the configuration
            vim pyproject.toml

See also:

            •   cmd-generate-config

            •   Configuration <#configuration>

  Configuring the Version Stamp Feature

One of the best features of Python Semantic Release is the ability to automatically stamp the new version number into your project files, so you don't have to manually update the version upon each release. The version that is stamped is automatically determined by Python Semantic Release from your commit messages which compliments automated versioning seamlessly.

The most crucial version stamp is the one in your project metadata, which is used by the Python Package Index (PyPI) and other package managers to identify the version of your package.

For Python projects, this is typically the version field in your pyproject.toml file. First, set up your project metadata with the base version value. If you are starting with a brand new project, set project.version = "0.0.0". If you are working on an existing project, set it to the last version number you released. Do not include any v prefix.

Important:
        The version number must be a valid SemVer version, which means it should follow the format MAJOR.MINOR.PATCH (e.g., 1.0.0). Python Semantic Release does NOT support Canonical version values defined in the PEP 440 <https://peps.python.org/pep-0440/> specification at this time. See Issue #455 <https://github.com/python-semantic-release/python-semantic-release/issues/455> for more details. Note that you can still define a SemVer version in the project.version field, and when your build is generated, the build tool will automatically generate a PEP 440 compliant version as long as you do NOT use a non-pep440 compliant pre-release token.

Your project metadata might look like this in pyproject.toml:

            [project]
            name = "my-package"
            version = "0.0.0"  # Set this to the last released version or "0.0.0" for new projects
            description = "A sample Python package"

To configure PSR to automatically update this version number, you need to specify the file and value to update in your configuration. Since pyproject.toml uses TOML format, you will add the replacement specification to the tool.semantic_release.version_toml list. Update the following configuration in your pyproject.toml file to include the version variable location:

            [tool.semantic_release]
            version_toml = ["pyproject.toml:project.version"]

            # Alternatively, if you are using poetry's 'version' key, then you would use:
            version_toml = ["pyproject.toml:tool.poetry.version"]

If you have other TOML files where you want to stamp the version, you can add them to the version_toml list as well. In the above example, there is an implicit assumption that you only want the version as the raw number format. If you want to specify the full tag value (e.g. v-prefixed version), then include :tf for "tag format" at the end of the version variable specification.

For non-TOML formatted files (such as JSON or YAML files), you can use the version_variables <#config-version-variables> configuration key instead. This feature uses an advanced Regular Expression to find and replace the version variable in the specified files.

For Python files, its much more effective to use importlib instead which will allow you to dynamically import the version from your package metadata and not require your project to commit the version number bump to the repository. For example, in your package's base __init__.py

            # my_package/__init__.py
            from importlib.metadata import version as get_version

            __version__ = get_version(__package__)
            # Note: __package__ must match your 'project.name' as defined in pyproject.toml

See also:

            •   Configuration specification of version_toml <#config-version-toml>

            •   Configuration specification of version_variables <#config-version-variables>

  Using PSR to Build your Project

PSR provides a convenient way to build your project artifacts as part of the versioning process now that you have stamped the version into your project files. To enable this, you will need to specify the build command in your configuration. This command will be executed after the next version has been determined, and stamped into your files but before a release tag has been created.

To set up the build command, add the following to your pyproject.toml file:

            [tool.semantic_release]
            build_command = "python -m build --sdist --wheel ."

See also:

            •   build_command <#config-build-command> - Configuration specification for the build command.

            •   build_command_env <#config-build-command-env> - Configuration specification for the build command environment variables.

  Choosing a Commit Message Parser

PSR uses commit messages to determine the type of version bump that should be applied to your project. PSR supports multiple commit message parsing styles, allowing you to choose the one that best fits your project's needs. Choose one of the supported commit parsers defined in Commit Parsing <#commit-parsing>, or provide your own and configure it in your pyproject.toml file.

Each commit parser has its own default configuration options so if you want to customize the parser behavior, you will need to specify the parser options you want to override.

            [tool.semantic_release]
            commit_parser = "conventional"

            [tool.semantic_release.commit_parser_options]
            minor_tags = ["feat"]
            patch_tags = ["fix", "perf"]
            parse_squash_commits = true
            ignore_merge_commits = true

  Choosing your Changelog

Prior to creating a release, PSR will generate a changelog from the commit messages of your project. The changelog is extremely customizable from the format to the content of each section. PSR ships with a default changelog template that will be used if you do not provide custom templates. The default should be sufficient for most projects and has its own set of configuration options.

For basic customization, you can choose either an traditional Markdown formatted changelog (default) or if you want to integrate with a Sphinx Documentation project, you can use the reStructuredText (RST) format. You can also choose the file name and location of where to write the default changelog.

To set your changelog location and changelog format, add the following to your pyproject.toml file:

            [tool.semantic_release.changelog.default_templates]
            changelog_file = "docs/source/CHANGELOG.rst"
            output_format = "rst" # or "md" for Markdown format

Secondly, the more important aspect of configuring your changelog is to define Commit Exclusion Patterns or patterns that will be used to filter out commits from the changelog. PSR does NOT (yet) come with a built-in set of exclusion patterns, so you will need to define them yourself. These commit patterns should be in line with your project's commit parser configuration.

To set commit exclusion patterns for a conventional commits parsers, add the following to your pyproject.toml file:

            [tool.semantic_release.changelog]
            # Recommended patterns for conventional commits parser that is scope aware
            exclude_commit_patterns = [
                '''chore(?:\([^)]*?\))?: .+''',
                '''ci(?:\([^)]*?\))?: .+''',
                '''refactor(?:\([^)]*?\))?: .+''',
                '''style(?:\([^)]*?\))?: .+''',
                '''test(?:\([^)]*?\))?: .+''',
                '''build\((?!deps\): .+)''',
                '''Initial [Cc]ommit.*''',
            ]

See also:

            •   Changelog <#config-changelog> - Customize your changelog

            •   changelog.mode <#config-changelog-mode> - Choose the changelog mode ('update' or 'init')

            •   Migrating an Existing Changelog <#changelog-templates-migrating-existing-changelog>

  Defining your Release Branches

PSR provides a powerful feature to manage release types across multiple branches which can allow you to configure your project to have different release branches for different purposes, such as pre-release branches, beta branches, and your stable releases.

Note:
        Most projects that do NOT publish pre-releases will be fine with PSR's built-in default.

To define an alpha pre-release branch when you are working on a fix or new feature, you can add the following to your pyproject.toml file:

            [tool.semantic_release.branches.alpha]
            # Matches branches with the prefixes 'feat/', 'fix/', or 'perf/'.
            match = "^(feat|fix|perf)/.+"
            prerelease = true
            prerelease_token = "alpha"

Any time you execute semantic-release version on a branch with the prefix feat/, fix/, or perf/, PSR will determine if a version bump is needed and if so, the resulting version will be a pre-release version with the alpha token. For example,
Branch | Version Bump | Current Version | Next Version
main | Patch | 1.0.0 | 1.0.1
fix/bug-1 | Patch | 1.0.0 | 1.0.1-alpha.1

See also:

            •   Multibranch Releases <#multibranch-releases> - Learn about multi-branch releases and how to configure them.

  Configuring 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.

  GitHub (GH_TOKEN)

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 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 <https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens#repository-permissions-for-contents> permission.

  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 <https://support.atlassian.com/bitbucket-cloud/docs/push-back-to-your-repository/#App-secret>, store the secret in the BITBUCKET_TOKEN environment variable and the username in BITBUCKET_USER.

    3.  Use an Access Token <https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens> for the repository and store it in the BITBUCKET_TOKEN environment variable.

See also:

            •   Changelog <#config-changelog> - customize your project's changelog.

            •   Custom Release Notes <#changelog-templates-custom-release-notes> - customize the published release notes

            •   version --vcs-release/--no-vcs-release - enable/disable VCS release creation.

  Testing your Configuration

It's time to test your configuration!

            # 1. Run the command in no-operation mode to see what would happen
            semantic-release -v --noop version

            # 2. If the output looks reasonable, try to run the command without any history changes
            #    '-vv' will give you verbose debug output, which is useful for troubleshooting
            #    commit parsing issues.
            semantic-release -vv version --no-commit --no-tag

            # 3. Evaluate your repository to see the changes that were made but not committed
            #    - Check the version number in your pyproject.toml
            #    - Check the distribution files from the build command
            #    - Check the changelog file for the new release notes

            # 4. If everything looks good, make sure to commit/save your configuration changes
            git add pyproject.toml
            git commit -m "chore(config): configure Python Semantic Release"

            # 5. Now, try to run the release command with your history changes but without pushing
            semantic-release -v version --no-push --no-vcs-release

            # 6. Check the result on your local repository
            git status
            git log --graph --decorate --all

            # 7a. If you are happy with the release history and resulting commit & tag,
            #     reverse your changes before trying the full release command.
            git tag -d v0.0.1  # replace with the actual version you released
            git reset --hard HEAD~1

            # 7b. [Optional] Once you have configured a remote VCS token, try
            #     running the full release command to update the remote repository.
            semantic-release version --push --vcs-release
            #    This is optional as you may not want a personal access token set up or make
            #    make the release permanent yet.

See also:

            •   cmd-version

            •   Increasing Verbosity <#troubleshooting-verbosity>

  Configuring CI/CD

PSR is meant to help you release at speed! See our CI/CD Configuration guides under the Automated Releases <#automatic> section.

Author
Python Semantic Release Team

Copyright
2025, Python Semantic Release Team