Skip to content
Skills Library
Programming · Writing

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.

Repository
arkenv ↗
Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. When to use
  3. What is a changeset?
  4. Changeset types
  5. Decision guide
  6. v0 Rules (Legacy / Reference Only)
  7. Decision guide (v1+ rules)
  8. Creating a changeset
  9. Modifying an existing changeset
  10. Release workflow
Original SKILL.md headings · 309 lines, 1,984 words
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

RepositoryScoreLicence
This page · yamcodes/arkenv100MIT
withastro/astro100MIT
sl-design-system/components100Apache-2.0
ShepardVasNormandy/claude-skills100MIT
modem-dev/ossrules100MIT
tuanductran/hr-skills100MIT
stormix/transcripts-mcp100MIT
udecode/kitcn96Apache-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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.