chore: adopt changesets for releases and publish a compatibility policy (#1392)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/README.md

@@ -0,0 +1,42 @@
+# Changesets
+
+A **changeset** here is a release note: a `.changeset/*.md` file that becomes `CHANGELOG.md` and drives
+the version bump. (Not a Liquibase `<changeSet>` — a schema change needs both.)
+
+Every PR that changes shipped code (anything under `server/`, `webapp/`, or `docker/` except tests and in-tree docs) ships one; CI (`verify-changesets`) enforces it.
+
+```bash
+pnpm changeset          # write one (pick the bump, describe the change)
+pnpm changeset --empty  # no user-facing effect — then write why in the file body (non-interactive)
+```
+
+The summary lands in the changelog **verbatim**, in the operator/user's voice — lead with what they can now
+do, or the symptom a fix removes. No class/hook/file names. No agent-attribution trailers. One changeset per
+user-visible change; unsure whether it's visible? Add one — a reviewer can delete it, a missing note can't.
+
+No TTY (agents, CI)? `pnpm changeset` is interactive — instead write `.changeset/<slug>.md` by hand in the
+format shown below. That is the one sanctioned hand-write; never touch `CHANGELOG.md` directly.
+
+**Bump = the operator's upgrade cost:**
+
+| Bump | Operator upgrade | Examples |
+| --- | --- | --- |
+| `patch` | no action | bug fix, internal change, additive auto-applied migration |
+| `minor` | no action | new capability; note any new *optional* env var / flag in the summary |
+| `major` | must act first | required new env var, removed/renamed config, destructive/manual migration, dropped API — state the action + update `MIGRATION.md` |
+
+**Pre-1.0 (now): never pick `major`** — it would cut 1.0.0; CI rejects it. Breaking changes ride in `minor`
+instead, so a pre-1.0 `minor` is *not* guaranteed zero-action: if the operator must act, say so
+(`**Operators:** …`) and update `MIGRATION.md` exactly as a `major` would.
+
+Example (a migration-bearing fix):
+
+```md
+---
+"hephaestus": minor
+---
+
+Fixes duplicate leaderboard entries after a team rename.
+```
+
+Full flow and rules: [release management guide](https://ls1intum.github.io/Hephaestus/contributor/release-management).

.changeset/changelog.cjs

@@ -0,0 +1,8 @@
+// Changelog entries are the summary verbatim — no commit hashes, PR links, or
+// attribution (the default formatter prefixes a commit hash; changelog-github
+// adds PR links + "Thanks @user!"). Operators read this file; git metadata
+// lives in git.
+module.exports = {
+  getReleaseLine: async (changeset) => `- ${changeset.summary.trim().split("\n").join("\n  ")}`,
+  getDependencyReleaseLine: async () => "",
+};

.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "./changelog.cjs",
+  "commit": false,
+  "baseBranch": "main",
+  "privatePackages": {
+    "version": true,
+    "tag": false
+  },
+  "ignore": [
+    "webapp",
+    "docs"
+  ]
+}

.changeset/release-pin-verification-identity.md

@@ -0,0 +1,6 @@
+---
+"hephaestus": patch
+---
+
+Fixes a release deploy that never started: the signature check on the pinned agent image rejected every
+valid release, so the application server stayed down.

.claude/skills/land-pr/SKILL.md

@@ -7,8 +7,8 @@ disable-model-invocation: true
 allowed-tools:
   - Bash(gh *)
   - Bash(git *)
-  - Bash(npm *)
-  - Bash(mvn *)
+  - Bash(pnpm *)
+  - Bash(./mvnw *)
   - Read
   - Grep
   - Glob
@@ -112,7 +112,19 @@ pnpm run check
 
 Both must pass.
 
-## 9. Create Branch (if on main)
+## 9. Changeset (required for shipped-code changes)
+
+If this PR changes `server/`, `webapp/`, or `docker/`, it must carry a changeset or CI (`verify-changesets`) fails:
+
+```bash
+pnpm changeset          # user-facing change: pick the bump, describe it for operators
+pnpm changeset --empty  # no user-facing effect (refactor/test/docs-only)
+```
+
+Pre-1.0: never pick `major`. Stage the generated `.changeset/*.md` before committing. `pnpm changeset` is
+interactive — with no TTY, write `.changeset/<slug>.md` by hand (`.changeset/README.md` shows the format).
+
+## 10. Create Branch (if on main)
 
 ```bash
 git branch --show-current
@@ -126,7 +138,7 @@ git checkout -b <type>/<description>
 
 Types: `feat`, `fix`, `docs`, `refactor`, `test`, `ci`, `chore`
 
-## 10. Commit
+## 11. Commit
 
 ```bash
 git add -A
@@ -135,23 +147,23 @@ git commit -m "<type>(<scope>): <description>"
 
 **Scopes:**
 
-- Service: `webapp`, `server`, `ai`, `webhooks`, `docs`
-- Infra (no release): `ci`, `config`, `deps`, `deps-dev`, `docker`, `scripts`, `security`, `db`, `no-release`
-- Feature: `gitprovider`, `leaderboard`, `mentor`, `notifications`, `profile`, `teams`, `workspace`
+- Service: `webapp`, `server`, `docs`
+- Infra: `ci`, `config`, `deps`, `deps-dev`, `docker`, `scripts`, `security`, `db`, `release`
+- Feature: `auth`, `integration`, `scm`, `leaderboard`, `mentor`, `notifications`, `profile`, `teams`, `workspace`
 
-## 11. Push
+## 12. Push
 
 ```bash
 git push -u origin HEAD
 ```
 
-## 12. Check if PR Exists
+## 13. Check if PR Exists
 
 ```bash
 PAGER=cat gh pr view --json number,url 2>/dev/null && echo "PR exists - skip creation" || echo "No PR - create one"
 ```
 
-## 13. Create PR (if needed)
+## 14. Create PR (if needed)
 
 Skip if step 13 showed "PR exists".
 
@@ -167,7 +179,7 @@ PAGER=cat gh pr create --base main \
 <steps to verify, or 'CI covers this'>"
 ```
 
-## 14. Verify
+## 15. Verify
 
 ```bash
 PAGER=cat gh pr view --json url,title -q '"PR: \(.title)\nURL: \(.url)"'

.github/CODEOWNERS

@@ -6,7 +6,9 @@
 
 # Release management and CI/CD
 .github/                         @ls1intum/hephaestus-maintainers
-.releaserc                       @ls1intum/hephaestus-maintainers
+.changeset/                      @ls1intum/hephaestus-maintainers
+CHANGELOG.md                     @ls1intum/hephaestus-maintainers
+commitlint.config.mjs            @ls1intum/hephaestus-maintainers
 renovate.json                    @ls1intum/hephaestus-maintainers
 
 # Application Server (Java/Spring)

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,15 +2,15 @@
 TITLE FORMAT (required):
   <type>(<scope>): <description>
 
-  Types: feat | fix | docs | refactor | test | ci | perf | revert
-  Scopes (Service): webapp | server | ai | docs
-  Scopes (Infra - NO RELEASE): ci | config | deps | deps-dev | docker | scripts | security | db | no-release
-  Scopes (Feature): integration | scm | leaderboard | mentor | notifications | profile | teams | workspace
+  Types: feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert
+  Scopes (Service): webapp | server | docs
+  Scopes (Infra): ci | config | deps | deps-dev | docker | scripts | security | db | release
+  Scopes (Feature): auth | integration | scm | leaderboard | mentor | notifications | profile | teams | workspace
 
-  Breaking: Add ! before colon (feat!: or feat(scope)!:)
+  Breaking changes: carried by the changeset (pre-1.0 = minor + MIGRATION.md), not the title.
 
   ✓ Good: feat(leaderboard): add weekly ranking filter
-  ✓ Good (No Release): fix(ci): update workflow configuration
+  ✓ Good: fix(ci): update workflow configuration
   ✗ Bad:  Added weekly ranking filter to leaderboard
 
 BEFORE PUSHING:
@@ -34,6 +34,13 @@ Fixes # <!-- Link issue if applicable, or delete this line -->
 
 <!-- Manual steps to verify, OR "CI covers this" for config/docs changes. -->
 
+## Checklist
+
+<!-- Only what CI can't check for you. Changeset presence is enforced by `verify-changesets`. -->
+
+- [ ] My changeset summary reads as an operator/user-facing note (it becomes the changelog entry) — see `.changeset/README.md`
+- [ ] If the operator must act on this change (new required env var, manual migration step), the changeset summary says how (`**Operators:** …`) and `MIGRATION.md` is updated
+
 ## Screenshots
 
 <!-- For UI changes. Delete section if not applicable. -->

.github/labeler.yml

@@ -1,5 +1,5 @@
-# Auto-labeler configuration for PRs
-# Labels assigned here are used by .github/release.yml for categorized release notes
+# Auto-labeler configuration for PRs (triage only — release notes come from
+# changesets, not labels; see docs/contributor/release-management.mdx)
 
 documentation:
   - changed-files:

.github/prompts/land-pr.prompt.md

@@ -98,7 +98,19 @@ pnpm run check
 
 Both must pass.
 
-## 9. Create Branch (if on main)
+## 9. Changeset (required for shipped-code changes)
+
+If this PR changes `server/`, `webapp/`, or `docker/`, it must carry a changeset or CI (`verify-changesets`) fails:
+
+```bash
+pnpm changeset          # user-facing change: pick the bump, describe it for operators
+pnpm changeset --empty  # no user-facing effect (refactor/test/docs-only)
+```
+
+Pre-1.0: never pick `major`. Stage the generated `.changeset/*.md` before committing. `pnpm changeset` is
+interactive — with no TTY, write `.changeset/<slug>.md` by hand (`.changeset/README.md` shows the format).
+
+## 10. Create Branch (if on main)
 
 ```bash
 git branch --show-current
@@ -112,7 +124,7 @@ git checkout -b <type>/<description>
 
 Types: `feat`, `fix`, `docs`, `refactor`, `test`, `ci`, `chore`
 
-## 10. Commit
+## 11. Commit
 
 ```bash
 git add -A
@@ -122,22 +134,22 @@ git commit -m "<type>(<scope>): <description>"
 **Scopes:**
 
 - Service: `webapp`, `server`, `docs`
-- Infra (no release): `ci`, `config`, `deps`, `deps-dev`, `docker`, `scripts`, `security`, `db`, `no-release`
-- Feature: `integration`, `scm`, `leaderboard`, `mentor`, `notifications`, `profile`, `teams`, `workspace`
+- Infra: `ci`, `config`, `deps`, `deps-dev`, `docker`, `scripts`, `security`, `db`, `release`
+- Feature: `auth`, `integration`, `scm`, `leaderboard`, `mentor`, `notifications`, `profile`, `teams`, `workspace`
 
-## 11. Push
+## 12. Push
 
 ```bash
 git push -u origin HEAD
 ```
 
-## 12. Check if PR Exists
+## 13. Check if PR Exists
 
 ```bash
 PAGER=cat gh pr view --json number,url 2>/dev/null && echo "PR exists - skip creation" || echo "No PR - create one"
 ```
 
-## 13. Create PR (if needed)
+## 14. Create PR (if needed)
 
 Skip if step 13 showed "PR exists".
 
@@ -153,7 +165,7 @@ PAGER=cat gh pr create --base main \
 <steps to verify, or 'CI covers this'>"
 ```
 
-## 14. Verify
+## 15. Verify
 
 ```bash
 PAGER=cat gh pr view --json url,title -q '"PR: \(.title)\nURL: \(.url)"'