| name | changesets |
| description | Use when a pull request changes a package's public API. Covers affected packages, semantic version impact, file format, and user-focused release notes. |
Changesets
This repository uses Changesets to
version packages and generate changelogs. Add a changeset whenever a pull
request changes the public API of a published package.
A changeset records:
- Every published package affected by the public API change
- The semantic version impact (
patch, minor, or major) for each package
- A concise description of the change for users of the affected packages
When a changeset is required
Add a changeset for consumer-facing changes such as:
- Adding, removing, or renaming an icon
- Changing an icon's rendered appearance or behavior
- Adding, removing, or changing an export
- Changing public JavaScript, React, CSS, or TypeScript APIs
- Fixing behavior that users experience through a package's public API
Changes that do not affect a published package's public API, such as
documentation, tests, internal refactors, or CI configuration, do not need a
changeset. Add the skip changeset label to those pull requests.
Identify affected packages
Review the change from the perspective of users of each published package.
Include every package whose shipped public API or output changes:
@primer/octicons@primer/octicons-react@primer/styled-octicons
Do not select a package only because its internal source or build process
changed. Select it when users of that package will observe the change.
Choose the version impact
patch: A backwards-compatible fix to existing public behavior or icon
outputminor: A backwards-compatible public API addition, such as a new icon or
exportmajor: A breaking public API change, such as removing or renaming an icon
or export
Choose the impact independently for each affected package.
Author a changeset
Run npx changeset and follow the prompts to select every affected package,
choose its version impact, and enter the description. Commit the generated
markdown file in .changeset/ to the pull request branch.
To create one manually, add a uniquely named markdown file in .changeset/
with YAML frontmatter for all affected packages:
---
'@primer/octicons': minor
'@primer/octicons-react': minor
'@primer/styled-octicons': minor
---
Add the accessibility icon for representing accessible experiences.
Write for package users
The description is published in package changelogs and release notes. Write it
as communication to users of the library:
- Describe the public API change and its user-visible effect
- Use one or two concise sentences
- Name relevant icons, exports, or packages when that helps users understand
the impact
- Use present tense and active voice
- Exclude implementation details, internal file names, test changes, and pull
request process
Good:
Add the `AccessibilityInsetIcon` export for representing accessible
experiences.
Avoid:
Update the build script and generated files after adding a new SVG, including
snapshot changes.
The avoided example explains the implementation rather than the public API
change that users need to know about.
