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.

Author: ericallam

.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/*` 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 `apps/webapp/`, `apps/supervisor/` edits with no public-package change when the change is user-facing; 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.

.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 server app change (webapp, supervisor, etc.) with **no package changes** is user-facing (something a user would notice or act on), 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/` and the package change needs a changeset, that changeset covers it (no `.server-changes/` needed). If the package 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.

.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
 

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
 

CHANGESETS.md

@@ -4,11 +4,13 @@ Trigger.dev uses [changesets](https://github.com/changesets/changesets) to manag
 
 ## Adding a changeset (package changes)
 
+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 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.
 
 ## 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/`) | 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)
 

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/`) | 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.