changeset

Files (2)

• SKILL.md
• scenarios.md · references/

SKILL.md (first lines)

# 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

From yamcodes/arkenv, MIT.

More from yamcodes/arkenv