# Isaaclab Writing Changelog Fragments

> Writes and validates Isaac Lab package changelog fragments using the repository fragment format and bump rules. Use when source package changes need release notes, migration guidance, or changelog validation.

- Skill: `isaac-sim/isaaclab-writing-changelog-fragments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add isaac-sim/isaaclab-writing-changelog-fragments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/isaac-sim/isaaclab-writing-changelog-fragments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: isaac-sim (https://skillmd.com/u/isaac-sim)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/isaac-sim/isaaclab-writing-changelog-fragments

---


# 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

1. Identify each changed package under `source/`.
2. Add fragments for each touched package under `source/<package>/changelog.d/`.
3. Follow the contribution guide's [changelog section](../../../docs/source/refs/contributing.rst#maintaining-package-changelogs-and-versions)
   for fragment tiers, entry format, breaking-change labels, and migration guidance.

## Validation

Run the changelog gate against the PR base (here, `upstream/main`):

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

## References

- [Contributing guide](../../../docs/source/refs/contributing.rst)
- [Changelog tool](../../../tools/changelog/cli.py)
- [Towncrier config](../../../tools/changelog/towncrier.toml)
- [Examples](examples.md)

