changeset
/changeset
Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes.
- Author
- yamcodes ↗
- Repository
- arkenv ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes.
Original author description
Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes.
How it works
- Overview
- When to use
- What is a changeset?
- Changeset types
- Decision guide
- v0 Rules (Legacy / Reference Only)
- Decision guide (v1+ rules)
- Creating a changeset
- Modifying an existing changeset
- Release workflow
SKILL.md preview
---
name: changeset
description: Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes.
metadata:
author: Yam C Borodetsky
original_author: Ollie Shop
origin: github.com/ollieshop/creating-changesets
version: 1.1.0
internal: true
---
# 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:
```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
```bash
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:
````markdown
---
"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
```markdown
---
"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
```bash
# 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](file:///Users/yamcodes/code/arkenv/docs/CONTRIBUTING.md#use-case-4-coordinating-a-major-version-eg-v1).
## Checking status
```bash
# 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/scenarios.md)**
## References
- [config.json](file:///.changeset/config.json) - Changeset configuration
- [CHANGELOG.md](file:///CHANGELOG.md) - Generated changelog
- Changesets docs: [https://github.com/changesets/changesets](https://github.com/changesets/changesets)
## Related skills
- **GitHub CLI**: See [gh-cli](../gh-cli/SKILL.md) for GitHub-related tasks.
- **Tackle Issue**: See [tackle-issue](../tackle-issue/SKILL.md) for the workflow of addressing issues.
## Credits
This skill was originally created by [Ollie Shop](https://github.com/ollieshop) and sourced from [github.com/ollieshop/creating-changesets](https://github.com/ollieshop/creating-changesets).
Files in this package (2)
- SKILL.md 14 KB
- references/scenarios.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · yamcodes/arkenv | 100 | MIT |
| withastro/astro | 100 | MIT |
| sl-design-system/components | 100 | Apache-2.0 |
| ShepardVasNormandy/claude-skills | 100 | MIT |
| modem-dev/ossrules | 100 | MIT |
| tuanductran/hr-skills | 100 | MIT |
| stormix/transcripts-mcp | 100 | MIT |
| udecode/kitcn | 96 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 04fc72565181 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100creating-changesets
Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes. - 100changesets
Write the changeset for a change in a repo that releases with changesets (a `.changeset/` folder exists). The bump level follows one question, whether the thing existed before: patch for changed behavior, minor for something new, major only with the maintainer's approval. Use… - 100pr-changeset
Create changesets for package changes in pull requests. Invoke whenever any file under packages/* is modified — including bug fixes, new features, and even documentation or typo changes. Changesets are required before committing; without one, the release pipeline won't know what… - 100writing-changesets
Use when writing a changeset, or before filing a PR in a repository that uses changesets. - 100changesets
How to write changesets in the Portable Text Editor monorepo. Use whenever adding a .changeset/*.md file or deciding whether a change needs one. Covers bump selection (patch/minor/none), the subject-mirrors-commit rule, consumer-facing prose style, and API changesets, with real… - 100pr-changeset
Create changesets for package changes in pull requests. Invoke whenever any file under packages/* is modified — including bug fixes, new features, and even documentation or typo changes. Changesets are required before committing; without one, the release pipeline won't know what…