yamcodes/arkenv/changeset

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

\* 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:

```markdown #### Remove the schema/define plugin API

The arkenv(schema) pattern has been dropped. Plugins now only accept transform options. ```

Bad (imperative body):

```markdown #### 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:
 

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:

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