Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

ci: define version bump rules and add the improvement commit type (#106)

Croffa49c8ef3b119
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 9f554c9d..67e17332 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,9 @@
-<!-- Title format: type(scope): summary, e.g. feat(api): add issue templates -->
+<!--
+Title format: type(scope): summary, e.g. feat(api): add issue templates
+The type picks the released version: feat is a new capability (minor),
+improvement is a visible change to something that exists (patch), fix is wrong
+behaviour made right (patch). See CONTRIBUTING.md.
+-->
## What
diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml
index f7a0741b..2e621455 100644
--- a/.github/workflows/pr-title.yml
+++ b/.github/workflows/pr-title.yml
@@ -23,6 +23,7 @@ jobs:
# PULL_REQUEST_TEMPLATE.md.
types: |
feat
+ improvement
fix
docs
refactor
diff --git a/AGENTS.md b/AGENTS.md
index dec02b6e..1be3f688 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -168,13 +168,37 @@ Images are not published to a registry: every deploy builds from source
Versioning is automated by release-please (`release.yml`). It reads the
Conventional Commit subjects that land on `main` and keeps an open release PR
-that accumulates the next version and `CHANGELOG.md`. `feat:` bumps the minor,
-`fix:` the patch, `!` (e.g. `feat!:`) the major — but while the version is
-`0.x`, a breaking change bumps the minor, not the major. Merging the release PR
+that accumulates the next version and `CHANGELOG.md`. Merging the release PR
tags the commit and publishes the GitHub Release. PR titles are squash-merged
into `main`, so the PR title is the commit subject release-please reads; it must
be a valid Conventional Commit (enforced by `pr-title.yml`).
+The type in the subject picks the version bump, so pick it by what the change
+gives the user, not by how much code it touches:
+
+- **`feat:` — minor.** A capability that did not exist: a new entity, page,
+ integration, or a setting that unlocks behaviour. Reserve it for what would
+ earn a "Highlights" entry in the release notes.
+- **`improvement:` — patch.** A visible change to something that already exists:
+ a redesign, a reworked layout, a theme, an interaction that got better. Not a
+ bug fix, not a new capability.
+- **`fix:` — patch.** Behaviour that was wrong is now right.
+- **everything else (`perf`, `refactor`, `docs`, `build`, `ci`, `test`,
+ `chore`, `revert`) — patch.**
+
+The major is never automatic. While the version is `0.x`, `!` (e.g. `feat!:`)
+bumps the minor (`bump-minor-pre-major`), and `1.0.0` is cut deliberately with a
+`Release-As: 1.0.0` footer in the squash commit body. That footer overrides the
+computed version for any release; release-please reads it before the versioning
+strategy runs. After `1.0.0`, `!` bumps the major on its own.
+
+`improvement` is not in the Conventional Commits standard list. release-please
+bumps the patch for any type it does not recognise, and the entry reaches the
+changelog because `changelog-sections` in `release-please-config.json` maps it to
+an "Improvements" section — a type missing from that list is dropped from the
+notes. The list of types a PR title may use lives in `pr-title.yml`; the two
+have to stay in sync.
+
The scope is the name of one app or package (`api`, `web`, `worker`, `bot`, `db`,
`auth`, …). A change spanning several of them carries no scope.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b7db49b5..cc482239 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -73,7 +73,19 @@ run `bun run auth:generate` first, then generate the migration.
2. Keep the change focused. One concern per pull request.
3. Title follows [Conventional Commits](https://www.conventionalcommits.org/):
`feat(web): add issue templates`, `fix(api): reject empty label names`,
- `docs: ...`, `refactor: ...`, `chore: ...`.
+ `improvement(web): ...`, `docs: ...`, `refactor: ...`, `chore: ...`.
+ The title picks the released version, so choose the type by what the change
+ gives the user:
+
+ - `feat` — a capability that did not exist. Bumps the minor.
+ - `improvement` — a visible change to something that already exists: a
+ redesign, a reworked layout, a better interaction. Bumps the patch.
+ - `fix` — behaviour that was wrong is now right. Bumps the patch.
+ - `perf`, `refactor`, `docs`, `build`, `ci`, `test`, `chore`, `revert` — bump
+ the patch.
+
+ The full list of accepted types is in `.github/workflows/pr-title.yml`.
+
4. Before pushing, make sure these pass:
```bash
diff --git a/release-please-config.json b/release-please-config.json
index 52620bf0..0c6ffafe 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -10,6 +10,7 @@
"changelog-path": "CHANGELOG.md",
"changelog-sections": [
{ "type": "feat", "section": "Features" },
+ { "type": "improvement", "section": "Improvements" },
{ "type": "fix", "section": "Bug Fixes" },
{ "type": "perf", "section": "Performance" },
{ "type": "refactor", "section": "Refactoring" },