---
title: "Releases and Changelogs"
description: "Skillset releases plan and apply workspace versions, changelogs, release evidence, and generated updates."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus.focal.host/llms.txt
> Use this file to discover all available pages before exploring further.

# Releases and Changelogs

<a id="releases-and-changelogs"></a>

<!-- skillset:generated:start feature-support -->
| Feature | Feature status | claude | codex | cursor |
| --- | --- | --- | --- | --- |
| `releases` | `implemented` | `metadata_only` | `metadata_only` | `metadata_only` |
<!-- skillset:generated:end feature-support -->

Support vocabulary: [Feature Reference](/skillset/reference/features/#support-vocabulary)

A [workspace](/skillset/glossary/#workspace) release turns accepted [source-change](/skillset/reference/features/changes/) reasons into stable [source-unit](/skillset/glossary/#source-unit) versions, generated changelogs, append-only release evidence, updated locks, and refreshed provider output. It does not publish a package, sync a distribution, install output, or prove [activation](/skillset/glossary/#activation).

## Plan Before Applying

```bash
skillset release plan
skillset release apply
skillset release apply --yes
```

`plan` and an unconfirmed `apply` write nothing. The plan shows selected pending reasons, ignored audit entries, release scopes, version changes, and source hashes. Confirmed apply consumes all eligible pending reasons; release commands reject build `--scope` because scoped release selection does not exist.

The [publishing guide](/skillset/guides/publishing/) owns the end-to-end workflow. The generated [`release` reference](/skillset/reference/cli/release/) owns exact command syntax.

## What Apply Writes

A confirmed release with at least one entry to apply:

- folds pending event files from `.skillset/changes/events/` into `.skillset/changes/ledger.jsonl` and removes them;
- appends `release.applied` evidence to `.skillset/changes/ledger.jsonl`;
- moves applied reasons into append-only history and appends release records;
- advances source-unit version authority and records deletion tombstones;
- regenerates entity-local `CHANGELOG.md` [projections](/skillset/glossary/#projection);
- refreshes generated provider versions, output, and locks.

With no entry to apply, `release apply` writes nothing. Events that lifecycle commands such as `draft` record without a change entry stay in their pending files, where readers still fold them, until the next release that has an entry folds them in.

Release state wins over inline source versions when a release scope exists. Otherwise inline metadata remains the import/read fallback. Pending reasons never appear as a pending section in committed changelogs. Cached `.skillset/changes/state.json` is published atomically so readers observe a complete previous document or a complete replacement.

## Correct Wording Without Editing Generated Changelogs

| Timing | Intent | Command |
| --- | --- | --- |
| Before release | Change pending changelog wording | `skillset change reason <@ref> --reason "…"` |
| After release | Correct an applied source-change reason | `skillset change amend <@ref> --reason "…"` |
| After release | Correct release-event notes | `skillset release amend <@ref> --reason "…"` |

Amendments append evidence and leave original history auditable. Rebuild after the correction to refresh the generated changelog.

## Errors and Recovery

| Problem | Result | Recovery |
| --- | --- | --- |
| No pending eligible reasons | Plan reports no release | Add or correct change coverage |
| Stale source evidence | Apply refuses | Run `change check` and review `change refresh` |
| Invalid or corrupt release state | Validation fails before output writes | Repair source-side state from trusted ledger/history evidence |
| Generated changelog was edited | Output checks refuse to treat it as source | Use the correction table above |
| `--scope` is supplied | Command rejects it | Apply the complete release or defer it |
| Output collision or target-side edit | Build safety creates a backup or refuses | Follow [Output Safety](/skillset/reference/features/output-safety/) |

An ignored change stays auditable but contributes no version bump or changelog entry. Its source hash is still recorded at apply so status does not repeatedly report the dispositioned edit.

## Separate Release Authorities

Skillset workspace releases own `.skillset/changes/`, source-unit versions, and entity changelogs. Changesets owns versions and changelogs for the public npm packages. Distribution plans and marketplace indexes are separate delivery evidence. Completing one lane does not authorize another; see [Package Releases](https://github.com/outfitter-dev/skillset/blob/24800e02ed4e7150ea1bc7130c35603c98ea9da2/docs/development/package-releases.md).

## Provenance

Release records include selected change ids, resolved versions, source hashes, and baseline metadata. Deleted scopes become tombstones. `skillset change status` uses ledger-derived release state as its durable baseline, even before the release commit exists.

Release records are append-only and derived release state resolves per scope in file order, so keep `.skillset/changes/*.jsonl` on the `merge=union` strategy described in [Merging Change Streams](/skillset/reference/features/changes/#merging-change-streams).

See [Source Change, Release, and Dependency Provenance](https://github.com/outfitter-dev/skillset/blob/24800e02ed4e7150ea1bc7130c35603c98ea9da2/docs/adrs/0014-source-change-release-provenance.md), [Changelog and Version Bump Workflow](https://github.com/outfitter-dev/skillset/blob/24800e02ed4e7150ea1bc7130c35603c98ea9da2/docs/adrs/0013-changelog-and-versioning.md), and [Reason-Only Change Ledger and Derived State](https://github.com/outfitter-dev/skillset/blob/24800e02ed4e7150ea1bc7130c35603c98ea9da2/docs/adrs/0015-reason-only-change-ledger-derived-state.md).

Source: https://nimbus.focal.host/skillset/reference/features/releases/index.mdx