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 convention

- **Format**: All changeset descriptions MUST start with a `####` header.
- **Mood**: You MUST use the **imperative mood** for all headers, change summaries, and actions. Write changesets as commands to the codebase (e.g. "Add helper...", "Fix issue...", "Drop support..." instead of "Adds...", "Fixed...", "Drops..."). Any changeset using indicative ("Adds/fixes") or past tense ("Added/fixed") is strictly invalid.

### 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 (remember to start with `####`)

### Manual method

Create a file in `.changeset/` with a random name:

````markdown
---
"arkenv": patch
---

From yamcodes/the-hat, MIT.

More from yamcodes/the-hat