OpenParable
Skip to content
← Back to skills

Writing A Changelog Entry

Productivity
writing-a-changelog-entry

Writing 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  1. You add a RELEASE.md at the repo root in your branch/PR.
  2. CI's changelog job (and just check-release locally) fails if a source-affecting change has no RELEASE.md.
  3. When the change lands on main, the auto-release job:
    • bumps the calver version,
    • prepends your RELEASE.md body to CHANGELOG.md under the new version's ## YY.M.D.N — DATE heading,
    • 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.md exists 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-release passes.