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:

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