Changeset & release manager

Overview

Automate the creation and modification of changesets following project conventions, ensuring proper version bumps and well-documented release notes.

When to use

• After completing a feature or fix
• Before creating a PR
• When updating or correcting an existing changeset
• When preparing a release
• To document breaking changes

What is a changeset?

A changeset is a markdown file in the .changeset/ directory that describes:

1. Which packages are affected
2. What type of version bump (patch/minor/major)
3. A description of the change

Changeset types

Type	When to Use in v0 (Current)	When to Use in v1+
patch	Any non-breaking change (fixes, features)	Non-breaking bug fixes
minor	Breaking changes	Non-breaking new features
major	Switch to v1 (only when instructed)	Breaking changes

* In v0, minor is used for breaking changes, not features. ** In v0, major is used only when explicitly transitioning to v1.

Decision guide

Current Status: The ArkEnv monorepo is in v1 prerelease mode (alpha). All packages follow standard SemVer (v1+ rules).

Use patch for:

• Bug fixes
• Dependency updates (non-breaking)
• Performance improvements
• Code style/linting fixes
• Small documentation corrections

Use minor for:

• New features (new CLI commands, new configuration options, enhanced functionality, non-breaking API additions, etc.)
• New exports or public APIs
• Significant documentation improvements

Use major for:

• Breaking changes (any modification that requires consumers to change their code). You MUST include a **BREAKING CHANGE**: note at the bottom of the changeset with migration instructions.

Note: Purely internal refactorings (e.g., library switches, internal type cleanup) that offer no tangible benefit or change to the consumer should NOT be documented in a changeset. Do not clutter the changelog with changes that are meaningless to the end user.

v0 Rules (Legacy / Reference Only)

Use these rules only when working with packages still at 0.y.z that are not in v1 prerelease mode:

Use patch for:

• Any non-breaking change (including new features, bug fixes, dependency updates, performance improvements, etc.)

Use minor ONLY for:

• Breaking changes (Required in v0 for any breaking modification. You MUST prefix the description with **BREAKING CHANGE**:).

Use major ONLY for:

• Explicitly transitioning the project from v0.x.y to v1.0.0. Only use major when explicitly instructed to switch/transition to v1.

Decision guide (v1+ rules)

For packages in v1+ (e.g. active v1 branch):

Use patch for:

• Backward-compatible bug fixes
• Internal performance or refactor improvements with user value

Use minor for:

• Backward-compatible new features or API additions

Use major for:

• Breaking changes (Any change that breaks backward compatibility. You MUST prefix the description with **BREAKING CHANGE**:).

Creating a changeset

Title and body voice

• Format: All changeset descriptions MUST start with a #### header.

• Title mood: The #### header MUST use the imperative mood — a command to the codebase (e.g. "Add helper...", "Fix missing-schema errors...", "Remove the schema/define plugin API"). Indicative titles ("Adds...", "Removes...") and past-tense titles ("Added...", "Removed...") are invalid.

• Body mood: The paragraphs under the title are changelog copy for users, not commit-message commands. Prefer past tense or a present "now" statement (e.g. "The arkenv(schema) pattern has been dropped", "Removed the ambient helpers...", "Plugins now only accept transform options"). Do not write the body as imperative commands ("Drop X", "Replace Y", "Make Z"). Match the voice in existing CHANGELOG.md files.

  Good:

  #### Remove the schema/define plugin API
  
  The `arkenv(schema)` pattern has been dropped. Plugins now only accept transform options.
  

  Bad (imperative body):

  #### Remove the schema/define plugin API
  
  Drop `arkenv(schema)` and replace native-accessor reads with the env object.
  

Usage examples

Always include usage examples or code snippets when adding new features or fixing bugs that affect how the library is used.

Interactive method

pnpm changeset

Follow the prompts:

