Add Changeset
Developmentadd-changesetAdd Changeset is an Agent Skill for development published in the swc-project/swc repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create SWC changeset files for pull requests. Use when asked to add a changeset, prepare release notes, decide patch/minor/major bumps, or enumerate changed Rust crates for an SWC PR; the skill requires every publishable Rust crate with a breaking change or a runtime dependency breaking change to be listed as major, every other changed publishable Rust crate to be listed as patch or minor, and swc_core to be listed as at least patch for Rust crate changes.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/swc-project/swc/blob/HEAD/.agents/skills/add-changeset/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-changeset, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add Changeset
Goal
Add one Markdown file under .changeset/ whose front matter lists every changed publishable Rust crate in the PR, plus swc_core when any Rust crate changes.
Workflow
-
Find the PR base and changed files.
- Prefer
gh pr view --json baseRefName,headRefName,bodywhen the branch has a GitHub PR. - Use
git diffagainst the PR merge base; include staged and unstaged local changes when preparing an unpushed PR. - Run
scripts/changed-rust-crates.mjsfrom this skill to get a first pass of directly touched Rust crates.
- Prefer
-
Read the code, not only the helper output.
- Inspect every changed Rust crate reported by the helper.
- Inspect root workspace changes such as
Cargo.toml,Cargo.lock,rust-toolchain,.cargo/, and release tooling manually; they may affect crates without changing files inside the crate directory. - Ignore non-publishable workspace crates in changeset front matter unless the maintainer explicitly asks otherwise; SWC's release tool skips
publish = falsecrates.
-
Classify every changed publishable Rust crate.
- Use
majorfor every crate whose public API, behavior contract, feature semantics, serialized output, CLI-visible behavior, or documented compatibility is breaking. - Use
majorfor a crate when one of its runtime dependencies changed in a breaking way. Check that crate's[dependencies], target-specific runtime dependencies, and relevantCargo.lockchanges; do not apply this rule to dev-only or build-only dependencies. - Do not expand
majorthrough SWC's reverse internal dependency graph just because another crate depends on a breaking crate; SWC's bump command handles that internal propagation after reading the changeset. - Use
minorfor non-breaking new public functionality, new supported syntax, new options, new public exports, or meaningful user-visible capability. - Use
patchfor bug fixes, performance work, refactors, internal-only changes, tests, fixtures, documentation, or dependency bumps that do not add a non-breaking capability. - If a crate has both breaking and non-breaking changes, list it once as
major.
- Use
-
Check
swc_coreexposure explicitly.- If a changed crate's breaking API is re-exported by
swc_coreor exposed through aswc_corefeature, listswc_core: major. - If a changed crate adds non-breaking public API that
swc_coreexposes, listswc_core: minor. - If
swc_corefiles or feature mappings changed directly and the change is not breaking or additive, listswc_core: patch. - If any publishable Rust crate is listed and no stronger
swc_corebump is required, includeswc_core: patcheven whenswc_corefiles did not change.
- If a changed crate's breaking API is re-exported by
-
Write the changeset.
- Create a new file at
.changeset/<short-kebab-summary>.md. - Keep the front matter sorted by crate name unless a maintainer provided another order.
- Mention only Rust crate names and bump levels in front matter.
- Write a concise summary after the front matter using SWC commit style, such as
fix(es/parser): ...,feat(es/parser): ...,perf(es/parser): ..., orrefactor(es/parser): ....
- Create a new file at
Example
---
swc_core: minor
swc_ecma_parser: minor
---
perf: Optimize es parser comment finalization
Helper
Run this helper from the repository root:
node .codex/skills/add-changeset/scripts/changed-rust-crates.mjs
Useful options:
node .codex/skills/add-changeset/scripts/changed-rust-crates.mjs --base origin/main
node .codex/skills/add-changeset/scripts/changed-rust-crates.mjs --json
node .codex/skills/add-changeset/scripts/changed-rust-crates.mjs --include-private
Treat the helper as an inventory aid. It does not decide breaking changes, does not understand public API exposure, and cannot fully interpret workspace-level changes.