release-notes - SKILL.md Agent Skill

name: release-notes description: Generate release notes for AlbumentationsX. Use when the user asks to prepare, draft, or write release notes for a new version (e.g. "prepare release notes for 2.x.y", "draft release X").

Release notes

Where they live

_internal/release_notes/RELEASE_NOTES_<version>.md (e.g. RELEASE_NOTES_2.2.0.md).

Source of truth for what changed

git log --oneline <prev_tag>..HEAD and git show --stat <sha> per commit.
git diff <prev_tag>..HEAD -- README.md for the canonical added/removed transforms list.
git diff <prev_tag>..HEAD -- pyproject.toml for dependency / version bumps.
The PR descriptions in commit messages — they're written carefully, mine them for one-liners.

Required structure

## Summary — 3–5 bullet TL;DR.
## Breaking changes — every backwards-incompatible change. Be specific (old → new). Include short before/after code snippets when the API surface changed.
## New features — new transforms, new core features, new params on existing transforms.
## Bug fixes — one entry per fix, link the PR.
## Misc — CI, build, deps, internal refactors users might notice.
## Commits — table of commit | PR | description for every commit since the previous tag.

Match the tone of RELEASE_NOTES_2.1.2.md and RELEASE_NOTES_2.2.0.md: terse, technical, no marketing fluff, no emoji.

Transform name → link

Every mention of a transform name in release notes MUST be a markdown link to its explore page:

[TransformName](https://albumentations.ai/explore/transform/TransformName/)

This applies to:

New transforms (in the "New features" section header and prose).
Transforms touched by bug fixes.
Transforms touched by breaking changes (including in the rename table).
The Commits table descriptions.

The first mention in each section should be a link. Repeat mentions in the same paragraph can stay as plain backticked names if it would be visually noisy, but err on the side of always linking.

Examples (good):

### [CopyAndPaste](https://albumentations.ai/explore/transform/CopyAndPaste/) (mixing)

[CopyAndPaste](https://albumentations.ai/explore/transform/CopyAndPaste/) was mixing positional indices and `_bbox_instance_id` values...

| `Rotate.limit`, `SafeRotate.limit` | `angle_range` |

Becomes:

| [Rotate](https://albumentations.ai/explore/transform/Rotate/).limit, [SafeRotate](https://albumentations.ai/explore/transform/SafeRotate/).limit | `angle_range` |

Do not link:

Core classes (Compose, BboxParams, KeypointParams, BasicTransform, BaseDistortion).
Parameter names (angle_range, blur_range).
Helper functions (unpack_label_wrappers, to_tuple).
Internal modules (core/utils.py).

Other conventions

Code references use single backticks for params/files; triple-backtick fenced blocks for code samples.
Use the actual commit short SHA (7 chars) and the real PR number in the commits table.
"Breaking changes" section comes before "New features" — users scan that first.
For mass renames, use a single 2-column table (Old | New) instead of a bullet list.
If a feature spans multiple PRs (e.g. instance binding in #222, #223, #237), mention them inline in the prose, not as separate entries.
If pyproject.toml version isn't bumped yet, note that in the response to the user; do not bump it as part of writing the notes.