Skip to content

Latest commit

 

History

History

.changeset

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 

README.md

Changesets

This repository versions its distributed packages with Changesets. A changeset is a small Markdown file in this directory that names the packages a pull request changes, the bump each one needs, and a user-facing summary. changeset version folds pending changesets into CHANGELOG.md and package.json versions. pkg.pr.new publishes commit-addressed previews of the result.

Which packages get changesets

Package Path Status
agent-bundle packages/agent-bundle publishable
@agent-bundle/runtime packages/rsc-runtime publishable
rsc-markdown-stream packages/rsc-markdown-stream publishable
create-agent-bundle packages/create-agent-bundle publishable
agent-bundle-workbench packages/workbench private, ignored
@agent-bundle-example/*, @agent-bundle/rsc-agent-runtime-demo examples/* private, ignored
@agent-bundle/docs website private, ignored

Private packages are listed under ignore in config.json and are also excluded by privatePackages.version: false, so pnpm changeset never prompts for them and a changeset must never name them. The workspace root (agent-bundle-workspace) is not a workspace package and needs no entry. A change that only touches private packages, docs/**, agent-patterns/**, CI, or a publishable package's tests/** directory needs no changeset (changedFilePatterns in config.json exempts tests/**).

Rules

  • One changeset per pull request that changes a publishable package's shipped surface (src/**, bin/**, templates/**, package.json, README.md, build config). Name every affected package in that one file. Split a PR instead of writing several changesets for it; the rare exception is a PR that intentionally ships two independent user-facing changes.
  • Semver before 1.0: minor = breaking change (removed or renamed exports, CLI flags, config keys, diagnostic codes, on-disk formats, or changed defaults that require consumer action); patch = everything else, including new features. Do not use major until the first 1.0.0; after 1.0 the usual semver meanings apply.
  • Summary style: user-facing, imperative, one paragraph. Lead with what changes for the consumer, name the affected command, export, or config key, and mention diagnostic codes (AB + four digits, see docs/diagnostics.md) when a diagnostic is added, removed, or reworded. Do not describe the implementation, the review thread, or internal refactors that leave behavior unchanged. End with the pull request reference in parentheses, (#123), when the PR number is known.
  • Never edit CHANGELOG.md or a publishable package.json version by hand. The "Version Packages" pull request is machine-owned; it is regenerated on every push to main and any manual edit is overwritten.
  • skip-changeset label: a PR that changes publishable files but ships no observable change (comments, formatting, type-only refactors) may carry the skip-changeset label instead of a changeset. The Changeset present check honours the label; reviewers should challenge its use.

Writing a changeset

Run pnpm changeset and follow the prompts, or create .changeset/<slug>.md by hand:

---
"agent-bundle": patch
"create-agent-bundle": patch
---

`agent-bundle doctor` now reports `AB6026` when a Cursor hook manifest points
at a missing built script instead of failing silently; scaffolded projects
pick up the same check. (#123)

Use a descriptive kebab-case slug (the generated random names are fine too). Commit the file with the change it describes.

Enforcement

.github/workflows/changeset.yml runs pnpm changeset status --since=origin/main on every pull request. It fails when a publishable package changed (per changedFilePatterns) and the PR adds no .changeset/*.md. It is skipped for the skip-changeset label and for the machine-owned changeset-release/main branch of this repository (not for a fork or contributor branch of the same name). Docs-only PRs pass automatically because they change no publishable package.

Versioning decisions

  • agent-bundle and @agent-bundle/runtime version independently (fixed and linked are empty). agent-bundle declares @agent-bundle/runtime as an optional peer with range >=0.0.0 <1: the lower bound is the first runtime version that ships every subpath the generated code imports (mount, notices, notices/inbox-route, state, state/sqlite, flight/server, lineage), so a changeset that adds a runtime subpath the compiler emits must also raise that bound; the upper bound keeps a future 1.x runtime from satisfying a 0.x compiler. @agent-bundle/runtime does not depend on agent-bundle, so neither package needs to move when the other does. Preview tarballs pin the peer to the same commit (docs/preview-packages.md), which is a preview concern, not a version-coupling one. Revisit if the peer range ever becomes exact.
  • create-agent-bundle versions independently, but its optional workspace:* peers on agent-bundle and @agent-bundle/runtime are the release pairing record. pnpm pack rewrites them to the two exact published versions; the installed scaffolder reads that record instead of assuming the packages share a version.
  • updateInternalDependencies: "patch" with bumpVersionsWithWorkspaceProtocolOnly: true: only workspace: ranges between publishable packages trigger dependent patch bumps. The runtime's rsc-markdown-stream: workspace:^ edge republishes it with the renderer's new caret. The scaffolder's two optional workspace:* peers patch-bump and republish it whenever either member of its exact release pair moves.
  • access stays "restricted" at the repository level. It is harmless while Changesets only versions packages and pkg.pr.new is the distribution channel; no npm publish command consumes it.

Release flow

  1. PRs merge to main with their changesets.

  2. .github/workflows/release.yml runs changesets/action on every push to main. While changesets are pending it pushes changeset-release/main and opens or refreshes the Version Packages pull request, which deletes the consumed changesets, bumps versions, and writes CHANGELOG.md entries. Review it, never edit it. GitHub does not start workflows for events created with the built-in GITHUB_TOKEN, so for that PR to get PR CI the repository needs a CHANGESETS_GITHUB_TOKEN secret (fine-grained PAT or GitHub App installation token with contents: write and pull-requests: write on this repository). When the workflow falls back to GITHUB_TOKEN, it explicitly dispatches ci.yml (per-PR gates, including pnpm check:release:ci) and release-candidate.yml (the packed-release boundary, pnpm check:release) on the generated changeset-release/main branch after confirming the Version Packages PR exists, so no close/reopen is needed. Each dispatched run posts its verdict as a commit status on the candidate head (CI (Version Packages candidate), Release candidate (Version Packages candidate)), so the PR page and gh pr checks show the gate; do not merge a candidate whose statuses are missing or red. When a CHANGESETS_GITHUB_TOKEN is configured, that token's push to changeset-release/main starts release-candidate.yml directly.

  3. Merging Version Packages pushes a Version Packages commit to main with no pending changesets. The Release packages workflow first calls the reusable Package preview workflow, which runs pnpm preview:publish and verifies that all four package URLs resolve for the merge SHA. The release job depends on that proof and runs pnpm check:release; a green Version Packages run therefore means both the packed gates and the exact commit-addressed previews passed.

  4. Consumers pin the resulting artifacts as https://pkg.pr.new/ScriptedAlchemy/agent-bundle/<package>@<sha>. No npm registry credential is needed or expected.