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