changesets/changesets
github.com/changesets/changesets ↗ · 325 files · 1.9 MB
[!IMPORTANT] This is development branch for Changesets v3.
Overview
Changesets helps package maintainers record release intent as Markdown, calculate coordinated version changes across workspaces, generate changelogs, and publish through npm, pnpm, or Yarn. This pinned checkout is the v3 development branch, with a modular TypeScript release engine, an interactive CLI, and a Vue/VitePress documentation site. Its distinctive boundary separates contributor-authored changesets, calculated release plans, and registry-aware publish plans, including a pack-then-publish artifact workflow.
System map
The runtime consists of a Node CLI and separately published release-processing packages. Workspace discovery and configuration feed an in-memory planner, while application and publishing own filesystem and external side effects. The documentation site has a separate VitePress build and Netlify target. Repository scripts and GitHub workflows define distinct verification, preview, and release paths.
- The changeset executable enables Node's compile cache when available, imports @changesets/cli, then parses argv and awaits cli.runMatchedCommand(); ExitError controls the process exit code.
- cac registrations in cli.ts dynamically load implementations for init, add, version, publish, publish-plan, pack, status, git-tag, and pre; add is the default command.
- getReleasePlan composes workspace discovery, config validation, changeset reading, prerelease-state reading, and assembleReleasePlan without applying the resulting plan.
- assembleReleasePlan owns calculated release state; applyReleasePlan owns manifest/changelog writes and changeset cleanup, returning touched paths for the CLI's optional commit step.
- Publishing crosses into package-manager subprocesses through PublishTool.info, pack, and publish; getPublishTool selects npm, version-aware pnpm, or Yarn Berry and rejects Yarn Classic.
- pnpm workspaces include packages, scripts, and site; tsdown builds package entrypoints as ESM with declarations and publint, and apply-release-plan publishes only its dist directory.
- Root scripts expose bootstrap, build, Vitest, separate E2E testing, TypeScript checking, ESLint, oxfmt, and check-all; the package manager is pinned to pnpm 11.13.1.
- Netlify builds packages and the VitePress site on Node 24; GitHub release automation separates mode selection, version PR creation, packing, and publishing, while labeled PRs can trigger pkg-pr-new previews.
Feature catalog
The CLI covers release setup, contributor input, release inspection, version application, artifact creation, and publication. Configuration controls coordinated groups, skipped/private packages, formatting, and generators. Prereleases and snapshots have explicit mode restrictions. The public documentation adds searchable guides, generated CLI help, and selected package references.
- init interactively chooses GitHub changelogs, automatic commits, access, and base branch, then writes .changeset/config.json and copies a README; an existing config makes it return early.
- add supports interactive package/bump selection, explicit --major/--minor/--patch lists, --message, --empty, best-effort changed-package suggestions, and opening the created file in an editor.
- version applies package versions, internal dependency ranges, and changelogs; fixed groups release together, linked groups coordinate released versions, and config controls ignored/private packages and workspace-only range handling.
- status supports --since, verbose release details, and JSON output; it exits with an error when changed versionable packages exist but the assembled plan contains no changesets.
- pre enter/exit persists prerelease mode and tag; version also supports snapshots with configurable tag/time/commit suffixes, defaults their base to 0.0.0, and rejects snapshots in active prerelease mode.
- publish-plan identifies registry-unpublished versions and optional private-package tags; pack writes tarballs plus publish-plan.json, and publish can consume that directory but rejects a custom tag in artifact mode.
- publish exposes OTP, dist-tag, artifact-directory, and Git-tag controls; git-tag is also standalone, and its older tag alias emits a deprecation warning.
- The site offers local search, Guide/FAQ/Blog navigation, generated CLI help, and sidebar-selected package reference pages; GitHub changelogs add PR/commit/author links, issue references, and optional templates.
Data flow
Release intent enters through CLI selections or editable changeset files. Schema validation and workspace discovery normalize configuration before the planner builds package-indexed state. Version application persists calculated results, while publishing independently compares current manifests against registry state. Artifact and reporting files are additional output boundaries with different formats and trust assumptions.
- normalizeOptions expands comma-separated bump/ignore values, removes aliases, keeps the last repeated scalar, and converts numeric-looking options to strings; CHANGESETS_OUTPUT supplies missing output paths.
- readConfig loads config.json from the discovered workspace root; validateConfig applies Valibot parsing, normalizeWrittenConfig, and package-aware validation rules before returning config or errors.
- writeChangeset converts releases and summary into quoted YAML frontmatter plus Markdown, assigns a human-readable ID, writes .changeset/<id>.md, and invokes the configured/detected formatter.
- readChangesets combines root and pre-directory Markdown, optionally filters by Git ref, excludes hidden/helper files, and returns parseChangesetFile results with path-derived IDs; parsing validates release names and types.
- flattenReleases builds a package-to-release Map, retains every contributing changeset ID, and selects the highest bump; assembleReleasePlan repeatedly mutates that state through dependents, fixed constraints, and links.
- applyReleasePlan attaches Git commit metadata for changelog generators, edits package and root dependency fields, formats changelogs, then archives active-prerelease changesets or removes consumed ordinary changesets while preserving skipped ones.
- getUnpublishedPackages queues registry info calls, compares local versions against published versions, assigns access/tag, and sortReleases produces dependency-ordered chunks excluding dev dependencies; shared limits are 40 registry requests and 10 publishes.
- pack records relative tarball paths and SHA-256 integrity in a versioned JSON plan; publication resolves those paths, while Git-tag reporting appends NDJSON events and flushes the stream on async disposal.
Behavior traces
The inspected startup, add, version, and publish paths connect concrete command dispatch to their terminal effects. Additional traces cover status, prerelease persistence, and packing. These are source-derived execution sequences, not observed runtime results. Branches around skipped packages, prerelease state, authentication, and partial publication materially change the sequence.
- Startup: bin.js imports the CLI → index.ts calls cli.parse(run:false) → enables interactive guidance for TTY add/publish → displays the version intro → awaits runMatchedCommand; command actions import handlers lazily.
- Add: getPackages → ensureChangesetFolder → readConfig → filter versionable packages → best-effort getVersionableChangedPackages → createChangeset or empty intent → writeChangeset → optional getAddMessage/Git commit → optional launchEditor.
- Version: discover packages/read config → validate ignore names and skipped dependents → readChangesets/readPreState → reject snapshot/pre conflicts or absent intent → assembleReleasePlan → applyReleasePlan → optionally stage touched paths sequentially and commit.
- Planner: getRelevantChangesets rejects unknown packages and mixed skipped/non-skipped intent → getPreInfo → flattenReleases → build dependents graph → repeat determineDependents/matchFixedConstraint/applyLinks until stable → calculate output versions.
- Status: getPackages/readConfig → readPreState/readChangesets → assembleReleasePlan → detect changed packages → enforce presence of changesets → either serialize the release plan or print sorted bump groups and optional IDs/new versions.
- Prerelease persistence: enterPre writes mode/tag → version application moves consumed files into .changeset/pre → active-pre assembly excludes archived IDs → exitPre writes mode:exit → the next application removes pre.json and consumes releasable archived intent.
- Pack: discover/read config → read supplied plan or compute getPublishPlan → create output/packages → queue publishTool.pack calls → hash each returned tarball → attach metadata to original chunks → write publish-plan.json; Yarn rejects publishConfig.directory.
- Publish: create reporter/discover adapter → load or compute plan → process dependency chunks → use TTY sequential probing or bulk publishing → recover eligible 2FA failures interactively → tag successes/tag-only entries → exit 1 for recorded failures.
Testing signals
Tests and CI were inspected, not executed; this report contains no passing test result or measured coverage percentage. Vitest covers planner logic, filesystem application, config rules, and mocked publication behavior. A separate E2E workspace exercises real CLI/package-manager processes against test infrastructure. Inspection is bounded, and explicit TODOs and fixture constraints limit what test existence establishes.
- Root Vitest excludes scripts/e2e, clears/restores mocks, and defines slow-test timeouts; the separate E2E config has its own timeout and both configurations allow focused tests.
- Planner tests use FakeFullState and assert basic releases, snapshot formats, maximum-bump merging, and transitive dependent updates; these assertions were read, not executed.
- apply-release-plan tests create filesystem fixtures, resolve built CLI generator paths, invoke applyReleasePlan, and assert exact manifest text preservation; duplicate-package-plan rejection remains an it.todo case.
- Config tests assert duplicate fixed/linked-group errors and skipped-dependent validation with a private-package exception; schema tests compare generated JSON against tracked schema.json.
- Publish unit tests mock Git and tinyexec, assert dependency-first invocation/tag ordering, and simulate expired-OTP recovery back to bulk mode; they do not exercise real authentication in those cases.
- Pack E2E tests explicitly use precomputed plans to avoid registry dependence, assert tarball/metadata output, exercise lifecycle stdout, and require a failed lifecycle to leave no publish-plan.json.
- The publish E2E OTP case runs a TTY CLI against a configured test registry, submits a fixture OTP, and checks failed/successful PUT requests; E2E dependencies include npm 10–12, pnpm 10–12, Yarn 4, and a PTY library.
- Inspected CI builds before tests, runs Node 22/24/26 on Ubuntu and Node 24 on macOS/Windows, uploads Ubuntu/Node-24 coverage, and separately runs E2E/type/lint/format checks; root check-all does not include E2E or site builds.
Risk map
These are source observations and narrowly labeled hypotheses, not confirmed vulnerabilities. Sensitive boundaries include configured executable modules, package-manager subprocesses, caller-selected paths, Git writes, and authenticated GitHub requests. Release application and publication can leave partial effects when later operations fail. Artifact validation and compatibility assumptions deserve focused verification before broader reliance.
- Configured changelog and commit modules are dynamically imported from the consumer's .changeset context with a CLI-context fallback; configuration therefore selects executable code in the invoking process.
- readPlanFile checks only the outer object, plan array, and version; artifact publishing then trusts entry fields and resolves tarball paths, without checking the integrity metadata in the inspected publish path.
- The publish-plan source explicitly documents that registry identity is omitted and planning/publishing require matching configuration; pnpm and Yarn info queries use fetch-registry behavior rather than publishConfig.registry overrides.
- applyReleasePlan writes manifests/changelogs sequentially before formatting and changeset cleanup, with no rollback in that sequence; later failures can leave earlier writes. Publishing similarly retains successful publications and tags when another package fails.
- readPreState parses JSON without structural validation and may migrate v2 state by renaming changesets and rewriting pre.json; callers such as status can therefore mutate legacy state through a read-named API.
- npm pack/publish delegate lifecycle execution to an external CLI; publish passes OTP as an argument and inherits other environment values after clearing OTP variables. pack/output paths and publishConfig.directory are caller/config-selected filesystem boundaries.
- GitHub helpers can read a consumer-cwd .env and send GITHUB_TOKEN to configured GITHUB_GRAPHQL_URL; changelog commit lookup may deepen shallow clones through git fetch. These are network/credential boundaries visible in source, not actions performed in this investigation.
- Two reporting compatibility hypotheses need reproduction: createGitTags records success without checking git.tag's false result, and release-utils.runPublish still extracts 'New tag:' text while current CLI tag formatting emits 'Created git tags:'. (inferred)
Extension points
The primary extension mechanisms are configurable generator modules and internal command/adapter tables. Shared types separate contributor intent, calculated releases, and publication results. Config rules and schema generation provide coordinated validation hooks. Documentation generation also plugs into CLI registrations and package sidebar entries.
- New CLI behavior belongs in cac command registrations with normalization and lazy handler imports; the existing command table demonstrates array-valued options, aliases, examples, and required-option checks.
- Changelog plugins implement getReleaseLine and getDependencyReleaseLine, may return promises, and receive configured options; the loader requires both functions and handles default-export interoperability.
- Commit plugins expose getAddMessage and/or getVersionMessage; config accepts booleans, module strings, or module/options tuples, with true normalized to the built-in commit generator.
- PublishTool is the internal adapter contract for info, pack, publish, and OTP extraction; adding a manager requires changing its name union and getPublishTool selection, not registering an arbitrary external plugin.
- WrittenConfigSchema defines accepted options/defaults, normalizeWrittenConfig reconciles alternate forms, and the rules array runs package-aware checks over one shared errors/warnings context.
- Configuration schema changes feed generateJsonSchema, which converts WrittenConfigSchema to draft-2020-12 JSON and writes schema.json; a file-snapshot test checks generated/schema alignment.
- Release policy helpers plug into assembleReleasePlan's stabilization loop; changes to dependent propagation, fixed constraints, or links must preserve their mutation/change-reporting contract and final version computation.
- Documentation extensions use VitePress sidebar entries and package README/manifest generation; CLI reference help comes from helpMessageTasks invoking the same CLI parser, while package builds inherit shared tsdown configuration.
Contributor handoff
Tests and CI were inspected, not executed, and the findings are a bounded onboarding map rather than exhaustive coverage or a verification certificate. Start with the relevant command, shared contracts, and side-effect-owning package before changing behavior. Preserve distinctions between release planning, filesystem application, and registry publication. Future checks must respect task authorization because several apparently convenient APIs or scripts perform writes, subprocess execution, or remote operations.
- Treat this checkout as v3 development, verify behavior against local source, and use the pinned pnpm/Node requirements; README explicitly points v2 users to a different maintenance branch.
- Read cli.ts plus the affected handler and shared types first; ReleasePlan and PublishPlan are different contracts, with the latter carrying ordered publish/tag-only chunks rather than proposed bumps.
- Keep semver-policy changes in assembly helpers and manifest edits in apply-release-plan; retain dev-dependent none releases and file/link/workspace range exceptions instead of treating every dependency edge as a version bump.
- Configuration changes should update WrittenConfig/Config, WrittenConfigSchema, normalization/rules, and generated schema together; schema snapshot tests are the narrow alignment check.
- Build before authorized tests that resolve dist generators: the apply-release-plan suite references built CLI changelog/commit files, and CI supplies build artifacts before test jobs. Then target the affected Vitest file before broader root checks.
- E2E is separately bootstrapped, excluded from root test/typechecking, and requires Node 24 or newer; use the relevant pack/publish suite for authorized adapter work instead of assuming check-all includes it.
- Follow explicit .ts ESM imports, inline type-import conventions, and == null checks; named exports are preferred, but index/config exceptions retain default exports for compatibility.
- For read-only investigations inspect tests/CI without executing them: readPreState may rewrite legacy files, runVersion resets/commits/force-pushes, and runPublish invokes an arbitrary command then pulls/pushes; these APIs are not safe inspection helpers.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 162 | 97% |
| Markdown | 87 | docs/config |
| JSON | 31 | docs/config |
| YAML | 12 | docs/config |
| JavaScript | 2 | 1% |
| Vue | 2 | 1% |
| CSS | 1 | docs/config |
| TOML | 1 | 1% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (212 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/apply-release-plan/ | 13 |
packages/assemble-release-plan/ | 16 |
packages/changelog-git/ | 4 |
packages/changelog-github/ | 8 |
packages/cli/ | 63 |
packages/color/ | 2 |
packages/config/ | 14 |
packages/errors/ | 6 |
packages/get-dependents-graph/ | 7 |
packages/get-github-info/ | 12 |
packages/get-release-plan/ | 5 |
packages/get-version-range-type/ | 6 |
packages/git/ | 6 |
packages/logger/ | 6 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 212 |
site/ | 49 |
docs/ | 18 |
scripts/ | 11 |
assets/ | 10 |
.github/ | 7 |
.changeset/ | 2 |
wiki/ | 1 |
Docs found: README.mddocs/adding-a-changeset.mddocs/automating-changesets.mddocs/checking-for-changesets.mddocs/command-line-options.mddocs/common-questions.mddocs/config-file-options.mddocs/decisions.mddocs/detailed-explanation.mddocs/dictionary.md
Package
package.json — @changesets/repository v1.0.0, 24 declared dependencies.
@changesets/changelog-github@changesets/cli@e18e/eslint-plugin@eslint/js@manypkg/cli@oxc-node/core@tsconfig/node22@tsconfig/node24@types/node@types/semver@vitest/coverage-v8@vitest/eslint-plugin
CI & config entrypoints
README.md— Repository readme.github/workflows/pkg-pr-new.yml— GitHub Actions workflow.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflowpackage.json— npm scripts: bootstrap, bootstrap:e2e, build, check-all, format, format:fix, generate-json-schema, lintsite/package.json— npm scripts: build, dev, generate-og, previewpackages/config/package.json— npm scripts: generate-json-schemascripts/e2e/package.json— npm scripts: test, types:check
Structural health signals
Average score 9.1/10 across 96 analyzed source files; 0 hotspots surfaced.
packages/cli/src/commands/publish/index.ts— 421 lines, score 6.9 (Deep nesting, Long function/block)packages/assemble-release-plan/src/determine-dependents.ts— 228 lines, score 6.9 (Deep nesting, High churn)packages/get-github-info/src/dataloader.ts— 237 lines, score 7.1 (High churn, No adjacent test signal)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
c73949ba7b312026-09-22 — Build(deps-dev): Bump unplugin-icons from 23.0.1 to 24.0.0 (#2314)70908e66a7cb2026-09-21 — Build(deps-dev): Bump the development-dependencies group with 7 updates (#2312)a4aae931d2862026-09-21 — Build(deps): Bump the github-actions group with 5 updates (#2310)c9269c01af5f2026-09-14 — Version Packages (#2291)ca9d1103c2092026-09-14 — Fix pnpm 10 publishing with npm 12 (#2276)