Writing Changelog Fragments
When To Use
Use this skill when a PR changes code under source/<package>/ and needs a changelog fragment, or when reviewing fragment formatting.
Do not use this skill for pure docs, CI, tools, or skills changes unless they also modify source/<package>/.
Workflow
- Identify each changed package under
source/. - Add fragments for each touched package under
source/<package>/changelog.d/. - Follow the contribution guide's changelog section for fragment tiers, entry format, breaking-change labels, and migration guidance.
Validation
Run the changelog gate against the PR base (here, upstream/main):
uv run python tools/changelog/cli.py check upstream/main --include-worktree
For pre-commit validation, set ISAACLAB_CHANGELOG_BASE_REF to the same base. Follow the guide's Tools section for the final formatting gate.
Maintenance
Keep this skill synchronized with AGENTS.md, docs/source/refs/contributing.rst, and tools/changelog/. If changelog policy changes, update those authoritative sources first and keep this skill focused on routing agents to the right workflow.