### Install Python Semantic Release and View Help

Source: https://python-semantic-release.readthedocs.io/en/latest/index.html

Installs the package using pip and displays the command-line help information.

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

```

--------------------------------

### Install Development Dependencies

Source: https://python-semantic-release.readthedocs.io/en/latest/contributing/contributing_guide.html

Install the package in editable mode with development and testing dependencies.

```bash
pip install -e .[dev,mypy,test]
```

--------------------------------

### Install Build Status Checking Dependencies

Source: https://python-semantic-release.readthedocs.io/en/latest/upgrading/08-upgrade.html

Install curl and jq on Ubuntu systems to enable build status checking functionality.

```bash
sudo apt update && sudo apt upgrade
sudo apt install -y curl jq

```

--------------------------------

### Monorepo Directory Structure Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Illustrates a common monorepo file structure where each package has its own configuration.

```text
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
```

--------------------------------

### Build Documentation Locally

Source: https://python-semantic-release.readthedocs.io/en/latest/contributing/contributing_guide.html

Install documentation dependencies and use sphinx-autobuild to serve the documentation locally with live reloading.

```bash
pip install -e .[docs]
sphinx-autobuild --open-browser docs docs/_build/html
```

--------------------------------

### Install uv in build command for CI

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/uv_integration.html

When using the PSR GitHub Action or similar CI environments, include a command to install uv (e.g., `python -m pip install -e '.[build]'`) before updating the lock file. Define uv in `project.optional-dependencies` for version management.

```toml
[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
"""

```

--------------------------------

### Example Configuration - Environment Variables

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Illustrates how to set semantic-release configuration options using environment variables. This is useful for CI/CD environments.

```bash
export SEMANTIC_RELEASE_VERSION="0.1.0"
export SEMANTIC_RELEASE_COMMIT_PARSER_MAJOR_VERSION_REGEX="^BREAKING CHANGE:"
export SEMANTIC_RELEASE_PUBLISH_DIST_GLOB_PATTERNS="dist/*"
export SEMANTIC_RELEASE_PUBLISH_UPLOAD_TO_VCS_RELEASE=true
```

--------------------------------

### Install python-semantic-release

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/cronjobs.rst.txt

Install the python-semantic-release package using pip within your virtual environment.

```bash
pip install python-semantic-release
```

--------------------------------

### Example Configuration - pyproject.toml

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Shows how to configure semantic-release within a pyproject.toml file. This is an alternative to using a dedicated .semanticreliserc file.

```toml
[tool.semantic_release]
version = "0.1.0"
commit_parser.major_version_regex = "^BREAKING CHANGE:"
publish.dist_glob_patterns = ["dist/*"]
publish.upload_to_vcs_release = true
```

--------------------------------

### Example: TOML Version Update Diff (definition.toml)

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Illustrates the diff for updating `version` and `release` in `definition.toml`.

```diff
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"


```

--------------------------------

### Common Continuous Delivery Workflow Example

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html

This workflow example demonstrates using both the Python Semantic Release Action and the Python Semantic Release Publish Action. It runs on every push to the `main` branch, creates a new release, publishes to PyPI, and uploads assets to GitHub Releases.

```yaml
name: Continuous Delivery

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build
          pip install semantic-release
      - name: Publish to PyPI and GitHub Releases
        uses: python-semantic-release/publish-action@v9
        with:
          github_token: "${{ secrets.GITHUB_TOKEN }}"
          pypi_token: "${{ secrets.PYPI_TOKEN }}"
```

--------------------------------

### Example Configuration - .semanticreliserc

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Demonstrates a basic configuration for semantic-release using a .semanticreliserc file. This includes settings for versioning, commit parsing, and publishing.

```json
{
    "version": "0.1.0",
    "commit_parser": {
        "major_version_regex": "^BREAKING CHANGE:"
    },
    "publish": {
        "dist_glob_patterns": [
            "dist/*"
        ],
        "upload_to_vcs_release": true
    }
}
```

--------------------------------

### Install curl and jq for Build Status Checking

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/upgrading/08-upgrade.rst.txt

This bash command installs curl and jq on Ubuntu systems, which are required for the new build status checking functionality replacing the removed `check_build_status` option.

```bash
sudo apt update && sudo apt upgrade
sudo apt install -y curl jq
```

--------------------------------

### Create Virtual Environment

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/cronjobs.rst.txt

Use this command to create a virtual environment for installing python-semantic-release.

```bash
virtualenv semantic_release -p `which python3`
```

--------------------------------

### Example Changelog Output from Squash Commit

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/commit_parsing.rst.txt

This markdown illustrates the expected changelog output generated from the example GitHub squash commit message. It shows how different commit types are categorized and presented.

```markdown
## 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)
```

--------------------------------

### Example: Partial Tags with Version 1.2.3

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Demonstrates the Git log output when `add_partial_tags` is enabled and the next version is `1.2.3`.

```bash
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
# ...

```

--------------------------------

### Template Environment Setup

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Configures the template environment using a specified template directory and additional model dump parameters.

```python
template_environment = environment(
    template_dir=template_dir,
    **raw.changelog.environment.model_dump(),
)
```

--------------------------------

### Unsquash Commit Example (GitHub)

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/commit_parser/emoji.html

Illustrates how a squashed merge commit, typically from GitHub, is handled. The example shows a commit message format that includes an emoji, scope, description, and a merge request number.

```text
# GitHub EXAMPLE:
# ✨(changelog): add autofit_text_width filter to template environment (#1062)
#
#
# This change adds an equivalent style formatter that can apply a text alignment
```

--------------------------------

### Integrate uv Installation in Build Command

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/uv_integration.rst.txt

When using uv within a CI environment like the PSR GitHub Action, ensure uv is installed by adding it to an optional dependency group (e.g., `build`). The `build_command` then includes installing this group before running `uv lock` and `uv build`.

```toml
[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
"""
```

--------------------------------

### Build Package Locally

Source: https://python-semantic-release.readthedocs.io/en/latest/contributing/contributing_guide.html

Install build dependencies and use the 'build' package to create a local distribution of the project.

```bash
pip install -e .[build]
python -m build .
```

--------------------------------

### CI Workflow: End-to-End Testing with UV

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/uv_integration.html

This GitHub Actions workflow sets up a CI job for end-to-end testing. It downloads build artifacts, installs UV, synchronizes test dependencies, installs the project's distribution artifact, and runs pytest.

```yaml
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
```

--------------------------------

### Example of Partial Tagging Output

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration.rst.txt

Demonstrates the git tag output when partial tags are enabled and the next version is 1.2.3.

```bash
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
# ...
```

--------------------------------

### Example: Partial Tags with Build Metadata

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Shows the Git log when build metadata is present and `add_partial_tags` is enabled, using `1.2.3+20251109` as the next version.

```bash
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
# ...

```

--------------------------------

### Monorepo Directory Structure Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Illustrates a typical monorepo project structure with separate package directories and a shared configuration for release templates.

```treeview
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
```

--------------------------------

### Package 1 PSR Configuration

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Example `pyproject.toml` configuration for `pkg1` using the `conventional-monorepo` commit parser.

```toml
# 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-"
```

--------------------------------

### Example: TOML Version Update Diff (pyproject.toml)

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Shows the diff for updating the version in `pyproject.toml` from `0.1.0` to `0.2.0`.

```diff
diff a/pyproject.toml b/pyproject.toml

  [tool.poetry]
- version = "0.1.0"
+ version = "0.2.0"


```

--------------------------------

### Package 2 PSR Configuration

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Example `pyproject.toml` configuration for `pkg2` using the `conventional-monorepo` commit parser.

```toml
# 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-"
```

--------------------------------

### Iterate Through Released Versions

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Example showing how to access and iterate over released versions from the 'history' context object to include version-specific changes.

```jinja
{%    set unreleased_commits = ctx.history.unreleased | dictsort
%}{%  for release in context.history.released.values()
%}{%    include ".versioned_changes.md.j2"
#}{%  endfor
%}
```

--------------------------------

### Get Default Template Directory

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/changelog_writer.html

Retrieves the path to the default template directory based on the specified style and subdirectory. Raises an InternalError if the directory is not found, indicating a corrupted installation.

```python
from pathlib import Path

import semantic_release
from semantic_release.cli.const import JINJA2_EXTENSION
from semantic_release.errors import InternalError
from importlib_resources import files




[docs]
def get_default_tpl_dir(style: str, sub_dir: str | None = None) -> Path:
    module_base_path = Path(str(files(semantic_release.__name__)))
    default_templates_path = module_base_path.joinpath(
        f"data/templates/{style}",
        "" if sub_dir is None else sub_dir.strip("/"),
    )

    if default_templates_path.is_dir():
        return default_templates_path

    raise InternalError(
        str.join(
            " ",
            [
                "Default template directory not found at",
                f"{default_templates_path}. Installation corrupted!",
            ],
        )
    )
```

--------------------------------

### Get Windows Environment Variables

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/commands/version.html

Retrieves a specific set of environment variables commonly found on Windows systems. This is useful for ensuring consistent environment configurations across different Windows setups.

```python
def get_windows_env() -> Mapping[str, str | None]:
    return {
        environment_variable: os.getenv(environment_variable, None)
        for environment_variable in (
            "ALLUSERSAPPDATA",
            "ALLUSERSPROFILE",
            "APPDATA",
            "COMMONPROGRAMFILES",
            "COMMONPROGRAMFILES(X86)",
            "DEFAULTUSERPROFILE",
            "HOMEPATH",
            "PATHEXT",
            "PROFILESFOLDER",
            "PROGRAMFILES",
            "PROGRAMFILES(X86)",
            "SYSTEM",
            "SYSTEM16",
            "SYSTEM32",
            "SYSTEMDRIVE",
            "SYSTEMPROFILE",
            "SYSTEMROOT",
            "TEMP",
            "TMP",
            "USERNAME",  # must include for python getpass.getuser() on windows
            "USERPROFILE",
            "USERSID",
            "WINDIR",
        )
    }
```

--------------------------------

### Attach Build Metadata to Versions

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/multibranch_releases.rst.txt

Use the `semantic-release version` command with build metadata to include branch and date information in version tags. This example uses bash commands to get the current branch and date.

```bash
semantic-release version \
   --build-metadata "$(git branch --show-current).$(date +%Y%m%d)"
```

--------------------------------

### Get the last released version from Git tags

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/commands/version.html

Retrieves the latest released version and its corresponding Git tag from a repository. It uses a provided tag format and an option to include partial tags. This is essential for determining the starting point for new releases.

```python
def last_released(
    repo_dir: Path,
    tag_format: str,
    add_partial_tags: bool = False,
) -> tuple[Tag, Version] | None:
    with Repo(str(repo_dir)) as git_repo:
        ts_and_vs = tags_and_versions(
            git_repo.tags,
            VersionTranslator(tag_format=tag_format, add_partial_tags=add_partial_tags),
        )

    return ts_and_vs[0] if ts_and_vs else None
```

--------------------------------

### Example Project Structure After Release

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Illustrates the expected directory structure of a project after a release, highlighting the generated CHANGELOG.md and other project files. The template directory itself is not included in the output.

```text
example-project/
    ├── CHANGELOG.md
    ├── src/
    │   └── example_project/
    │       ├── data/
    │       │   └── data.json
    │       └── __init__.py
    └── static/
        └── config.cfg
```

--------------------------------

### Print Next Version with Prerelease

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Prints the next version that will be applied, including a prerelease, and then exits.

```bash
semantic-release version --prerelease --print
```

--------------------------------

### setup_hook

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.html

A hook to be used in setup.py to enable python setup.py publish.

```APIDOC
## setup_hook

### Description
A hook to be used in setup.py to enable python setup.py publish.

### Parameters
#### Path Parameters
- **argv** (list[str]) - Required - sys.argv
```

--------------------------------

### Force Version Increment Examples

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Demonstrates how to force the next version to be a patch, minor, major, or prerelease, and prints the result. These options override the usual calculation.

```bash
semantic-release version --prerelease --print
# 0.2.1-rc.2
```

```bash
semantic-release version --patch --print
# 0.2.2
```

```bash
semantic-release version --minor --print
# 0.3.0
```

```bash
semantic-release version --major --print
# 1.0.0
```

```bash
semantic-release version --minor --as-prerelease --print
# 0.3.0-rc.1
```

```bash
semantic-release version --prerelease --as-prerelease --print
# 0.2.1-rc.2
```

--------------------------------

### Example Generated Markdown Changelog

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

The resulting Markdown changelog generated from the example template, showing formatted release versions and commit details with links.

```markdown
# 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))
```

--------------------------------

### Configure Root Options for semantic-release

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html

This example shows how to pass additional options to the main semantic-release command, which will precede the version subcommand. This configuration would cause the command to be `semantic-release -vv --noop version`.

```yaml
uses: python-semantic-release/python-semantic-release@v9
  with:
    root_options: "-vv --noop"
```

--------------------------------

### Example GitHub Squash Commit Message

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/commit_parsing.rst.txt

This is an example of a GitHub-formatted squash commit message with conventional commit style. It demonstrates how multiple commits can be embedded within a single squash commit.

```text
feat(config): add new config option (#123)

    * refactor(config): change the implementation of config loading

    * docs(configuration): defined new config option for the project
```

--------------------------------

### Example of Partial Tagging with Build Metadata

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration.rst.txt

Shows the git tag output when partial tags are enabled and the next version includes build metadata.

```bash
git log --decorate --oneline --graph --all
```

--------------------------------

### get_release_id_by_tag

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.hvcs.github.html

Get a release by its tag name.

```APIDOC
## get_release_id_by_tag

### Description
Get a release by its tag name.

### Parameters
* **tag** (str) - Tag to get release for.

### Returns
* int | None - ID of release, if found, else None.
```

--------------------------------

### get_release_by_tag

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.hvcs.gitlab.html

Get a release by its tag name.

```APIDOC
## get_release_by_tag(_tag : str_) -> ProjectRelease | None

### Description
Get a release by its tag name.

### Parameters
* **tag** (str) - The tag name to get the release for

### Returns
(gitlab.v4.objects.ProjectRelease | None) - The release object or None if not found

### Raises
* **gitlab.exceptions.GitlabAuthenticationError** - If the user is not authenticated
```

--------------------------------

### Initialize Gitea Helper

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/gitea.html

Instantiate the Gitea helper class with repository URL and optional token or domain. It configures the HTTP session for authenticated requests.

```python
Gitea(
    remote_url="https://gitea.com/user/repo.git",
    token="YOUR_GITEA_TOKEN",
    hvcs_domain="gitea.example.com",
    allow_insecure=True,
)
```

--------------------------------

### Release Notes Template Example (GitHub Style)

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/changelog_templates.html

A Jinja template for generating release notes similar to GitHub's automatically generated notes. It formats commit messages, authors, and links.

```jinja
## 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
%

```

--------------------------------

### Custom Changelog Jinja2 Template Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

An example of a Jinja2 template for generating release notes. It iterates through commit types and commits, formatting them into a Markdown list. This template assumes a specific data structure provided by the semantic-release library.

```jinja
## 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
%}
```

--------------------------------

### Unsquash Commit Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/commit_parser/angular.html

Provides examples of commit message formats for GitHub squashed merge commits and general git merge --squash commits. This method is used to split a squashed merge commit into individual commits for parsing.

```text
# GitHub EXAMPLE:
# feat(changelog): add autofit_text_width filter to template environment (#1062)
#
# This change adds an equivalent style formatter that can apply a text alignment
# to a maximum width and also maintain an indent over paragraphs of text
#
# * docs(changelog-templates): add definition & usage of autofit_text_width template filter
#
# * test(changelog-context): add test cases to check autofit_text_width filter use
#
# `git merge --squash` EXAMPLE:
# Squashed commit of the following:
#
# commit 63ec09b9e844e616dcaa7bae35a0b66671b59fbb
# Author: codejedi365 <codejedi365@gmail.com>
# Date:   Sun Oct 13 12:05:23 2024 -0600
#
#     feat(release-config): some commit subject

```

--------------------------------

### issue_url

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.hvcs.github.html

Get the URL for a given issue number.

```APIDOC
## issue_url

### Description
Get the URL for a given issue number.

### Parameters
* **issue_num** (str | int) - The issue number.

### Returns
* str - The URL for the issue.
```

--------------------------------

### asset_upload_url

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.hvcs.github.html

Get the correct upload URL for a release.

```APIDOC
## asset_upload_url

### Description
Get the correct upload url for a release.

### Parameters
* **release_id** (str) - ID of the release to upload to.

### Returns
* str | None - URL to upload for a release if found, else None.
```

--------------------------------

### CLI Version Override Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Demonstrates how to use the semantic-release CLI to force a patch version bump, disable changelog generation, and provide custom build metadata.

```shell
semantic-release version --patch --no-changelog --build-metadata abc123
```

--------------------------------

### pull_request_url

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.hvcs.github.html

Get the URL for a given pull request number.

```APIDOC
## pull_request_url

### Description
Get the URL for a given pull request number.

### Parameters
* **pr_number** (str | int) - The pull request number.

### Returns
* str - The URL for the pull request.
```

--------------------------------

### Full Version Command

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Executes the version command performing all available actions.

```bash
semantic-release version
```

--------------------------------

### get_changelog_context_filters

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/bitbucket.html

Get a tuple of callable filters used for generating changelog context.

```APIDOC
## get_changelog_context_filters

### Description
Get a tuple of callable filters used for generating changelog context.

### Returns
- (tuple[Callable[..., Any], ...]) - A tuple of filter functions.
```

--------------------------------

### remote_url

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/bitbucket.html

Get the remote URL for the repository, optionally including a token for authentication.

```APIDOC
## remote_url

### Description
Get the remote url including the token for authentication if requested.

### Parameters
- **use_token** (bool) - Optional - Whether to include the token for authentication.

### Returns
- (str) - The remote URL for the repository.

### Raises
- ValueError - If `use_token` is true and no token is set.
```

--------------------------------

### Print Next Version

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Use the `--print` option with the `version` command to display the next semantic version that will be applied to the project without making any changes.

```bash
semantic-release version --print
```

--------------------------------

### ScipyParserOptions.allowed_tags

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.commit_parser.scipy.html

Specifies all commit-type prefixes that are considered valid. Commits not starting with these prefixes will be ignored.

```python
allowed_tags_: Tuple[str, ...] = ('API', 'DEP', 'ENH', 'FEAT', 'BLD', 'BUG', 'MAINT', 'DEV', 'BENCH', 'DOC', 'STY', 'TST', 'REL', 'TEST')

```

--------------------------------

### Manual Release Steps in Monorepo

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/monorepos.html

Demonstrates the manual release process for packages in a monorepo. Requires changing the current directory to each package before running `semantic-release version`.

```bash
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)


