package-release

Files (1)

• SKILL.md

SKILL.md (first lines)

# Package Releases

Release notes are user documentation. `CHANGELOG.md` is their canonical source. Never invent a second narrative during publication.

## Classify the request

- **Update the changelog** — edit `Unreleased` only. Do not bump, tag, push, or publish.
- **Prepare a release** — bump/align versions, roll the changelog, validate, and stop before irreversible actions.
- **Release / publish / ship** — complete every applicable release output: package, package documentation, tag, GitHub Release, and public verification. Do not stop after publishing only one artifact.
- **Repair a release** — derive missing or corrected metadata from the tagged changelog; do not generate replacement prose.
- **Deploy** — this skill does not define application deployment. Clarify when “release” could mean an OTP/app deployment rather than a package version.

A direct request to release, publish, ship, or cut a version authorizes the complete workflow after a clean preflight. Ask only when the version or intent is ambiguous, repository state is unexpected, project instructions require confirmation, or authentication/2FA is needed.

## Non-negotiable release-note contract

- GitHub Release title is exactly the tag, normally `vX.Y.Z`.
- GitHub Release body is exactly the body of the matching `CHANGELOG.md` version section, excluding the level-two version heading.
- Do not add an opening summary, closing sentence, generated prose, commit list, contributor list, checksum, or publication status.
- Do not add Install/Installation sections or dependency snippets.
- Do not append Hex, HexDocs, npm, crates.io, changelog, compare, marketing, or “full changelog” links.
- Never use generated GitHub notes (`--generate-notes`).
- Never embellish terse changelog notes.
- Always pass multiline notes through a file with `--notes-file`; never inline Markdown in `--notes` or a shell string.
- Never use regex, `awk`, or `sed` to determine Markdown section boundaries. Read the Markdown structure directly or use the repository’s canonical parser/extractor.
- Preserve directly relevant issue, pull-request, migration, or security links already present in the canonical changelog. Do not add links during release publication.

## Changelog audience

Every entry must answer:

> What changed for a package user deciding whether or how to upgrade?

Include:

- New public behavior or APIs
- Changed behavior
- User-visible bug fixes
- Observable performance improvements
- Compatibility and platform changes
- Deprecations, removals, security changes, and migration requirements

Exclude:

- Test additions, test counts, CI status, or quality-gate output
- Corpus, calibration, benchmark-gate, precision-ratchet, or release-gate results
- Checksums, publication status, and generated documentation status
- Local paths, path dependencies, dogfooding setup, and maintainer workstation state
- Release preparation and internal workflow changes
- Internal refactors without a user-visible outcome
- Dependency/lockfile updates without compatibility, security, or behavioral impact
- Temporary operational details and implementation-specific validation

Describe internal work through its user-visible outcome. For example, write “Improved analysis performance on large diffs,” not how many packages or tests were used to validate it.

## Canonical changelog format

Use this format for new owned-project release sections unless repository instructions or an upstream fork require preserving another established format:

```markdown
# Changelog

## Unreleased

## 1.2.3 - 2026-07-20

### Breaking changes

- ...

### Added

- ...

### Changed

- ...

### Deprecated

- ...

### Removed

- ...

### Fixed

- ...

### Security

- ...

### Compatibility

- ...
```

Rules:

- Version headings do not include `v`; tags normally do.
- Dates use ISO `YYYY-MM-DD`.
- Keep releases in reverse chronological order.
- Keep an `Unreleased` section at the top.
- Omit empty categories.
- Use only the categories above, in the order above.
- Put upgrade-required source/config/data changes under `Breaking changes`, including for `0.x` packages. Do not duplicate them under `Changed` or `Removed`.
- Use `Compatibility` only for supported Elixir/OTP/runtime/framework versions, operating systems, architectures, or explicit interoperability boundaries—not ordinary dependency bumps.
- Do not use `New`, `Improved`, `Highlights`, `Fixes`, `What's New`, `Tests`, `Validation`, `Links`, or project-specific release headings.
- Do not rewrite historical sections merely to adopt the standard. Normalize `Unreleased` and future releases prospectively.
- Preserve upstream changelog conventions in maintained forks, while still enforcing the audience and exact-release-body rules.

## Discover project release mechanics

Before choosing commands, inspect:

1. Repository instructions (`AGENTS.md`, contributing/release docs)
2. Working-tree and remote synchronization state

From dannote/dot-pi, MIT.

More from dannote/dot-pi