Changeset

Changeset

Create changeset files for the Astro monorepo. Changesets declare which packages changed, the semver bump type, and a user-facing message that becomes the CHANGELOG entry.

Every PR that modifies a package requires a changeset. Only examples/* changes are exempt.

Creating the File

Run pnpm changeset --empty from the repo root. This creates a randomly-named .md file in .changeset/ with empty front matter — no need to invent a filename or inspect the directory. Then edit the generated file to add the package bump and message.

Format

---
'<package-name>': patch
---

<changeset message>

• Package names must match the name field in the package's package.json exactly (e.g., 'astro', '@astrojs/node')
• Bump types: patch, minor, or major
• A single changeset file can cover multiple packages
• major and minor bumps to the core astro package are blocked by CI and require maintainer review

Writing the Message

The changeset message is a public CHANGELOG entry. Write it for Astro users, not for code reviewers.

Begin with a present tense verb that completes the sentence "This PR ...":

• Adds, Removes, Fixes, Updates, Refactors, Improves, Deprecates

Describe the change as someone building an Astro site will experience it, not how it was implemented internally:

// Too implementation-focused
Logs helpful errors if content is invalid

// Better -- user-facing impact
Adds logging for content collections configuration errors.

Patch updates

One line is usually enough. No end punctuation required unless writing multiple sentences.

---
'astro': patch
---

Fixes a bug where the toolbar audit would incorrectly flag images as above the fold

---
'astro': patch
---

Refactors internal handling of styles and scripts for content collections to improve build performance

Help the reader figure out if the change matters to them. Include the specific API name (with backtick formatting) when the change is tied to a recognizable option or function. When the API is not user-facing, describe the use case or end result instead:

// Vague
Improves automatic fallbacks generation

// Clear -- reader can tell if it affects them
Improves automatic `fallbacks` generation for the experimental Fonts API

New features (minor)

Start with "Adds", name the new API, and describe what users can now do. Include a code example when helpful:

---
'astro': minor
---

Adds a new, optional property `timeout` for the `client:idle` directive

This value allows you to specify a maximum time to wait, in milliseconds, before hydrating a UI framework component.

```astro
<Button client:idle={{ timeout: 500 }} />
```

New features are an opportunity to write a richer description that can feed into blog posts. See the Astro changeset docs for guidance on longer entries.

Breaking changes (major)

Use verbs like "Removes", "Changes", or "Deprecates". Must include migration guidance. Use diff code samples when appropriate:

---
'astro': major
---

Removes support for Shiki custom language's `path` property. The language JSON file must now be imported and passed to the option instead.

```diff
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: './custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})
```

Changes to default values must mention the old default, the new default, and how to restore previous behavior.

Longer changesets

For longer descriptions, use #### and deeper headings (never ## or ###) to divide sections. This keeps the CHANGELOG readable when your entry is incorporated:

---
'astro': minor
---

Adds a new Sessions API to store user state between requests for on-demand rendered pages.

#### Configuring session storage

<!-- ... -->

#### Using sessions

<!-- ... -->