Every non-trivial change to the project - those that should appear in the changelog - must be captured in a "changeset".
We use the changesets tool for creating changesets, publishing versions and updating the changelog.
pnpm changeset- Select which packages are affected by the change
- Choose whether the version requires a major, minor, or patch release
- Write a description of the change (see format below)
- Include the generated changeset in your commit:
git add .changeset/*.md
- patch: Bug fixes, small improvements, documentation fixes
- minor: New features, new CLI commands, new configuration options, deprecations, and changes to experimental/beta/pre-1.0 features (including breaking changes to those features). When adding or changing experimental features, call this out explicitly in the changeset description.
- major: Breaking changes to stable features (when deprecations take effect, or functional breaking behavior is added). Note: breaking changes to experimental/beta features do NOT require a major version bump.
Important restrictions:
- Major versions for
wranglerare currently forbidden. This rule will be removed when we are preparing for the next major release ofwrangler. - Major versions for other packages require strong justification
- If the change collects more analytics, it should be a minor even though there is no user-visible change.
<TITLE>
<BODY>
- TITLE: A single sentence with an imperative description of the change
- BODY: One or more paragraphs explaining the reason for the change and anything notable about the approach. Aim for more than one sentence but less than three paragraphs to keep it succinct and useful. Larger changes may warrant more detail.
For a new feature (minor):
---
"wrangler": minor
---
Add `wrangler d1 export` command for exporting D1 databases to SQL files
You can now export your D1 database to a local SQL file:
`wrangler d1 export my-database --output backup.sql`
This is useful for creating backups or migrating data between databases.For a bug fix (patch):
---
"wrangler": patch
---
Fix `wrangler dev` failing to start when `wrangler.toml` contains Unicode characters
Previously, projects with non-ASCII characters in configuration values would fail with "Invalid UTF-8 sequence". This is now handled correctly.- "fix bug" - What bug? What was the symptom?
- "update dependency" - Which one? Why? Any user impact?
- "Add new feature" - What feature? How do you use it?
- "refactor" - Why does this warrant a release? What's the user impact?
Changeset descriptions must NOT use h1 (#), h2 (##), or h3 (###) headers.
The changelog uses h3 for section headers, so any headers in changeset content must be h4 (####) or smaller. This prevents formatting issues in the generated changelog.
For new features or significant changes, consider including a brief usage example. Examples can be helpful for users to understand new functionality, but they are not mandatory—use your judgment based on how self-explanatory the change is.
When showing Wrangler configuration examples, use wrangler.json (with JSONC syntax for comments) rather than wrangler.toml.
If your PR makes multiple distinct user-facing changes, create separate changesets so each gets its own changelog entry. Don't lump unrelated changes together, and don't mix different types of changes (e.g., bug fix + new feature) in a single changeset.
Each changeset should reference all packages that have user-facing changes:
- If a change affects multiple packages, list them all in the changeset
- Alternatively, create separate changesets for each package if the changes warrant different descriptions
- Changesets automatically releases packages affected through runtime dependencies. Include consumers of bundled
devDependenciesexplicitly, because Changesets does not bump their versions automatically.
- Changes that are purely internal refactoring with no user-facing impact
- Changes only to devDependencies
- Documentation-only changes within a package
- Test-only changes
- CI/workflow changes that don't affect package behavior
To release an npm package as a prerelease while other packages continue receiving stable releases, add an npmPrerelease object to its workers-sdk metadata:
{
"workers-sdk": {
"npmPrerelease": {
"tag": "beta",
"numbered": true
}
}
}The tag is appended to versions and used as the npm dist-tag. The latest tag is reserved for stable releases and cannot be used for a prerelease. Numbered prereleases advance a counter such as 2.0.0-beta.0, 2.0.0-beta.1, and so on. Unnumbered prereleases advance the package's patch version instead, producing versions such as 5.20260723.0-beta and 5.20260723.1-beta.
Add a changeset when starting a prerelease. Miniflare requires a major changeset when beginning a new major prerelease because its minor version remains aligned with workerd. While a prerelease is active, major, minor, and patch changesets all advance it by one release. Updating workerd updates Miniflare's date and resets its patch to 0.
Change tag and add a changeset to move to another stage such as beta or rc. Releases with the rc tag also update the beta npm dist-tag to the same version, so existing beta users receive release candidates. Before entering rc, enable Allow npm dist-tag for the package's changesets.yml trusted publisher in its npm settings. To graduate, remove npmPrerelease and add a changeset. The prerelease suffix will be removed while retaining the target version.
Here's a complete example of a patch changeset file:
---
"wrangler": patch
---
Replace the word "publish" with "deploy" everywhere
We should be consistent with the word that describes how we get a worker to the edge. The command is `deploy`, so let's use that everywhere.