1. Select affected packages (space to select)
2. Choose bump type for each package
3. Write a summary of changes (imperative #### title; user-friendly past-tense / "now" body)

Manual method

Create a file in .changeset/ (at the root of .changeset/, not under .changeset/pre/) with a random kebab-case name:

---
"arkenv": patch
---

#### Add `arkenv` helper for improved type inference

The `arkenv` helper now infers types from your schema without extra annotation.

Usage:

```ts
import arkenv from "arkenv"
import { type } from "arktype"

export const env = arkenv({
  schema: {
    NODE_ENV: type("'development' | 'production' | 'test'"),
    PORT: type.number.parseable()
  }
})
```

Pending vs .changeset/pre/ (hard rule)

On v1 (and any branch in Changesets pre mode), two folders look similar but mean opposite things:

Path	Role	Who writes here
.changeset/<name>.md	Pending — not applied until changeset version (but changesets/action does read these to open/update the Version Packages PR)	You / agents on feature PRs
.changeset/pre/<name>.md	Consumed archive — already applied by a Version Packages PR	Only changeset version / the release bot

Never create, move, or commit a new changeset under .changeset/pre/. changesets/action / assemble-release-plan only treat root .changeset/*.md as pending. A file that lands only in pre/ is skipped (“No changesets found” when nothing else is pending) and will not bump packages or open/update a Version Packages PR (see the #2022 extractors miss, plus #2013 / #2014).

Also never hand-edit or delete files already in pre/ to “fix” a missed release — restore a copy as a new pending file under .changeset/ instead (or move an orphaned never-consumed file from pre/ back to .changeset/ in a dedicated fix PR).

Orphaned vs deliberate deferral: do not use pre/ as a holding pen. If a change should not release yet, do not add a changeset (or keep the PR unmerged). A file under pre/ that was added by a feature commit (not a Version Packages commit) is almost certainly an orphaned miss — move it back to .changeset/.

pre.json (mode / tag) is the pre-release channel config. It is unrelated to the pre/ directory of consumed markdown.

File format

---
"package-name": patch|minor|major
---

#### Imperative title of the change (e.g., "Add helper" — MUST be imperative mood)

A concise, user-facing description of what changed (past tense or present "now", not imperative). Keep it brief, avoid long prose, and provide code snippets/usage examples where helpful.

Include:
- **Usage examples** (code blocks)
- Bullet points for details (same body voice: "Added…", "The plugin now…")
- Migration instructions for breaking changes (using `major` bump and you MUST include a `**BREAKING CHANGE**:` note at the bottom)

**Note**: Do NOT reference GitHub issues (e.g., #123) or internal developer documentation (e.g., ADRs like "ADR 0021", internal RFCs, or private discussion threads) directly in the changeset. Changesets are external, consumer-facing release notes published in CHANGELOGs; all copy should focus entirely on user-observable behavior, syntax, and migration steps.
**BREAKING CHANGE**: Place migration instructions or descriptions of breaking changes (using the `**BREAKING CHANGE**:` label) at the **end** of the changeset. Keep it concise - 1-2 lines max, 3 lines absolute maximum. Prefer using ```diff blocks to visually demonstrate syntax/behavior changes. Write this note for users too (e.g. "The `arkenv(schema)` pattern has been dropped" rather than "Drop the `arkenv(schema)` pattern").

Modifying an existing changeset

When to modify

• The bump type is wrong (e.g., used minor for a patch-level change)
• The title is not imperative, or the body is written as imperative commands instead of changelog prose
• Usage examples are missing or incorrect
• The changeset references GitHub issues directly
• A change is documented that should be excluded (internal-only refactoring with no consumer value)
• Multiple related changes exist across separate changesets that should be combined

Process

1. Read the existing changeset file from .changeset/
2. Assess what needs to change: bump type, description, examples, or scope
3. Edit the file directly - changesets are plain markdown files
4. Remove the file entirely if the changeset no longer applies (e.g., the change was reverted)

Validation checklist after modification

• File path is .changeset/<name>.md — not .changeset/pre/<name>.md
• Bump type matches the decision guide (patch/minor for non-breaking, major for breaking)
• Title starts with #### header and uses imperative mood
• Body is user-facing changelog prose (past tense or "now"), not imperative commands
• Usage examples present for user-facing changes
• No GitHub issue references (# numbers) or internal documentation references (e.g. ADRs, internal RFCs)
• Breaking changes use major bump and include a **BREAKING CHANGE**: note at the bottom

Release workflow

1. Create or modify changeset

# Create
pnpm changeset

# Or modify manually
# Edit .changeset/<name>.md directly

2. PR and review

• Changeset is part of the feature PR targeting the dev branch
• Reviewers can suggest bump type changes or edits

3. Merge to dev

• Merging a feature PR containing a changeset to dev triggers the Changesets GitHub Action
• The action automatically creates or updates a "Version Packages" PR targeting the dev branch (since baseBranch is set to dev in .changeset/config.json)
• This "Version Packages" PR contains all accumulated version updates and CHANGELOG entries

4. Merge version PR

• Merging the "Version Packages" PR on dev triggers the publication of bumped packages to npm
• Upon successful publish, the release workflow programmatically fast-forwards the main branch to dev (git merge dev --ff-only) and pushes it
• The push to main refreshes the v0 docs archive (https://arkenv-v0.vercel.app), not Production
• Production / arkenv.js.org tracks v1 (vercel --prod via deploy-www.yml)

Pre-release versions

For managing alpha, beta, and release candidate (rc) pre-releases, we follow a strict versioning policy using the alpha ➔ beta ➔ rc progression.

To avoid duplication, the exact pre-release branching strategies, command workflows, and SemVer naming rules are documented in the Contributing Guide.

Checking status

# See what changesets exist
npx changeset status

# Preview version bump
npx changeset version --dry-run

# List all changeset files
ls .changeset/*.md

Common mistakes

Mistake	Issue	Fix
Wrong bump type	Unexpected version	Review decision guide above
Vague description	Poor CHANGELOG	Be specific about changes
Missing changeset	No release notes	Always add before PR
Writing under .changeset/pre/	Release ignores it (“No changesets found”); package never bumps	Put pending files only in .changeset/<name>.md. pre/ is the consumed archive.
Imperative body ("Drop X")	Reads like a commit, not a changelog	Rewrite in past tense / "now" for users
Past-tense title ("Removed…")	Title should be a command	Use imperative ("Remove…")
Not including context	Hard to understand	Explain why not just what
Meaningless changes	Cluttered CHANGELOG	Only document changes with consumer value
Including issue links	Redundant data	Remove # references; PR links them automatically
Referencing ADRs/internal docs	Unprofessional in consumer docs	Remove ADR / internal doc references; describe user-observable changes only

Common scenarios

For detailed examples of common scenarios including:

• Bug fixes, new features, breaking changes
• Multiple related changes
• Pre-release versions
• Best practices for descriptions

See Scenarios & Examples

References

• config.json - Changeset configuration
• CHANGELOG.md - Generated changelog
• Changesets docs: https://github.com/changesets/changesets

Related skills

• GitHub CLI: See gh-cli for GitHub-related tasks.
• Tackle Issue: See tackle-issue for the workflow of addressing issues.

Credits

This skill was originally created by Ollie Shop and sourced from github.com/ollieshop/creating-changesets.