changeset

Source excerpt starting at line 1.

1---2name: changeset3description: Create a changeset for the Astro monorepo. Use this skill whenever you need to add a changeset file to a PR, write a changelog entry, or document a package version bump. Also trigger when the user says "add a changeset", "write a changeset", "create a changeset", or when another skill instructs you to create a changeset.4---5 6# Changeset7 8Create 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.9 10Every PR that modifies a package requires a changeset. Only `examples/*` changes are exempt.11 12## Creating the File13 14Run `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.15 16## Format17 18```md19---20'<package-name>': patch21---22 23<changeset message>24```25 26- Package names must match the `name` field in the package's `package.json` exactly (e.g., `'astro'`, `'@astrojs/node'`)27- Bump types: `patch`, `minor`, or `major`28- A single changeset file can cover multiple packages29- `major` and `minor` bumps to the core `astro` package are blocked by CI and require maintainer review30 31## Writing the Message32 33The changeset message is a public CHANGELOG entry. Write it for **Astro users**, not for code reviewers.34 35Begin with a **present tense verb** that completes the sentence "This PR ...":36 37- Adds, Removes, Fixes, Updates, Refactors, Improves, Deprecates38 39Describe the change **as someone building an Astro site will experience it**, not how it was implemented internally:40 41```md42// Too implementation-focused43Logs helpful errors if content is invalid44 45// Better -- user-facing impact46Adds logging for content collections configuration errors.47```48 49### Patch updates50 51One line is usually enough. No end punctuation required unless writing multiple sentences.52 53```md54---55'astro': patch56---57 58Fixes a bug where the toolbar audit would incorrectly flag images as above the fold59```60 61```md62---63'astro': patch64---65 66Refactors internal handling of styles and scripts for content collections to improve build performance67```68 69Help 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:70 71```md72// Vague73Improves automatic fallbacks generation74 75// Clear -- reader can tell if it affects them76Improves automatic `fallbacks` generation for the experimental Fonts API77```78 79### New features (minor)80 81Start with "Adds", name the new API, and describe what users can now do. Include a code example when helpful:82 83````md84---85'astro': minor86---87 88Adds a new, optional property `timeout` for the `client:idle` directive89 90This value allows you to specify a maximum time to wait, in milliseconds, before hydrating a UI framework component.91 92```astro93<Button client:idle={{ timeout: 500 }} />94```95````96 97New features are an opportunity to write a richer description that can feed into blog posts. See the [Astro changeset docs](https://contribute.docs.astro.build/docs-for-code-changes/changesets/#new-features) for guidance on longer entries.98 99### Breaking changes (major)100 101Use verbs like "Removes", "Changes", or "Deprecates". Must include migration guidance. Use diff code samples when appropriate:102 103````md104---105'astro': major106---107 108Removes support for Shiki custom language's `path` property. The language JSON file must now be imported and passed to the option instead.109 110```diff111// astro.config.js112+ import customLang from './custom.tmLanguage.json'113 114export default defineConfig({115  markdown: {116    shikiConfig: {117      langs: [118-       { path: './custom.tmLanguage.json' },119+       customLang,120      ],121    },122  },123})124```125````126 127Changes to default values must mention the old default, the new default, and how to restore previous behavior.128 129### Longer changesets130 131For longer descriptions, use `####` and deeper headings (never `##` or `###`) to divide sections. This keeps the CHANGELOG readable when your entry is incorporated:132 133```md134---135'astro': minor136---137 138Adds a new Sessions API to store user state between requests for on-demand rendered pages.139 140#### Configuring session storage141 142<!-- ... -->143 144#### Using sessions145 146<!-- ... -->147```148