From 32d2f02d273ae4b6cdf3baede02392532ee5266d Mon Sep 17 00:00:00 2001 From: Eric Allam Date: Fri, 14 Aug 2026 11:51:18 +0100 Subject: [PATCH] docs: clarify when changesets and server-changes files are needed Reframe changesets and .server-changes notes as user-facing release notes rather than a catalog of every change. The test is whether a user or customer would care, not whether a public package or server app was touched. Call out the skip cases: internal/admin-only changes, refactors, chores, performance tuning with no user-visible effect, and public packages that are not consumed independently. --- .claude/REVIEW.md | 4 ++-- .claude/rules/server-apps.md | 4 ++-- .server-changes/README.md | 8 +++++--- AGENTS.md | 20 +++++++++++++++++--- CHANGESETS.md | 16 ++++++++++------ CONTRIBUTING.md | 12 ++++++------ 6 files changed, 42 insertions(+), 22 deletions(-) diff --git a/.claude/REVIEW.md b/.claude/REVIEW.md index 3bf89ff193..b9438c08af 100644 --- a/.claude/REVIEW.md +++ b/.claude/REVIEW.md @@ -56,8 +56,8 @@ Every PR gets a performance pass — not just the ones that look perf-sensitive. ## Always check - **Tests use testcontainers, not mocks.** Vitest with `redisTest` / `postgresTest` / `containerTest` from `@internal/testcontainers`. Any new `vi.mock(...)` on Redis, Postgres, BullMQ, or other infra is wrong here — 🔴 if added in production-path tests, 🟡 if isolated unit test. -- **Public-package changes have a changeset.** `pnpm run changeset:add` produces `.changeset/*.md`. Required for any edit under `packages/*`. Missing → 🟡; missing on a breaking change → 🔴. -- **Server-only changes have `.server-changes/*.md`.** Required for `apps/webapp/`, `apps/supervisor/` edits with no public-package change. Body should be 1-2 sentences (it has to fit as one bullet in a future changelog). Missing → 🟡. +- **User-facing public-package changes have a changeset.** `pnpm run changeset:add` produces `.changeset/*.md`. Changesets are user-facing release notes, not a catalog of every change: required when a `packages/*` or `integrations/*` change is something a user would notice or act on, skipped for internal-only changes, refactors, chores, and packages not consumed independently (e.g. `@trigger.dev/redis-worker`). Missing on a user-facing change → 🟡; missing on a breaking change → 🔴. Do not flag a missing note when the change is not user-facing. +- **User-facing server-only changes have `.server-changes/*.md`.** Required for user-facing `apps/webapp/`, `apps/supervisor/` edits in a PR with no package or integration change that requires a changeset; skip internal-only or admin-only changes, refactors, and chores. Body should be 1-2 sentences (it has to fit as one bullet in a future changelog). Missing on a user-facing change → 🟡. - **Lua script naming.** Coexisting scripts use behavior-descriptive suffixes (`Tracked`), never `V2`. Old name must keep working until the next deploy clears it. - **RunQueue payload shape.** V2 run-queue payload's `projectId` is consumed by `workerQueueResolver` for override matching. If a PR drops it from the payload, 🔴. - **`safeSend` scope.** Defensive IPC wrappers belong on loop / interval / handler contexts, not one-shot terminal sends. If the PR adds `safeSend` to a single terminal call for consistency, 🟡 with a "remove this" suggestion. diff --git a/.claude/rules/server-apps.md b/.claude/rules/server-apps.md index 3bc4c0b2b9..cc3e6852a0 100644 --- a/.claude/rules/server-apps.md +++ b/.claude/rules/server-apps.md @@ -5,7 +5,7 @@ paths: # Server App Changes -When modifying server apps (webapp, supervisor, etc.) with **no package changes**, add a `.server-changes/` file instead of a changeset: +`.server-changes/` files are user-facing release notes, not a catalog of every change. When a user-facing server app change (webapp, supervisor, etc.) is in a PR with **no package or integration change that requires a changeset**, add a `.server-changes/` file instead of a changeset. Skip it for internal-only or admin-only changes, refactors, and chores: ```bash cat > .server-changes/descriptive-name.md << 'EOF' @@ -20,6 +20,6 @@ EOF - **area**: `webapp` | `supervisor` - **type**: `feature` | `fix` | `improvement` | `breaking` -- If the PR also touches `packages/`, just the changeset is sufficient (no `.server-changes/` needed). +- If the PR also touches `packages/` or `integrations/` and that change needs a changeset, the changeset covers it (no `.server-changes/` needed). If the package or integration change is internal and needs no changeset, still add a `.server-changes/` file for the user-facing server change. The body ships **verbatim in user-facing release notes**. Keep it to 1–2 short sentences, non-technical, written for a dashboard user: describe what changed for them, never the implementation (no header names, endpoints, middleware, storage mechanisms, internal tools). See `.server-changes/README.md` for full guidance. diff --git a/.server-changes/README.md b/.server-changes/README.md index 12815039ac..e13ebec4a7 100644 --- a/.server-changes/README.md +++ b/.server-changes/README.md @@ -4,11 +4,13 @@ This directory tracks changes to server-only components (webapp, supervisor, etc ## When to add a file -**Server-only PRs**: If your PR only changes `apps/webapp/`, `apps/supervisor/`, or other server components (and does NOT change anything in `packages/`), add a `.server-changes/` file. +These entries are **user-facing release notes**, not a catalog of every change. The test is "would a user or customer care about this change?", not "did I touch a server app?". Add one only when a server-only change is something a user would notice, act on, or want to hear about (a feature, a bug fix they could have hit, a behavior or performance change they would feel). Skip it for internal-only or admin-only changes, refactors, test-only changes, chores, and performance tuning with no user-visible effect. Anyone who wants the exact history reads the commits. When in doubt, ask a maintainer rather than adding a note by default. -**Mixed PRs** (both packages and server): Just add a changeset as usual. No `.server-changes/` file needed — the changeset covers it. +**Server-only PRs**: If your PR only changes `apps/webapp/`, `apps/supervisor/`, or other server components (and does NOT change anything in `packages/`) AND the change is user-facing, add a `.server-changes/` file. -**Package-only PRs**: Just add a changeset as usual. +**Mixed PRs** (both packages and server): the changeset covers it, so no `.server-changes/` file is needed. If the package change is internal and needs no changeset but the server change is user-facing, add a `.server-changes/` file for it. + +**Package-only PRs**: Just add a changeset as usual, when the change is user-facing. ## File format diff --git a/AGENTS.md b/AGENTS.md index cc947c7a57..2a2dea78b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,7 +92,21 @@ Dynamic imports add unnecessary overhead in hot paths and make code harder to an ## Changesets and Server Changes -When modifying any public package (`packages/*` or `integrations/*`), add a changeset: +Changesets and `.server-changes/` files are **user-facing release notes**. They ship verbatim into the changelog that customers read to decide what to upgrade for or pay attention to. They are not a catalog of every change: anyone who wants the exact history reads the commits. So the question is not "did I touch a public package or a server app?" but **"would a user or customer care about this change?"** + +**Add one** when the change is something a user would notice, act on, or want to hear about: a new feature, a bug fix they could have hit, a behavior or performance change they would feel, a breaking change. + +**Skip it** (no changeset, no `.server-changes/` file) when the change is not worth communicating to users, even if it touches a public package or a server app. For example: + +- internal-only or admin-only changes, refactors, test-only changes, chores +- performance or query tuning with no user-visible behavior change +- changes to a public package that is not consumed independently (e.g. `@trigger.dev/redis-worker`), where a version bump means nothing to a user + +When in doubt, ask a maintainer rather than adding a note by default. An unnecessary entry is noise in the changelog, not a safe default. + +### How to add one + +When a **public package** (`packages/*` or `integrations/*`) change is user-facing, add a changeset: ```bash pnpm run changeset:add @@ -102,9 +116,9 @@ pnpm run changeset:add - Confirm with maintainers before selecting **minor** (new features) - **Never** select major without explicit approval -When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation. +When a **server-only** change (`apps/webapp/`, `apps/supervisor/`, etc., with no package changes) is user-facing, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation. -**Write the description for users, not maintainers.** Both changesets and `.server-changes/` notes ship verbatim in user-visible release notes. Lead with what changed *for the user* - one plain sentence describing behavior, not implementation, and never naming internal tools or infra. The full writing guidance in `.server-changes/README.md` applies to changesets too. +**Write the description for users, not maintainers.** Both changesets and `.server-changes/` notes ship verbatim in user-visible release notes. Lead with what changed *for the user*: one plain sentence describing behavior, not implementation, and never naming internal tools or infra. The full writing guidance in `.server-changes/README.md` applies to changesets too. ## Dependency Pinning diff --git a/CHANGESETS.md b/CHANGESETS.md index db9d5719d9..74f8adda6c 100644 --- a/CHANGESETS.md +++ b/CHANGESETS.md @@ -4,11 +4,13 @@ Trigger.dev uses [changesets](https://github.com/changesets/changesets) to manag ## Adding a changeset (package changes) -To add a changeset, use `pnpm run changeset:add` and follow the instructions [here](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md). Please only ever select one of our public packages when adding a changeset. +Changesets and `.server-changes/` files are user-facing release notes, not a catalog of every change. Add one only when the change is something a user would notice or act on. Skip it for internal-only changes, refactors, chores, and packages that are not consumed independently (e.g. `@trigger.dev/redis-worker`). Anyone who wants the exact history reads the commits. + +To add a changeset, use `pnpm run changeset:add` and follow the [Changesets adding-a-changeset guide](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md). Please only ever select one of our public packages when adding a changeset. ## Adding a server change (server-only changes) -If your PR only changes server components (`apps/webapp/`, `apps/supervisor/`, etc.) and does NOT change any published packages, add a `.server-changes/` file instead of a changeset: +If your PR only changes server components (`apps/webapp/`, `apps/supervisor/`, etc.), does NOT change any published packages, AND the change is user-facing, add a `.server-changes/` file instead of a changeset: ```sh cat > .server-changes/fix-batch-queue-stalls.md << 'EOF' @@ -24,17 +26,19 @@ EOF - `area`: `webapp` | `supervisor` - `type`: `feature` | `fix` | `improvement` | `breaking` -For **mixed PRs** (both packages and server): just add a changeset. No `.server-changes/` file needed. +For **mixed PRs** (both packages and server): the changeset covers it, so no `.server-changes/` file is needed. If the package change is internal and needs no changeset but the server change is user-facing, add a `.server-changes/` file for it. See `.server-changes/README.md` for full documentation. ## When to add which +Only for user-facing changes. Skip the note entirely for internal-only or admin-only changes, refactors, and chores. + | PR changes | What to add | |---|---| -| Only packages (`packages/`) | Changeset (`pnpm run changeset:add`) | -| Only server (`apps/`) | `.server-changes/` file | -| Both packages and server | Just the changeset | +| Only packages (`packages/` or `integrations/`) | Changeset (`pnpm run changeset:add`), if the package change is user-facing | +| Only server (`apps/`) | `.server-changes/` file, if the server change is user-facing | +| Both packages and server | The changeset covers it; if the package change needs no changeset but the server change is user-facing, add a `.server-changes/` file | ## Release instructions (CI) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb41c308fd..127b1e64e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -247,7 +247,7 @@ If your change touches core infrastructure, modifies widely-used code paths, or We use [changesets](https://github.com/changesets/changesets) to manage our package versions and changelogs. If you've never used changesets before, first read [their guide here](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md). -If you are contributing a change to any packages in this monorepo (anything in either the `/packages` or `/integrations` directories), then you will need to add a changeset to your Pull Requests before they can be merged. +Changesets are user-facing release notes, not a catalog of every change. If you are contributing a **user-facing** change to a package in this monorepo (anything in `/packages` or `/integrations` that a user would notice or act on), add a changeset to your Pull Request before it can be merged. Skip the changeset for internal-only changes, refactors, chores, and packages that are not consumed independently (e.g. `@trigger.dev/redis-worker`), where a version bump means nothing to a user. To add a changeset, run the following command in the root of the repo @@ -265,7 +265,7 @@ Most of the time the changes you'll make are likely to be categorized as patch r ## Adding server changes -Changesets only track published npm packages. If your PR only changes server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file so the change appears in release notes. +Changesets only track published npm packages. If your PR only changes server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes AND the change is user-facing, add a `.server-changes/` file so the change appears in release notes. Skip it for internal-only or admin-only changes, refactors, and chores. Create a markdown file with a descriptive name: @@ -286,13 +286,13 @@ EOF The body text (below the frontmatter) is a one-line description of the change. Keep it concise — it will appear in release notes. -**When to add which:** +**When to add which** (only for user-facing changes; skip the note entirely for internal-only or admin-only changes, refactors, and chores): | PR changes | What to add | |---|---| -| Only packages (`packages/`) | Changeset | -| Only server (`apps/`) | `.server-changes/` file | -| Both packages and server | Just the changeset | +| Only packages (`packages/` or `integrations/`) | Changeset (if the package change is user-facing) | +| Only server (`apps/`) | `.server-changes/` file (if the server change is user-facing) | +| Both packages and server | The changeset covers it; if the package change needs no changeset but the server change is user-facing, add a `.server-changes/` file | See `.server-changes/README.md` for more details.