|
| 1 | +--- |
| 2 | +name: changesets |
| 3 | +description: 'Use when: adding changesets to pull requests, determining semver bump types, versioning packages, or preparing releases. Covers changeset file format, semver guidance, when changesets are required, and the release pipeline.' |
| 4 | +--- |
| 5 | + |
| 6 | +# Changesets in Primer React |
| 7 | + |
| 8 | +This repository uses [Changesets](https://github.com/changesets/changesets) to manage versioning and changelogs. Every pull request that changes the public API or runtime behavior of a package must include a changeset file. |
| 9 | + |
| 10 | +## What is a changeset? |
| 11 | + |
| 12 | +A changeset is a markdown file in the `.changeset/` directory that describes: |
| 13 | + |
| 14 | +1. **Which package** is affected (e.g., `@primer/react`) |
| 15 | +2. **What semver bump** to apply (`patch`, `minor`, or `major`) |
| 16 | +3. **A human-readable description** of the change (used in the changelog) |
| 17 | + |
| 18 | +## File format |
| 19 | + |
| 20 | +Changeset files live in `.changeset/` and have a random name with a `.md` extension. The file uses YAML frontmatter to specify the package and bump type, followed by a description: |
| 21 | + |
| 22 | +```markdown |
| 23 | +--- |
| 24 | +'@primer/react': patch |
| 25 | +--- |
| 26 | + |
| 27 | +ActionMenu: Fix focus management when menu is closed with Escape key |
| 28 | +``` |
| 29 | + |
| 30 | +The description should be concise and follow this pattern: |
| 31 | + |
| 32 | +- Start with the component or module name followed by a colon |
| 33 | +- Describe WHAT changed and WHY |
| 34 | +- Write from the consumer's perspective |
| 35 | + |
| 36 | +## How to create a changeset |
| 37 | + |
| 38 | +### Option 1: Interactive CLI |
| 39 | + |
| 40 | +Run `npx changeset` and follow the prompts to select the package, bump type, and enter a description. |
| 41 | + |
| 42 | +### Option 2: Manually create a file |
| 43 | + |
| 44 | +Create a new file in `.changeset/` with a unique name (e.g., `.changeset/my-change-description.md`): |
| 45 | + |
| 46 | +```markdown |
| 47 | +--- |
| 48 | +'@primer/react': minor |
| 49 | +--- |
| 50 | + |
| 51 | +Avatar: Add `square` variant for non-user avatars |
| 52 | +``` |
| 53 | + |
| 54 | +Use lowercase kebab-case for the filename. The name is arbitrary but should be descriptive. |
| 55 | + |
| 56 | +## Choosing the correct semver bump |
| 57 | + |
| 58 | +Use this quick reference to determine the bump type. For the full decision table with detailed examples, see `contributor-docs/versioning.md`. |
| 59 | + |
| 60 | +### `patch` — Bug fixes and internal corrections |
| 61 | + |
| 62 | +- Fix a bug in component behavior |
| 63 | +- Fix a styling issue |
| 64 | +- Fix a TypeScript type that was incorrect |
| 65 | +- Internal refactor that does not change the public API |
| 66 | + |
| 67 | +### `minor` — New features and non-breaking additions |
| 68 | + |
| 69 | +- Add a new component |
| 70 | +- Add a new prop to an existing component |
| 71 | +- Broaden the type of an existing prop (e.g., `string` → `string | number`) |
| 72 | +- Deprecate a component or prop |
| 73 | +- Add a new export |
| 74 | +- Add a `data-component` attribute |
| 75 | +- Add a dependency |
| 76 | + |
| 77 | +### `major` — Breaking changes |
| 78 | + |
| 79 | +- Remove a component |
| 80 | +- Remove a prop |
| 81 | +- Narrow the type of a prop (e.g., `string` → `'a' | 'b'`) |
| 82 | +- Change the element that props are spread onto |
| 83 | +- Broaden the element type in an event handler |
| 84 | +- Remove or rename a `data-component` attribute |
| 85 | +- Bump a dependency to a new major version |
| 86 | + |
| 87 | +## When a changeset is NOT needed |
| 88 | + |
| 89 | +Skip the changeset for changes that do not affect the published package: |
| 90 | + |
| 91 | +- Documentation-only changes (markdown files, docs site content) |
| 92 | +- Test-only changes (adding or updating tests) |
| 93 | +- CI/infrastructure changes (GitHub Actions, scripts, config files) |
| 94 | +- Storybook stories that don't change component source |
| 95 | +- Dev dependency updates |
| 96 | +- Changes to `examples/` or `e2e/` directories |
| 97 | + |
| 98 | +When a changeset is not needed, add the `skip changeset` label to the pull request. This bypasses the CI check that requires a changeset to be present. |
| 99 | + |
| 100 | +## Multiple changesets in one PR |
| 101 | + |
| 102 | +If a PR introduces multiple distinct changes, add a **separate changeset file for each**. For example, if you fix a bug in `Button` and add a new prop to `ActionMenu`, create two changeset files — one `patch` for the fix and one `minor` for the new prop. |
| 103 | + |
| 104 | +## Release pipeline |
| 105 | + |
| 106 | +Understanding the release pipeline helps explain why changesets are required: |
| 107 | + |
| 108 | +1. **On PR creation**: `changeset-bot` comments on the PR indicating whether valid changesets are present. If your change requires a changeset and none is found, the bot will flag it. |
| 109 | +2. **On merge to `main`**: The `changesets/action` GitHub Action automatically creates or updates a "Version Packages" release PR that bumps version numbers, updates `CHANGELOG.md`, and shows release notes. |
| 110 | +3. **On merging the release PR**: The action publishes the new version to npm and creates a GitHub Release. |
| 111 | + |
| 112 | +## Common files |
| 113 | + |
| 114 | +- `.changeset/*.md` — Changeset files (one per change) |
| 115 | +- `.changeset/config.json` — Changesets configuration |
| 116 | +- `contributor-docs/versioning.md` — Detailed semver bump guidance |
| 117 | +- `contributor-docs/CONTRIBUTING.md` — Contributing guidelines including changeset instructions |
0 commit comments