Configuration reference

Every fork addition lives under [tool.semantic_release.bsr] in the same config file upstream already reads (pyproject.toml, setup.cfg, releaserc.toml, …). The two guards are on by default; everything else is off by default, so an untouched config behaves exactly like upstream.

Every diagnostic below writes to stderr, so semantic-release version keeps printing only the version number on stdout and stays safe to capture in a shell substitution.

Release diagnostics (explain)

When next_version() recomputes a version that already exists, upstream always prints the same line – No release will be made, X has already been released! – no matter what actually happened. The usual real cause is that no commit since the last release qualified for a bump, a fact upstream only logs at INFO and never surfaces.

[tool.semantic_release.bsr]
schema_version = 1
explain = true

With explain on, that line is replaced by the classified cause:

• NO_QUALIFYING_COMMITS – commits were scanned, none were releasable (no feat / fix / breaking-change commits). This is the case upstream misattributes.

• ALREADY_RELEASED_NOOP – the current tip is already tagged; a genuine re-dispatch with nothing new to release.

• ORPHAN – the version recomputes to an already-released but unreachable tag, which is the silent-release-freeze the orphan-tag guard exists for.

On a run that does release, it also prints a “why this bump” line – the bump level, the per-commit-type breakdown behind it, the base version, and how many commits were scanned:

better-semantic-release explain: minor bump from 2 feat, 3 fix commit(s) since 1.4.0 (5 commit(s) scanned).

Actionable error messages (actionable_errors)

Upstream surfaces its most-cited failures as a bare str(exc) with no framing, and leaves two of them uncaught entirely (raw traceback).

[tool.semantic_release.bsr]
schema_version = 1
actionable_errors = true

With the flag on, these categories are rewritten as “what happened / why / how to fix”:

• PRERELEASE BUMP MISMATCH – a prerelease-level bump was requested but the base version is not already a prerelease.

• INVALID CONFIGURATION – each failing key is listed as [tool.semantic_release.<key>]: <reason> instead of a raw pydantic dump.

• PARSER LOAD FAILED – lists the valid parser names (angular, conventional, conventional-monorepo, emoji, scipy) and the module:ClassName form.

• GIT REMOTE NOT FOUND – shows both fixes (add the remote, or point [tool.semantic_release.remote] at an existing one).

• TAG_FORMAT MISMATCH – a note emitted when the repository has git tags but none match the configured tag_format, which otherwise makes upstream silently treat the repository as having no prior releases and start over from the initial version.

Monorepo path filtering

Upstream’s directory: input only selects where config (pyproject.toml, tag_format, …) is read from – it does not filter which commits are analyzed, so in a monorepo a commit touching an unrelated component still bumps this component’s version and shows up in its changelog. This is opt-in and off by default (drop-in): enable it under [tool.semantic_release.bsr].

[tool.semantic_release.bsr]
schema_version = 1
path_filter = true
paths = ["apps/api", "libs/shared"]

• path_filter (default false) – master switch. When false the fork behaves identically to upstream: every commit since the last release counts, regardless of which paths it touched.

• paths (default [], repository-root-relative) – one or more path prefixes; a commit only counts toward this component if it changed a file under one of them. Multiple entries are OR’d together, which supports a component that also depends on shared code (e.g. ["apps/api", "libs/shared"]).

• When path_filter is true and paths is left empty, it defaults to the run directory (the GitHub Action’s directory: input) made relative to the repository root.

Monorepo release-plan summary (summary)

Neither upstream’s conventional-monorepo parser nor the path filter above tells you what a release run would do across a monorepo’s components before it does it.

[tool.semantic_release.bsr]
schema_version = 1
summary = true
components = [
    { name = "api", paths = ["apps/api", "libs/shared"] },
    { name = "web", paths = ["apps/web"] },
]

Each row is computed with the same next_version() upstream uses for the real release, scoped to that component’s paths:

better-semantic-release summary: monorepo release plan
component  would-release  level       commits  sample paths                            version
---------  -------------  ----------  -------  --------------------------------------  -------
api        yes            MINOR       4        apps/api/main.go, apps/api/handlers.go  1.4.0
web        no             NO_RELEASE  0        -                                       1.2.3

• The report is read-only – nothing is committed, tagged, pushed or persisted, and it renders before any persistence step, so it appears whether or not the run itself ends up releasing.

• components is optional. Left empty, you get a single row built from bsr.paths and named after [project].name – so a non-monorepo project still gets a plan instead of an empty report.

• A component with no paths means “the whole repository” (the filter is a passthrough), not “nothing”.

Stable release notes aggregation (stable_notes_aggregate)

Upstream buckets every commit under the nearest tag walking back from HEAD. Once a line has rc/beta tags, those prereleases have already “consumed” the commits, so finalizing the stable version with no brand-new commits of its own produces a release section that is empty – or fragmented across the prerelease tags instead of one grouped vX.Y.Z section. This is the most-cited changelog complaint upstream (issues #555, #817, #1377, #1440) and is won’t-fix there.

[tool.semantic_release.bsr]
schema_version = 1
stable_notes_aggregate = true
stable_notes_scope = "line"  # or "since_stable"

With this on, the notes of every intervening prerelease are merged into the stable release that finalizes them, de-duplicated by commit sha, covering both the written changelog and the VCS release notes. It only ever runs for a genuine stable finalize; a prerelease run is untouched.

• scope = "line" (default) – fold in prereleases sharing the stable version’s major.minor.patch.

• scope = "since_stable" – walk back from the new version and fold in every intervening prerelease regardless of line, stopping at (and excluding) the previous stable tag. This differs from "line" when a prerelease track was abandoned mid-line: if a forced bump moved 0.2.0-beta.1 to 1.0.0-beta.1, "line" picks up only 1.0.0-beta.1 while "since_stable" also folds in the abandoned 0.2.0-beta.1.

Machine-readable output (--format json)

Everything above is reported as English prose. That is the right default for a human reading a CI log, and the wrong one for the CI job itself: to answer “did this release, and why not”, a script has to either match on message text or re-derive the answer from git. --format json is the exit for the data the tool already computed.

It is a CLI flag, not a [tool.semantic_release.bsr] key – it describes how one invocation reports, not how the repository releases, so it does not belong in a committed config that every other run would inherit.

$ semantic-release version --print --format json
{
  "schema_version": 1,
  "released": false,
  "version": "1.3.0",
  "tag": "v1.3.0",
  "is_prerelease": false,
  "previous_version": "1.2.3",
  "reason": null,
  "commit_count": 7,
  "level_bump": "minor",
  "type_counts": { "features": 4, "bug fixes": 3 },
  "components": []
}

Three guarantees, with no exceptions to memorize:

• stdout carries exactly one JSON document and nothing else – for every way the command can end, including --print, --print-last-released, a run that makes no release, and the failure exits. A caller can run json.loads over the whole stream without special-casing any path. (--print-last-released has no bare line to print in this mode; its datum travels in previous_version.)

• Human output is unchanged without the flag – byte-for-byte, asserted directly by the test suite. Anything parsing today’s --print line is unaffected.

• The decision data does not depend on the diagnostics being on. explain controls what is narrated; the document reports reason, level_bump and type_counts whether or not it is set. (components is the one exception: it mirrors the summary report, so it is [] unless summary is configured.)

The full field reference for both documents is in docs/api/commands.rst, under the --format option of each command. schema_version is 1; it exists so a consumer can pin behavior if fields are ever added or renamed.