Changelogs Skill

Update CHANGELOG.md files to reflect changes made in the current git branch.

When to Use

• When asked to update or write changelogs

• When preparing a PR for merge

• When documenting recent changes before release

Instructions

Step 1: Analyze Branch Changes

Run these git commands to understand what changed:

Get the base branch (usually master or main)

git log --oneline -1 origin/master

List all commits in current branch not in master

git log origin/master..HEAD --oneline

Show changed files with their packages

git diff origin/master --name-only

Step 2: Identify Affected Packages

Determine which packages were modified by checking changed file paths:

• packages/react/src/atomic/<Component>/* → Update packages/react/src/atomic/<Component>/CHANGELOG.md and packages/react/CHANGELOG.md

• packages/react/src/composite/<Component>/* → Update packages/react/src/composite/<Component>/CHANGELOG.md packages/react/CHANGELOG.md

• packages/core/styles/* → Update packages/core/styles/CHANGELOG.md

• packages/core/tokens/* → Update packages/core/tokens/CHANGELOG.md

• Any root monorepo configuration change → Also update the root CHANGELOG.md

CRITICAL After ANY change to a specific component, it's critical to reflect the same change in packages/react/CHANGELOG.md . If this is ommited, the change will only apply to the specific package and not to the general @nimbus-ds/components bundle, generating an inconsistency.

Step 3: Classify the Change

Determine the change type based on commit messages and diff:

Type Category Version Bump

Breaking API changes 🛠 Breaking changes

Major (x.0.0)

New props, components, features 🎉 New features

Minor (0.x.0)

Bug fixes, corrections 🐛 Bug fixes

Patch (0.0.x)

Dependency updates 📚 3rd party library updates

Patch

Refactors, docs, tooling 💡 Others

Patch

Step 4: Write the Entry

Format:

YYYY-MM-DD version

<emoji> <category>

• <Summary of the change>. (#PR by @contributor)

Writing Guidelines:

• Be concise: One sentence summarizing the user-facing impact

• Focus on "what": Describe the outcome, not implementation details

• Use past tense: "Added", "Fixed", "Updated", not "Add", "Fix", "Update"

• Avoid code details: No mention of specific functions, variables, or files

Good examples:

• Added disabled state styling to Input component.

• Fixed focus ring not appearing on keyboard navigation.

• Updated Button to support icon-only variant.

Bad examples:

• Update Input.tsx to add handleFocus callback and modify CSS classes.

• Fixes bug in line 45 of nimbus-input.css.ts where outline was missing.

Step 5: Ask for Missing Information

If any of the following is unknown, ask the user:

• PR number: Required for the entry link

• GitHub username: Required for contributor attribution

• Version number: If not clear from existing changelog

Step 6: Update the Files

• Read the existing CHANGELOG.md for the affected package(s)

• Determine the next version based on current version + change type

• Insert the new entry at the TOP, below the # Changelog header

• Use today's date in YYYY-MM-DD format

• Update package-specific CHANGELOG.md file, and only update the root CHANGELOG.md file if the change is related to the root monorepo.

Reference

Full formatting rules are defined in .cursor/rules/changelogs.mdc .