# Release Notes

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

- Skill: `albumentations-team/release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add albumentations-team/release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/albumentations-team/release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: albumentations-team (https://skillmd.com/u/albumentations-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/albumentations-team/release-notes

---


# 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

1. `## Summary` — 3–5 bullet TL;DR.
2. `## Breaking changes` — every backwards-incompatible change. Be specific (old → new). Include short before/after code snippets when the API surface changed.
3. `## New features` — new transforms, new core features, new params on existing transforms.
4. `## Bug fixes` — one entry per fix, link the PR.
5. `## Misc` — CI, build, deps, internal refactors users might notice.
6. `## 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

Link the first meaningful mention of a transform in each section, including headings and table entries:

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

Repeated mentions in the same paragraph may use plain backticked names. Keep code fences runnable, without links.
For parameter renames, link the transform separately and put the parameter name in code.

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.