```

--------------------------------

### Example pyproject.toml Project Metadata

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/getting_started.html

This TOML snippet shows the basic structure for project metadata in `pyproject.toml`, including the `name`, `version`, and `description` fields. Ensure the `version` field is set to the last released version or '0.0.0' for new projects.

```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"

```

--------------------------------

### Update newTag in kustomization.yml

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration.rst.txt

Example of updating the newTag variable in kustomization.yml using the tag format ('tf').

```diff
diff a/kustomization.yml b/kustomization.yml

      images:
        - name: repo/image
    -     newTag: v0.1.0
    +     newTag: v0.2.0
```

--------------------------------

### Print Next Version with Tag Prefix

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

To include the configured tag prefix when printing the next version, use the `--print-tag` option.

```bash
semantic-release version --print-tag
```

--------------------------------

### Update __version__ in __init__.py

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration.rst.txt

Example of updating the __version__ variable in src/semantic_release/__init__.py using the default number format.

```diff
diff a/src/semantic_release/__init__.py b/src/semantic_release/__init__.py

    - __version__ = "0.1.0"
    + __version__ = "0.2.0"
```

--------------------------------

### Create Virtual Environment

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/cronjobs.html

Creates a virtual environment named 'semantic_release' using the 'python3' interpreter.

```bash
virtualenv semantic_release -p `which python3`

