Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/relctl/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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) |

Expand Down
3 changes: 2 additions & 1 deletion docs/relctl/release-flows.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
34 changes: 34 additions & 0 deletions docs/relctl/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,40 @@ relctl release create --merge-sha <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 (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 `<details>` 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.

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
Expand Down
Loading