---
id: biomejs/biome/changeset
version: "000cfd9f"
license: Apache-2.0
install: manual
updated: 2026-07-27
---

# changeset — This skill walks you through building changesets for Biome pull requests that introduce user-facing changes—bug fixes, new features, rule updates, or formatter tweaks. It covers selecting the right change type (patch, minor, or major), formatting rules, and writing clear descriptions with examples. Use it whenever your PR needs a CHANGELOG entry.

Publisher: biomejs · Stars: 25418 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/biomejs/biome`

## SKILL.md

## Purpose

Use this skill when a PR introduces user-facing changes that require a changeset. Changesets drive CHANGELOG generation and release automation. Internal-only changes (refactors with no user-visible effect) do not need changesets.

## Create a Changeset

**Do not create changeset files manually.** Use:

```shell
just new-changeset-empty
```

The command will create a file in `.changeset/`. Edit it directly to add detail.

Note that the file will *not* be literally empty. It will have this content:

```markdown
---
---
```

Do not simply append to the changeset description below the existing content, which creates an invalid changeset.

> Requires `pnpm` — run `pnpm i` from repo root first.

## Choose the Correct Change Type

- `patch` — Bug fixes.
- `minor` — New features. PR must target the `next` branch.
- `major` — Breaking user API changes. PR must target the `next` branch. These are rare and strictly controlled.

Refer to the [versioning page](https://biomejs.dev/internals/versioning/) when unsure.

## Changeset Format

```markdown
---
"@biomejs/biome": patch
---

Description here.
```

If you need headers inside the description, use `####` or `#####` only. Other header levels break the CHANGELOG tooling.

## Writing Guidelines

### General Rules

- Write about **user-facing changes only**. No changeset needed for pure refactoring. Describe how the change affects the user.
- Be **concise and clear** — 1 to 3 sentences. Longer entries signal to users that the change deserves attention.
- **Past tense** for what you did: "Added", "Fixed", "Changed".
- **Present tense** for Biome behavior: "Biome now supports...", "The rule now detects...".
- End every sentence with a **full stop** (`.`).

### Bug Fixes

Start with a link to the issue:

```markdown
Fixed [#4444](https://github.com/biomejs/biome/issues/4444): [`useOptionalChain`](https://biomejs.dev/linter/rules/use-optional-chain/) now detects negated logical OR chains.
```

### New Lint Rules

Show an example of an invalid case. Use inline code for simple things, a code block for complex ones:

```markdown
Added a new nursery rule [`noDuplicateSelectors`](https://biomejs.dev/linter/rules/no-duplicate-selectors/), that disallows duplicate selector lists within the same at-rule context.

For example, the following snippet triggers the rule:

` ` `css
.foo {}
.foo {}
` ` `
```

### Changes to Existing Rules

Clearly show what is now invalid that was not before (or vice versa). Show both sides if helpful:

```markdown
Fixed [#7211](https://github.com/biomejs/biome/issues/7211): [`useOptionalChain`](https://biomejs.dev/linter/rules/use-optional-chain/) now detects negated logical OR chains. The following code is now considered invalid:

` ` `js
!foo || !foo.bar
` ` `
```

### Formatter Changes

Show the formatting diff:

```markdown
Changed formatting of arrow function parameters. Example:

` ` `diff
- const fn = (  a,  b  ) => {};
+ const fn = (a, b) => {};
` ` `
```

### Parser Changes

Brief inline example of what can now be parsed:

```markdown
Added support for parsing `using` declarations in JavaScript.
```

Use a code block if multiline clarity helps.

### Linking Rules and Assists

Always link to the website, even if the page does not exist yet (it will after merge):

- Rules: `` [`useConst`](https://biomejs.dev/linter/rules/use-const/) ``
- Assists: `` [`organizeImports`](https://biomejs.dev/assist/actions/organize-imports/) ``

## Tips

- Create the changeset before opening the PR; you can edit it after.
- Look at existing files in `.changeset/` or recent `CHANGELOG.md` entries for reference.
- One changeset per PR is typical. Multiple changesets are allowed if the PR addresses multiple, distinct bugs.

## References

- Contribution guide: `CONTRIBUTING.md` section "Changelog"
- Versioning policy: https://biomejs.dev/internals/versioning/
- Changesets documentation: https://github.com/changesets/changesets


[View on SkillFed](https://skillfed.io/biomejs/biome/changeset) · [View on GitHub](https://github.com/biomejs/biome)