# Prepare Release

> Prepare a CLI11 release — changelog entry, version bump, README feature markers, and related version references.

- Skill: `cliutils/prepare-release` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cliutils/prepare-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cliutils/prepare-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cliutils (https://skillmd.com/u/cliutils)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cliutils/prepare-release

---


# Prepare a CLI11 release

When preparing a release (`chore: prepare X.Y.Z release`):

## Collect the changes

List the merged PRs since the last release with
`git log --oneline --first-parent v<last>..main`. Every user-visible change gets
a changelog line.

## Changelog entry

Add a `## Version X.Y.Z: <Short title>` section at the top of `CHANGELOG.md`.
The heading becomes the name of the GitHub release, so give it a short title,
such as `## Version 2.7.0: Audit and documentation`.

- Start with a short prose paragraph that summarizes the release.
- Group the entries under `### Added`, `### Changed`, `### Fixed`,
  `### Documentation`, and `### Internal` (and `### Removed`/`### Deprecated` if
  needed). `Documentation` covers docs-only changes; `Internal` covers CI,
  tests, and tooling changes with no user-visible effect.
- Reference PRs as `[#1305][]` and put the matching link definitions
  (`[#1305]: https://github.com/CLIUtils/CLI11/pull/1305`) at the end of the
  version section — each section keeps its own definitions so an extracted
  section needs no fixup.

## Version bump

Bump `include/CLI/Version.hpp`: the `CLI11_VERSION_MAJOR`/`MINOR`/`PATCH` macros
and the `CLI11_VERSION` string.

## Other files

- Only if not a patch release: Update the feature markers in `README.md`: remove
  the old 🆕 markers (the previous release's features) and change 🚧 markers
  (main-only features) to 🆕. Removing an emoji from a heading also changes its
  TOC anchor — drop the trailing `-` from the matching TOC links.
- Check the copyright year in `LICENSE` and the version in
  `book/chapters/installation.md`.

## Verify

CI extracts the release notes from the changelog on every build, so a version
bump without a matching changelog section fails. Check locally:

```bash
python3 scripts/ExtractReleaseNotes.py --title "$(python3 scripts/ExtractVersion.py)"
python3 scripts/ExtractReleaseNotes.py "$(python3 scripts/ExtractVersion.py)"
```

## After the PR merges

Tell the user to tag the merge commit as `vX.Y.Z` and push the tag. CI then
creates the GitHub release: the name comes from the changelog heading, the body
from the changelog section, and the single header plus source packages are
attached automatically.