|
| 1 | +--- |
| 2 | +id: release-notes |
| 3 | +title: Release notes |
| 4 | +description: How to write the changeset that becomes a changelog entry — voice, bump type, worked examples. |
| 5 | +--- |
| 6 | + |
| 7 | +# Release-notes style guide |
| 8 | + |
| 9 | +User-facing release notes come from [Changesets](https://github.com/changesets/changesets). One changeset per user-visible PR; its summary becomes the changelog entry verbatim. |
| 10 | + |
| 11 | +Three release lines carry changesets: `@tumaet/apollon` on npm, and `@tumaet/webapp` + `@tumaet/server` as paired `ghcr.io` Docker images. The VS Code extension, the docs site, and the webview sub-packages are excluded in `.changeset/config.json#ignore` — they have their own (or no) release flow, and without the exclusion a routine library bump would version them too, since every package depends on `@tumaet/apollon` via `workspace:*`. |
| 12 | + |
| 13 | +:::note |
| 14 | +Changesets are the per-PR convention now; the pipeline that consumes them (`changeset version` → `CHANGELOG.md` → release) lands in a follow-up. Until then, write the changeset so the backlog is ready — and note that the existing `CHANGELOG.md` files are hand-maintained, since the tool does not yet regenerate them. See [Releases](/contributor/deployment/npm-publishing). |
| 15 | +::: |
| 16 | + |
| 17 | +## When do you need one? |
| 18 | + |
| 19 | +Add a changeset whenever a **user, embedder, or operator would notice** a change to `@tumaet/apollon`, `@tumaet/webapp`, or `@tumaet/server` — a new feature, a bug fix, a changed API, or a new deployment step. |
| 20 | + |
| 21 | +Skip it when nothing downstream is affected: docs, CI, tests, refactors, and formatting — plus anything touching only the VS Code extension or the docs site (both excluded above). When unsure, add one; an extra changelog line beats a silent gap. The advisory **Verify changesets** check on each PR reminds you. |
| 22 | + |
| 23 | +## What you write per PR |
| 24 | + |
| 25 | +```sh |
| 26 | +pnpm changeset |
| 27 | +``` |
| 28 | + |
| 29 | +Pick the packages and bump type when prompted; **the summary you type becomes the changelog entry, verbatim.** Edit `.changeset/<name>.md` afterwards and commit it with your PR. |
| 30 | + |
| 31 | +## Writing the summary |
| 32 | + |
| 33 | +**Write for the user, not the engineer.** Lead with what the user can now do (or, for fixes, the symptom they would have seen). Implementation language — internal types, hook names, file paths — stays in the PR description. |
| 34 | + |
| 35 | +| Don't | Do | |
| 36 | +| --------------------------------------------------------------- | ----------------------------------------------------------------- | |
| 37 | +| `add useExportAsPPTX hook with lazy-loaded pptxgenjs` | `Export diagrams as animatable PowerPoint slides.` | |
| 38 | +| `Reset isLoading on effect re-entry and thread AbortController` | `Sharing a diagram twice no longer leaves a blank canvas behind.` | |
| 39 | + |
| 40 | +For an embedder-facing library change, name the API and describe the contract instead — see [Per-package conventions](#per-package-conventions) below. |
| 41 | + |
| 42 | +For **breaking changes**, mark the changeset `major` and link a migration runbook — the GitHub Release body, or [`ops/operations.md`](https://github.com/ls1intum/Apollon/blob/main/ops/operations.md). |
| 43 | + |
| 44 | +## Per-package conventions |
| 45 | + |
| 46 | +| Package | Audience | Voice | |
| 47 | +| -------------------------------------------- | --------------------- | ----------------------------------------------------- | |
| 48 | +| `@tumaet/apollon` | embedders | name the API; describe the contract | |
| 49 | +| `@tumaet/webapp` + `@tumaet/server` (paired) | end users + operators | what the user can do; for operators, link the runbook | |
| 50 | + |
| 51 | +## Picking the bump type |
| 52 | + |
| 53 | +- **patch** — bug fixes, internal-only changes consumers adopt without code changes. |
| 54 | +- **minor** — new backwards-compatible functionality (new options, exports, optional behaviour). |
| 55 | +- **major** — breaks an existing caller, deployment, or storage layout. Must link a migration runbook. |
| 56 | + |
| 57 | +## Worked examples |
| 58 | + |
| 59 | +A standalone-only fix (`#683`, in v4.4.1): |
| 60 | + |
| 61 | +```markdown |
| 62 | +--- |
| 63 | +"@tumaet/webapp": patch |
| 64 | +--- |
| 65 | + |
| 66 | +Sharing a diagram a second time, or starting a new diagram during a collaboration session, no longer leaves a blank canvas behind. |
| 67 | +``` |
| 68 | + |
| 69 | +A library API addition (`#657`, in v4.4.0): |
| 70 | + |
| 71 | +```markdown |
| 72 | +--- |
| 73 | +"@tumaet/apollon": minor |
| 74 | +--- |
| 75 | + |
| 76 | +Adds editor primitives for hosting a version-history UX on top of the live Yjs document — preview mode, programmatic readonly, fit-to-view, and full-state broadcast. |
| 77 | +``` |
| 78 | + |
| 79 | +A change that spans the webapp and the library lands as two changesets in the same PR — one per audience, each in its track's voice. |
| 80 | + |
| 81 | +## CHANGELOG.md and the GitHub Release body |
| 82 | + |
| 83 | +`CHANGELOG.md` is the per-version bullet log Changesets writes; once the consuming pipeline lands it is tool-owned, not edited by hand. The **GitHub Release body** carries the human-curated lede and highlights (screenshots, video). |
| 84 | + |
| 85 | +You write only the changeset body (the markdown after the frontmatter). At `changeset version` time, `@changesets/changelog-github` prepends the PR link, commit link, and `Thanks @author!` automatically. The backfilled v4.4.0 / v4.4.1 entries omit the commit-SHA link — those commits predate Changesets; new releases include it. |
0 commit comments