changesets · Andarist · Jul 29, 2026 · May 5, 2026 · May 5, 2026 · May 5, 2026
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@ dist/
 node_modules/
 .env
 *error.log
+/site/.vitepress/cache/
diff --git a/.node-version b/.node-version
@@ -1 +1 @@
-v22.9.0
+v24
diff --git a/README.md b/README.md
@@ -21,102 +21,11 @@
 <br/>
 
 [![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/@changesets/cli?name=true)](https://npmx.dev/package/@changesets/cli)
-[![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/@changesets/cli?color=229fe4&value=View+changelog&label=+)](./packages/cli/CHANGELOG.md)
+[![View changelog](https://npmx.dev/api/registry/badge/version/@changesets/cli?color=229fe4&value=View+changelog&label=+)](./packages/cli/CHANGELOG.md)
 [![pkg.pr.new](https://pkg.pr.new/badge/changesets/changesets)](https://pkg.pr.new/~/changesets/changesets)
 
-The `changesets` workflow is designed to help when people are making changes, all the way through to publishing. It lets contributors declare how their changes should be released, then we automate updating package versions, and changelogs, and publishing new versions of packages based on the provided information.
+Changesets is designed to help manage and describe changes, all the way through to publishing. It lets contributors declare how their changes should be released, and it'll handle updating package versions, changelogs, and publishing based on the provided changesets.
 
-Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages.
+Changesets has a focus on solving these problems for monorepos, keeping packages that rely on each other up to date, as well as making it easy to make changes to groups of packages. Conceptually, the workflow is also beneficial for single package repos.
 
-## How do we do that?
-
-A `changeset` is an intent to release a set of packages at particular [semver bump types](https://semver.org/) with a summary of the changes made.
-
-The **@changesets/cli** package allows you to write `changeset` files as you make changes, then combine any number of changesets into a release, that flattens the bump-types into a single release per package, handles internal dependencies in a multi-package-repository, and updates changelogs, as well as release all updated packages from a mono-repository with one command.
-
-## How do I get started?
-
-If you just want to jump in to using changesets, the [Intro to using changesets](./docs/intro-to-using-changesets.md) and [@changesets/cli](./packages/cli/README.md) docs are where you should head.
-
-If you want a detailed explanation of the concepts behind changesets, or to understand how you would build on top
-of changesets, check out our [detailed-explanation](./docs/detailed-explanation.md).
-
-We also have a [dictionary](./docs/dictionary.md).
-
-## Integrating with CI
-
-While changesets can be an entirely manual process, we recommend integrating it with how your CI works.
-
-To check that PRs contain a changeset, we recommend using [the changeset bot](https://github.com/apps/changeset-bot), or if you want to fail builds on a changesets failure, run `yarn changeset status` in CI.
-
-To make releasing easier, you can use [this changesets github action](https://github.com/changesets/action) to automate creating versioning pull requests, and optionally publishing packages.
-
-## Documentation
-
-- [Intro to using changesets](./docs/intro-to-using-changesets.md)
-- [Detailed explanation](./docs/detailed-explanation.md)
-- [Common questions](./docs/common-questions.md)
-- [Adding a changeset](./docs/adding-a-changeset.md)
-- [Automating changesets](./docs/automating-changesets.md)
-- [Checking for changesets](./docs/checking-for-changesets.md)
-- [Command line options](./docs/command-line-options.md)
-- [Config file options](./docs/config-file-options.md)
-- [Decisions](./docs/decisions.md)
-- [Dictionary](./docs/dictionary.md)
-- [Fixed packages](./docs/fixed-packages.md)
-- [Linked packages](./docs/linked-packages.md)
-- [Modifying changelog format](./docs/modifying-changelog-format.md)
-- [Prereleases](./docs/prereleases.md)
-- [Problems publishing in monorepos](./docs/problems-publishing-in-monorepos.md)
-- [Snapshot releases](./docs/snapshot-releases.md)
-- [Versioning applications and other non-npm packages](./docs/versioning-apps.md)
-- [Experimental Options](./docs/experimental-options.md)
-
-## Cool Projects already using Changesets for versioning and changelogs
-
-- [atlaskit](https://atlaskit.atlassian.com)
-- [emotion](https://emotion.sh/docs/introduction)
-- [keystone](https://keystonejs.com)
-- [react-select](https://react-select.com/home)
-- [XState](https://xstate.js.org)
-- [pnpm](https://pnpm.io)
-- [tinyhttp](https://github.com/talentlessguy/tinyhttp)
-- [Firebase Javascript SDK](https://github.com/firebase/firebase-js-sdk)
-- [Formik](https://github.com/jaredpalmer/formik)
-- [MobX](https://github.com/mobxjs/mobx)
-- [Nhost](https://github.com/nhost/nhost)
-- [verdaccio](https://verdaccio.org)
-- [Chakra UI](https://chakra-ui.com)
-- [Astro](https://astro.build)
-- [Biome](https://biomejs.dev)
-- [SvelteKit](https://kit.svelte.dev)
-- [Hydrogen](https://hydrogen.shopify.dev)
-- [react-pdf](https://github.com/diegomura/react-pdf)
-- [GraphQL Code Generator](https://github.com/dotansimha/graphql-code-generator)
-- [GraphQL Yoga](https://github.com/dotansimha/graphql-yoga)
-- [GraphQL-Mesh](https://github.com/Urigo/graphql-mesh)
-- [GraphiQL](https://github.com/graphql/graphiql)
-- [wagmi](https://github.com/wagmi-dev/wagmi)
-- [refine](https://github.com/pankod/refine)
-- [Modern Web](https://modern-web.dev)
-- [Atomizer](https://github.com/acss-io/atomizer)
-- [Medusa](https://github.com/medusajs/medusa)
-- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts)
-- [Block Protocol](https://github.com/blockprotocol/blockprotocol)
-- [Remix](https://remix.run/)
-- [Clerk](https://github.com/clerk/javascript)
-- [Hey API](https://github.com/hey-api/openapi-ts)
-- [neverthrow](https://github.com/supermacro/neverthrow)
-- [Apollo Client](https://github.com/apollographql/apollo-client)
-- [Adobe Spectrum CSS](https://github.com/adobe/spectrum-css)
-- [Adobe Spectrum Web Components](https://github.com/adobe/spectrum-web-components)
-- [React Email](https://react.email)
-
-<!-- NOTE: we currently only accept new entries with at least 1000 GitHub stars -->
-
-# Thanks/Inspiration
-
-- [bolt](https://github.com/boltpkg/bolt) - Brought us a strong concept of how packages in a mono-repo should be able to interconnect, and provided the initial infrastructure to get inter-package information.
-- [Atlassian](https://www.atlassian.com/) - The original idea/sponsor of the changesets code, and where many of the ideas and processes were fermented. It was originally implemented by the team behind [atlaskit](https://atlaskit.atlassian.com).
-- [lerna-semantic-release](https://github.com/atlassian/lerna-semantic-release) - put down many of the initial patterns around updating packages within a multi-package-repository, and started us thinking about how to manage dependent packages.
-- [Thinkmill](https://www.thinkmill.com.au) - For sponsoring the focused open sourcing of this project, and the version two rearchitecture.
+Visit https://changesets.dev to learn more.
diff --git a/docs/adding-a-changeset.md b/docs/adding-a-changeset.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/faq#how-do-i-add-a-changeset
+
 # Adding a changeset
 
 Hi! You might be here because a person or a bot has asked you to 'add a changeset' to a project. Let's walk through adding a changeset. But first, what is a changeset?

diff --git a/docs/automating-changesets.md b/docs/automating-changesets.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/automating
+
 # Automating Changesets
 
 While changesets are designed to work with a fully manual process, it also provides tools to help automate these releases. These can be broken into two major decisions:

diff --git a/docs/checking-for-changesets.md b/docs/checking-for-changesets.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/automating#how-do-i-ensure-pull-requests-have-changesets
+
 # Checking for changesets
 
 Using `@changesets/cli`, there is a `status` command. See the docs for it in the

diff --git a/docs/command-line-options.md b/docs/command-line-options.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/cli
+
 # Command line options
 
 The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](./intro-to-using-changesets.md)

diff --git a/docs/common-questions.md b/docs/common-questions.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/faq
+
 # Common Questions
 
 A quick list of common questions you might want answered to understand what changesets is doing, without going into minutiae or workflow.

diff --git a/docs/config-file-options.md b/docs/config-file-options.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/config
+
 # Configuring Changesets
 
 Changesets has a minimal amount of configuration options. Mostly these are for when you need to change the default workflows. These are stored in `.changeset/config.json`. Our default config is:

diff --git a/docs/decisions.md b/docs/decisions.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/technical-decisions
+
 # Decisions
 
 This file is a discussion of some of the rules and design decisions that have gone into making changesets. The goal of all of these has been to make the experience of using changesets easy, while still providing the maximum value possible.

diff --git a/docs/detailed-explanation.md b/docs/detailed-explanation.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/why
+
 # A Detailed Explanation of Changesets
 
 Below, you will find a detailed explanation of what changesets are, and how they are being thought about.

diff --git a/docs/dictionary.md b/docs/dictionary.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. There is no up-to-date version of this documentation as the relevant concepts are explained inlined where needed.
+
 # Changesets Dictionary
 
 This is a list of some words and phrases that are used in changesets which are helpful to know so that contributors to changesets have a shared understanding of various concepts in the project.

diff --git a/docs/experimental-options.md b/docs/experimental-options.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/config#experimentalunsafeoptions-will-change-in-patch
+
 # Experimental Options
 
 All experimental options are configured in `config.json` under `___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH` flag.

diff --git a/docs/fixed-packages.md b/docs/fixed-packages.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/fixed-packages
+
 # Fixed Packages
 
 Fixed packages allow you to specify a group or groups of packages that should be versioned and published together.

diff --git a/docs/intro-to-using-changesets.md b/docs/intro-to-using-changesets.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/getting-started
+
 # Using Changesets
 
 Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following [semver](https://semver.org/)), and change information to be added to a changelog.

diff --git a/docs/linked-packages.md b/docs/linked-packages.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/linked-packages
+
 # Linked Packages
 
 Linked packages allow you to specify a group or groups of packages that should be versioned together. There are some complex cases, so some examples are shown below to demonstrate various cases.

diff --git a/docs/modifying-changelog-format.md b/docs/modifying-changelog-format.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/customize-changelog-format
+
 # Modifying The Changelog Formats
 
 Changesets comes with a default format for the changelogs for packages which is relatively basic in what information it displays, however this is customisable. Here we will talk about how to modify the changelog, so that it contains extra meta-information.

diff --git a/docs/prereleases.md b/docs/prereleases.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/prereleases
+
 # Prereleases
 
 > Warning! Prereleases are very complicated! Using them requires a thorough understanding of all parts of npm publishes. Mistakes can lead to repository and publish states that are very hard to fix.

diff --git a/docs/problems-publishing-in-monorepos.md b/docs/problems-publishing-in-monorepos.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. There is no up-to-date version of this documentation as problems are explained inlined where needed.
+
 # Problems Publishing in Monorepos
 
 Monorepos have a heap of complexity around how publishing to npm works. Changesets helps most repository users avoid ever having to think about these problems, however repository maintainers, especially those who want to customise how their releases work (for example those not using our [github action](https://github.com/changesets/action/)), may want to understand what it is solving for you.

diff --git a/docs/snapshot-releases.md b/docs/snapshot-releases.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/snapshot-releases
+
 # Snapshot Releases
 
 Snapshot releases are a way to release your changes for testing without updating the versions. Both a modified `version` and a modified `publish` command are used to do accomplish a snapshot release. After both processes run, you will have a published version of packages in changesets with a version of `0.0.0-{tag}-DATETIMESTAMP`.

diff --git a/docs/versioning-apps.md b/docs/versioning-apps.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This documentation is outdated. View the up-to-date version at https://changesets.dev/guide/beyond-npm
+
 # Managing applications or non-npm packages
 
 Changesets can also be used to manage application versions or non-npm packages (ie dotnet NuGet packages, ruby gems, docker images etc).

diff --git a/eslint.config.js b/eslint.config.js
@@ -10,10 +10,13 @@ import tseslint from "typescript-eslint";
 export default defineConfig(
   {
     ignores: [
-      "**/node_modules/**",
+      "**/*.{json,md}",
       "**/dist/**",
+      "**/coverage/**",
+      "**/node_modules/**",
       "site/.vitepress",
       "packages/cli/bin.js",
+      "site/.vitepress/cache/**",
       "**/*.snap",
     ],
   },
@@ -97,10 +100,18 @@ export default defineConfig(
       "import-lite/no-mutable-exports": "error",
     },
   },
+  {
+    files: ["site/.vitepress/theme/**"],
+    rules: {
+      "n/no-unsupported-features/node-builtins": "off",
+    },
+  },
   {
     files: [
       "**/index.ts", // to be removed in next release (v4) when we are dropping default export
-      "**/*.config.*", // config files often return default exports
+      "**/*config.*", // config files often return default exports
+      "site/**/*.data.ts",
+      "site/**/*.paths.ts",
     ],
     rules: {
       "import-lite/no-default-export": "off",

diff --git a/netlify.toml b/netlify.toml
@@ -0,0 +1,6 @@
+[build]
+publish = "site/.vitepress/dist"
+command = "pnpm build && pnpm site:build"
+
+[build.environment]
+NODE_VERSION = "24"
diff --git a/package.json b/package.json
@@ -15,10 +15,6 @@
     "type": "git",
     "url": "git+https://github.com/changesets/changesets.git"
   },
-  "workspaces": [
-    "packages/*",
-    "scripts/*"
-  ],
   "type": "module",
   "scripts": {
     "postinstall": "manypkg check",
@@ -32,6 +28,9 @@
     "test:fast": "vitest --tags-filter=!slow",
     "types:check": "tsc",
     "check-all": "pnpm build && pnpm test run && pnpm types:check && pnpm lint && pnpm format",
+    "site:dev": "pnpm --filter=./site dev",
+    "site:build": "pnpm --filter=./site build",
+    "site:preview": "pnpm --filter=./site preview",
     "version-packages": "changeset version && pnpm format:fix",
     "lint-staged:setup": "pnpm run --sequential \"/lint-staged:setup:\\d/\"",
     "lint-staged:setup:1": "git config set hook.\"lint-staged\".event pre-commit",