package-release
Prepare, publish, repair, or verify package releases and changelogs. Always use for package/version release, publish, ship, tag, changelog, release notes, registry publication, documentation publication, or GitHub Release work. Distinguish package releases from application deployments before acting.
dannote · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add dannote/dot-pi --skill package-releaseAbout this skill
name: package-release description: Prepare, publish, repair, or verify package releases and changelogs. Always use for package/version release, publish, ship, tag, changelog, release notes, registry publication, documentation publication, or GitHub Release work. Distinguish package releases from application deployments before acting.
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
Unreleasedonly. 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.mdversion 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--notesor a shell string. - Never use regex,
awk, orsedto 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:
# 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
Unreleasedsection 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 for0.xpackages. Do not duplicate them underChangedorRemoved. - Use
Compatibilityonly 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
Unreleasedand 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:
- Repository instructions (
AGENTS.md, contributing/release docs) - Working-tree and remote synchronization state
- Current package version(s) and intended tag
CHANGELOG.mdand the exact target section- Package manifests and package file lists
- Tag-triggered workflows and reusable release workflows
- Existing tag and GitHub Release state
- Registry authentication and required 2FA
Respect project-specific publication mechanics. They may change command order; they do not override the release-note audience contract.
Common topologies:
- Manual registry release — validate, publish package/docs, push the correct tag, create the GitHub Release.
- Tag-triggered publication — push the prepared commit and tag, watch the workflow, then verify every output. Do not duplicate local publication.