From 40f9e709de71e586fb450cd9f6db0da76da8d0eb Mon Sep 17 00:00:00 2001 From: Eike Haller <58111764+eksrha@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:58:03 +0100 Subject: [PATCH 1/2] docs(relctl): document the breaking_markers option --- docs/relctl/usage.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/relctl/usage.md b/docs/relctl/usage.md index df2a68c..4c53cc6 100644 --- a/docs/relctl/usage.md +++ b/docs/relctl/usage.md @@ -17,6 +17,38 @@ relctl release create --merge-sha Reads the merged PR's branch name, computes the next SemVer version, and creates a draft GitHub Release. +### Breaking-change markers (SemVer) + +In the SemVer scheme the branch prefix (for example `fix/` or `feature/`) decides the bump. A pull request that carries a Conventional Commits breaking-change marker can therefore be released as a patch or minor version by accident. The `breaking_markers` option in `.relctl.yaml` decides what relctl does about it: + +```yaml +# .relctl.yaml +breaking_markers: warn # major | warn | off +``` + +| Value | Behaviour | +| --- | --- | +| `warn` (default) | Keeps the bump. Warns in the log, in the GitHub Actions run summary and at the top of the release notes. | +| `major` | Raises the bump to major. | +| `off` | Ignores markers (the behaviour before 2.12.0). | + +**The default changes to `major` in 3.0.0.** Set `breaking_markers: major` to get that behaviour now. + +What counts as a marker: + +- a `type!:` or `type(scope)!:` header, for example `fix!: drop the old API` or `fix(forms)!: rename a field`, in the pull request title or in a subject of one of the pull request's own commits +- a `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer at the start of a line, followed by `: ` (colon and space), in the pull request title, description or one of its own commits + +relctl does not look at markers inside fenced code blocks, HTML comments or `
` blocks. It reads only the pull request's own commits, not the merge commit and not commits of the target branch. The description of pull requests from `renovate/` and `dependabot/` branches is ignored, because it quotes upstream release notes; their title and commits are still checked. + +A marker never lowers the bump. The bump is decided in this order: + +1. The branch prefix gives the base level. +2. A `relctl_patch_level` comment replaces it. +3. A breaking-change marker then raises the level to major (`major`) or only warns (`warn`). If the level is already major, nothing changes. + +If the commits of a pull request cannot be read completely, `breaking_markers: major` fails the release, so that a breaking change cannot slip through as a patch. `warn` continues and checks only the title and description. + ### CalVer ```bash From 7062bc2cbe8bc9c98457f3e244cf30ac4fdaa5e9 Mon Sep 17 00:00:00 2001 From: Eike Haller <58111764+eksrha@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:01:47 +0100 Subject: [PATCH 2/2] docs(relctl): fix marker rules, add breaking_markers to configuration, document recreated forward result --- docs/relctl/configuration.md | 5 +++++ docs/relctl/release-flows.md | 3 ++- docs/relctl/usage.md | 4 +++- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/relctl/configuration.md b/docs/relctl/configuration.md index a04ab5a..49fc590 100644 --- a/docs/relctl/configuration.md +++ b/docs/relctl/configuration.md @@ -19,6 +19,10 @@ changelog_file: CHANGELOG.md production_branch: main # receives the releases development_branch: dev # work lands here first +# semver scheme: what a breaking-change marker (`fix!:`, `BREAKING CHANGE: `) does. +# warn (default) | major | off. The default becomes major in 3.0.0. +breaking_markers: warn + # A prefix in front of every tag and release: "v" gives v1.2.3. tag_prefix: v @@ -40,6 +44,7 @@ components: | `production_branch` | `main` | `release forward` (the branch that is brought back into the development branch) | | `development_branch` | the default branch of the repository | `release forward` | | `default_branch` | — | former name of `production_branch`; still read and used if `production_branch` is not set | +| `breaking_markers` | `warn` | `release create`, `pr info` (SemVer scheme): `major`, `warn` or `off` — see [Breaking-change markers](./usage.md#breaking-change-markers-semver). The default becomes `major` in 3.0.0. | | `tag_prefix` | none | every command that reads or writes tags and releases — see [Tag prefix](#tag-prefix) | | `components` | none | `--component` on `release create`, `release publish`, `release gate`, `pr info`, and `release changed` — see [Components](#components) | diff --git a/docs/relctl/release-flows.md b/docs/relctl/release-flows.md index 11809b1..0c24175 100644 --- a/docs/relctl/release-flows.md +++ b/docs/relctl/release-flows.md @@ -148,9 +148,10 @@ relctl release forward --from main --to dev --dry-run - If `dev` already contains `main`, nothing happens. - If `dev` is an ancestor of `main`, `dev` is **fast-forwarded**. This needs a token that may push to `dev`; with branch rules that require pull requests only a bypass actor can. - Otherwise (the branches diverged, or the push is not allowed) a **pull request** `main` → `dev` is opened. **Merge it with a merge commit, do not squash it**: a squash creates a commit that `main` never had and causes conflicts with the next release. +- If `dev` does not exist (for example because the repository deletes head branches on merge and the release pull request came from `dev`), it is **recreated** at the head of `main`. This only happens for the `development_branch` from `.relctl.yaml`, never for a name given with `--to`, and needs a token that may create branches. With `--dry-run` nothing is created; the result is `recreated` and the output says `Would recreate`. - It is idempotent: a second run does not open a second pull request. -The branches come from [`.relctl.yaml`](./configuration.md) (`production_branch`, `development_branch`). The result is exported as `RELCTL_FORWARD_RESULT` (`nothing`, `fast-forward`, `pull-request`) and `RELCTL_FORWARD_PR`. +The branches come from [`.relctl.yaml`](./configuration.md) (`production_branch`, `development_branch`). The result is exported as `RELCTL_FORWARD_RESULT` (`nothing`, `fast-forward`, `pull-request`, `recreated`) and `RELCTL_FORWARD_PR`. ## Tag prefix diff --git a/docs/relctl/usage.md b/docs/relctl/usage.md index 4c53cc6..2b1a565 100644 --- a/docs/relctl/usage.md +++ b/docs/relctl/usage.md @@ -37,7 +37,7 @@ breaking_markers: warn # major | warn | off What counts as a marker: - a `type!:` or `type(scope)!:` header, for example `fix!: drop the old API` or `fix(forms)!: rename a field`, in the pull request title or in a subject of one of the pull request's own commits -- a `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer at the start of a line, followed by `: ` (colon and space), in the pull request title, description or one of its own commits +- a `BREAKING CHANGE: ` or `BREAKING-CHANGE: ` footer (upper case, colon and space) at the very start of a line, not indented, in the pull request description or in one of its own commits. A footer in the pull request title does not count. relctl does not look at markers inside fenced code blocks, HTML comments or `
` blocks. It reads only the pull request's own commits, not the merge commit and not commits of the target branch. The description of pull requests from `renovate/` and `dependabot/` branches is ignored, because it quotes upstream release notes; their title and commits are still checked. @@ -49,6 +49,8 @@ A marker never lowers the bump. The bump is decided in this order: If the commits of a pull request cannot be read completely, `breaking_markers: major` fails the release, so that a breaking change cannot slip through as a patch. `warn` continues and checks only the title and description. +To release a breaking change as a major version when the markers are not enough, use a `major/` branch prefix, a `relctl_patch_level: major` comment, or `relctl_version_override`. + ### CalVer ```bash