Writing A Changelog Entry
Productivitywriting-a-changelog-entryWriting A Changelog Entry is an Agent Skill for productivity published in the DRMacIver/shrinkray repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Write or update the RELEASE.md changelog entry that Shrink Ray requires for any change touching src/ or pyproject.toml. Use when opening or preparing a PR, adding a user-facing feature or fix, or when CI / `just check-release` reports a missing RELEASE.md.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/DRMacIver/shrinkray/blob/HEAD/.claude/skills/writing-a-changelog-entry/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-a-changelog-entry, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Writing a changelog entry
Shrink Ray assembles its user-facing CHANGELOG.md from per-change RELEASE.md
files, in the style of Hypothesis's release system. Every change that touches
src/ or pyproject.toml must ship a RELEASE.md at the repository root.
How the system works
- You add a
RELEASE.mdat the repo root in your branch/PR. - CI's
changelogjob (andjust check-releaselocally) fails if a source-affecting change has noRELEASE.md. - When the change lands on
main, the auto-release job:- bumps the calver version,
- prepends your
RELEASE.mdbody toCHANGELOG.mdunder the new version's## YY.M.D.N — DATEheading, - deletes
RELEASE.md, - commits, tags, and publishes to PyPI.
You never edit CHANGELOG.md by hand, and there is no release-type flag to
set — calver decides the version, so RELEASE.md is purely the entry body.
What to write
RELEASE.md is Markdown. It is the body of one changelog entry. Write it for
someone who uses the shrinkray command, not for a developer of Shrink Ray.
Rules:
- User-visible effects only. New or changed CLI options, changed behaviour, changed output, bug fixes users could hit. Never mention Python modules, classes, functions, refactors, tests, type checking, or coverage.
- Concise. One or two sentences per change.
- Bullet list when there is more than one change; no long paragraphs.
- Backticks for CLI flags and literal values (e.g.
`--memory-limit`). - Purely internal changes still need a
RELEASE.md. Its body is simply:- No user-visible changes.
Good examples
- Added `--memory-limit` to cap the memory each interestingness-test run may use,
so a runaway test can't exhaust your machine's RAM.
- Fixed a crash when reducing deeply nested JSON inputs.
- C and C++ reduction no longer needs `clang_delta` installed; it now uses
built-in reduction passes.
Bad examples (do not do this)
Refactored problem.py to extract reflow_sort_key into reformat.py.(Internal; means nothing to a user.)Bumped test coverage to 100% and fixed basedpyright errors.(Internal; not a release note.)- A three-paragraph essay explaining the implementation. (Too long; use a bullet and describe the effect, not the mechanism.)
Checklist
-
RELEASE.mdexists at the repository root. - Every bullet describes something a user would notice.
- No references to internal code, tests, or types.
- Flags/values are in backticks.
-
just check-releasepasses.