```

--------------------------------

### Get Remote URL

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/gitlab.html

Retrieves the remote URL for the GitLab repository, optionally including a token for authentication.

```APIDOC
## remote_url

### Description
Get the remote url including the token for authentication if requested.

### Parameters
#### Path Parameters
- **use_token** (bool) - Optional - Whether to include the token for authentication (default: True)

### Returns
- **str**: The remote URL
```

--------------------------------

### Create Server URLs with create_server_url Filter

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Prepend the VCS server host and URL scheme to a given path using `create_server_url`. Optionally include authentication, query, or fragment strings.

```jinja
{{ "example/repo.git" | create_server_url }}
```

```jinja
{{ "example/repo" | create_server_url(None, "results=1", "section-header") }}
```

--------------------------------

### Get Default Emoji Parser Options

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/commit_parser/emoji.html

Provides the default configuration options for the emoji commit parser.

```python
    @staticmethod
    def get_default_options() -> EmojiParserOptions:
        return EmojiParserOptions()

```

--------------------------------

### Get Commit Hash URL

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/gitea.html

Generates a URL to a specific commit hash within the Gitea repository.

```APIDOC
## commit_hash_url

### Description
Generates a URL pointing to a specific commit in the repository.

### Parameters
#### Path Parameters
- **commit_hash** (str) - Required - The hash of the commit.

### Returns
- str - The URL for the commit.
```

--------------------------------

### Monorepo Directory Structure Example

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/monorepos.html

Illustrates a common monorepo file structure where each package has its own configuration and source files. PSR requires individual configuration files for each package.

```plaintext
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

```