1# Authoring changesets
2
3Update 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
12Describe the consumer-visible change and why it matters.
13```
14
15Default to one short paragraph of one to three sentences. State the changed
16behavior or API and, for a break, the required migration. Leave motivation,
17implementation details, benchmarks, test coverage, and the development history
18in the PR description.
19
20When several related consumer-visible effects cannot be stated clearly in that
21paragraph, use compact bullets with one outcome per bullet. Keep them in this
22file under the PR's shared purpose.
23
24List every directly affected published package. Do not list packages merely
25because they share the fixed release group in `.changeset/config.json`.
26
27Choose the bump from current release policy:
28
29- Use `patch` for compatible fixes, `minor` for compatible additions, and
30 `major` for breaks.
31- A break confined to APIs tagged `@stability unstable` is `minor`. A break
32 confined to APIs tagged `@stability experimental` is `patch`. APIs without a
33 stability tag follow strict semver.
34- Use `major` only when a maintainer has approved a major release.
35- The release queue retargets PRs with `minor` changesets to `v4/next-minor`
36 and PRs with `major` changesets to `v4/next-major`. Choose the level the
37 change requires, not the branch you want it to land on.
38- Ask when release intent is ambiguous.
39
40Write for consumers. Use a `### Breaking changes` section when several breaks
41need separate scanning. Include before/after examples only when they materially
42clarify migration.
43
44Validate frontmatter against published package names and inspect nearby current
45changesets for wording and release convention. Never run `changeset-version` or
46`changeset-publish` as contributor validation.