The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Authoring changesets |
| 2 | |
| 3 | Update the changeset already introduced by the PR. If there is none, create one |
| 4 | `.changeset/<descriptive-name>.md` for the complete PR: |
| 5 | |
| 6 | ```md |
| 7 | --- |
| 8 | "effect": patch |
| 9 | "@effect/affected-package": patch |
| 10 | --- |
| 11 | |
| 12 | Fix `Effect.cachedInvalidateWithTTL` caching a stale result when invalidated while the effect is running. |
| 13 | ``` |
| 14 | |
| 15 | Write one short sentence, usually under 25 words, that names the changed API |
| 16 | and states what consumers will notice. That sentence is the whole entry unless |
| 17 | the change is breaking or consumers must migrate. |
| 18 | |
| 19 | Leave out how the change works: internal modules, algorithms, data structures, |
| 20 | refactors, motivation, benchmarks, test coverage, and development history. They |
| 21 | belong in the PR description. Cut any sentence a consumer would not act on. |
| 22 | |
| 23 | - Bad: "Rework the `MemoMap` lookup so `Layer.provide` checks identity before |
| 24 | building, adding a cache keyed by layer reference and tests for shared |
| 25 | layers." |
| 26 | - Good: "Fix composed layers being rebuilt for every parent that references |
| 27 | them." |
| 28 | |
| 29 | Add detail only for a break or required migration: what existing code must |
| 30 | change and how. Use compact bullets, one break per bullet, when several breaks |
| 31 | need migration steps. Several non-breaking fixes or additions still share one |
| 32 | sentence. |
| 33 | |
| 34 | List every directly affected published package. Do not list packages merely |
| 35 | because they share the fixed release group in `.changeset/config.json`. |
| 36 | |
| 37 | Choose the bump from current release policy: |
| 38 | |
| 39 | - APIs tagged `@stability stable`, and APIs without a stability tag, follow |
| 40 | strict semver: `patch` for compatible fixes, `minor` for compatible |
| 41 | additions, and `major` for breaks. |
| 42 | - For APIs tagged `@stability unstable`, use `patch` for compatible fixes and |
| 43 | new features. Only a break is `minor`. |
| 44 | - For APIs tagged `@stability experimental`, use `patch` for fixes, new |
| 45 | features, and breaks. |
| 46 | - When a PR touches APIs at several stability levels, use the highest bump any |
| 47 | of them requires. |
| 48 | - Use `major` only when a maintainer has approved a major release. |
| 49 | - The release queue retargets PRs with `minor` changesets to `v4/next-minor` |
| 50 | and PRs with `major` changesets to `v4/next-major`. Choose the level the |
| 51 | change requires, not the branch you want it to land on. |
| 52 | - Ask when release intent is ambiguous. |
| 53 | |
| 54 | Use a `### Breaking changes` section when several breaks need separate |
| 55 | scanning. Include before/after examples only when they materially clarify |
| 56 | migration. |
| 57 | |
| 58 | Validate frontmatter against published package names and inspect nearby current |
| 59 | changesets for release convention. Do not copy the length of longer entries. |
| 60 | Never run `changeset-version` or `changeset-publish` as contributor validation. |