using-changelogger

name	using-changelogger
description	Creates changelog entries using the Changelogger CLI tool. Use when asked to create a changelog entry, when preparing a merge request, when suggesting a changelog for significant code changes, or when the keyword 'finished' is used.

Using Changelogger

Creates structured changelog entries as YAML files using the changelogger new CLI command. Each changelog entry is stored as a separate file in changelogs/unreleased/ to avoid merge conflicts.

When to Act

• Always: When explicitly asked to create a changelog entry.
• Always: When creating or preparing a merge request — create a changelog entry for the changes.
• Suggest: When you've made significant code changes (new features, bug fixes, breaking changes), ask the user if a changelog entry should be created. Do not create one automatically for minor changes like refactoring, typo fixes, or dependency updates unless asked.

Workflow

1. Read Project Configuration

Before creating a changelog, check if a .changelogger.yml exists in the project root:

cat .changelogger.yml

This file may define:

• types: Custom changelog types (overrides defaults). Use the YAML keys as type values.
• groups: Module or component groups. If groups are configured, you must provide a --group flag.

2. Determine the Changelog Type

If .changelogger.yml defines custom types, use those. Otherwise, use the default types:

Type Key	Label
added	New feature
fixed	Bug fix
hotfix	Hotfix
changed	Feature change
deprecated	New deprecation
removed	Feature removal
security	Security fix
performance	Performance improvement
other	Other
ignore	No Changelog

Choose the type that best matches the change. When in doubt, ask the user.

3. Match the Language

Check existing changelog entries in changelogs/unreleased/ or CHANGELOG.md to determine the language used. Write new entries in the same language. For example, if existing entries are in German, write the new entry in German too.

4. Create the Changelog Entry

Use the changelogger new command with CLI flags to avoid interactive prompts:

changelogger new --type=<type> --message="<description>"

With groups (if configured in .changelogger.yml):

changelogger new --type=<type> --message="<description>" --group="<group>"

For changes that need no changelog:

changelogger new --empty

5. Verify

After creating the entry, confirm the file was created:

ls changelogs/unreleased/

Writing Good Changelog Messages

• Write from the user's perspective, not the developer's.
• Describe what changed, not how it was implemented.
• Use clear, non-technical language when possible.
• Keep it concise — one sentence is ideal.

Good examples:

• "Add dark mode support for the dashboard"
• "Fix login failing when using special characters in password"
• "Remove deprecated CSV export feature"

Bad examples:

• "Refactor AuthService to use strategy pattern" (implementation detail)
• "Update dependencies" (too vague)
• "Fix bug" (not descriptive)

Important Rules

• Never edit CHANGELOG.md directly. It is generated by changelogger release.
• Never manually create YAML files in changelogs/unreleased/. Always use the changelogger new command.
• One entry per logical change. If a merge request contains multiple user-facing changes, create multiple changelog entries.
• Always use the --type and --message flags to run non-interactively.