README

A tool to manage versioning and changelogs for Composer packages, inspired by changesets.

Installation

composer require change-champion/champ --dev

Or install globally:

composer global require change-champion/champ

Quick Start

# Initialize in your project
champ init

# Create a changeset when you make changes
champ add

# View pending changesets
champ status

# Apply version bump and generate changelog
champ version

# Create a git tag
champ publish

Commands

`champ init`

Initialize change-champion in your project. Creates a .changes directory with configuration.

champ init

# With GitHub Actions automation
champ init --with-github-actions

Options:

--with-github-actions - Also install GitHub Actions workflows for automation

`champ add`

Create a new changeset. Run this after making changes that should be released.

# Interactive mode
champ add

# Non-interactive mode
champ add --type=minor --message="Add user authentication feature"

# Create empty changeset (useful for CI)
champ add --empty

Options:

--type, -t - Bump type: major, minor, or patch
--message, -m - Summary of the change
--empty - Create an empty changeset

`champ generate`

Generate changesets from conventional commits (hybrid mode like release-please).

# Generate from latest tag to HEAD
champ generate

# Preview without creating files
champ generate --dry-run

# Specify commit range
champ generate --from=v1.0.0 --to=HEAD

Options:

--from - Starting ref (tag, commit, or branch). Defaults to latest tag.
--to - Ending ref. Defaults to HEAD.
--dry-run - Show what would be generated without creating files

Conventional commit types:

Commit Type	Changeset Type	Example
`feat`	minor	`feat: add user authentication`
`feat!`	major	`feat!: remove deprecated API`
`fix`	patch	`fix: resolve null pointer`
`perf`	patch	`perf: optimize database queries`
`refactor`	patch	`refactor: extract helper function`
`docs`	ignored	`docs: update README`
`chore`	ignored	`chore: update dependencies`
`test`	ignored	`test: add unit tests`
`ci`	ignored	`ci: update workflow`

Breaking changes are detected via ! suffix (e.g., feat!:) or BREAKING CHANGE: in the commit body.

`champ status`

Show pending changesets and the calculated next version.

champ status

# Verbose output
champ status -v

`champ version`

Apply all pending changesets: update CHANGELOG.md and delete the changeset files.

# Interactive confirmation
champ version

# Preview changes without applying
champ version --dry-run

# Skip changelog generation
champ version --no-changelog

# Create a pre-release version
champ version --prerelease alpha
champ version --prerelease beta
champ version --prerelease rc

Options:

--dry-run - Show what would be done without making changes
--no-changelog - Skip changelog generation
--prerelease, -p - Create a pre-release version (alpha, beta, rc)

Pre-release workflow:

# Create first alpha (1.0.0 → 1.1.0-alpha.1)
champ version --prerelease alpha

# Bump alpha (1.1.0-alpha.1 → 1.1.0-alpha.2)
champ version --prerelease alpha

# Move to beta (1.1.0-alpha.2 → 1.1.0-beta.1)
champ version --prerelease beta

# Move to RC (1.1.0-beta.1 → 1.1.0-rc.1)
champ version --prerelease rc

# Graduate to stable (1.1.0-rc.1 → 1.1.0)
champ version

`champ preview`

Preview the CHANGELOG entry that would be generated without making any changes.

# Preview changelog entry
champ preview

# Preview with pre-release version
champ preview --prerelease alpha

Options:

--prerelease, -p - Preview as a pre-release version (alpha, beta, rc)

`champ check`

Validate changeset files for correct format. Useful in CI to catch errors early.

champ check

Returns exit code 0 if all changesets are valid, 1 if any are invalid.

`champ publish`

Create a git tag for the current version.

# Create and push tag
champ publish

# Create tag without pushing
champ publish --no-push

# Preview without creating tag
champ publish --dry-run

Options:

--dry-run - Show what would be done without making changes
--no-push - Create tag but don't push to remote

`champ install-skill`

Install the Change Champion Claude skill file into the current project.

champ install-skill

# Overwrite existing skill file
champ install-skill --force

Options:

--force, -f - Overwrite an existing skill file

Copies the skill file to .claude/skills/change-champion/SKILL.md in your project, giving Claude context about Change Champion commands and workflows.

Changeset Format

Changesets are stored in .changes/ as markdown files:

---
type: minor
---

Add user authentication with OAuth2 support.

Configuration

Configuration is stored in .changes/config.json:

{
  "baseBranch": "main",
  "changelog": true,
  "repository": "https://github.com/owner/repo",
  "sections": {
    "major": "Breaking Changes",
    "minor": "Features",
    "patch": "Fixes"
  },
  "releaseBranchPrefix": "release/",
  "versionPrefix": "v",
  "draftRelease": false
}

Options:

baseBranch - The base branch for comparisons (default: main)
changelog - Whether to generate changelog entries (default: true)
repository - Repository URL for linking issues, PRs, and commits (auto-detected from git remote if not set)
sections - Custom section headers for changelog (defaults shown above)
releaseBranchPrefix - Branch prefix for release PRs created by the action (default: release/)
versionPrefix - Prefix for version numbers in changelog headers and git tags (default: v for v1.0.0 format)
draftRelease - Create GitHub releases as drafts for manual publishing; used by the action only (default: false)

Auto-linking

Changelog entries are automatically enriched with links when a repository URL is configured (or auto-detected from git remote).

Issue references

Issue references in changeset summaries are linked:

- Fix authentication bug. Fixes [#123](https://github.com/owner/repo/issues/123)

Supported patterns: #123, Fixes #123, Closes #123, Resolves #123

PR numbers and commit hashes

PR numbers and commit hashes are automatically appended to each changelog entry from git history:

- Add user authentication ([#45](https://github.com/owner/repo/pull/45)) ([abc1234](https://github.com/owner/repo/commit/abc1234...))

PR numbers are extracted from squash merge subjects (feat: some change (#45)) and merge commits ( Merge pull request #45 from ...). If a PR number already appears in the changeset summary, it won't be duplicated.

Semantic Versioning

Change Champion follows semver:

patch (0.0.x) - Bug fixes, minor changes
minor (0.x.0) - New features, backwards compatible
major (x.0.0) - Breaking changes

When multiple changesets exist, the highest bump type wins. For example, if you have one minor and one patch changeset, the version will be bumped as minor.

Workflow

Make changes to your code
Run champ add to create a changeset describing your changes
Commit the changeset file along with your code changes
When ready to release, run champ version to bump versions and update changelog
Commit the version bump
Run champ publish to create a git tag
Push the tag to trigger your release pipeline

GitHub Actions

The quickest way to automate releases is with champ init:

champ init --with-github-actions

This installs a workflow (.github/workflows/change-champion.yml) that uses the change-champion/action GitHub Action to handle:

check — Comments on PRs that don't include a changeset
release — Creates a release PR when changesets are merged to main
publish — Creates a git tag and GitHub Release when a release PR is merged

Setup

After installing the workflow, enable the required permissions:

Go to Settings → Actions → General
Under Workflow permissions, enable:
- "Read and write permissions"
- "Allow GitHub Actions to create and approve pull requests"

For full action documentation, see the change-champion/action repository.

License

The MIT License (MIT). Please see License File for more information.

change-champion / champ

Maintainers

Details

README

Installation

Quick Start

Commands

`champ init`

`champ add`

`champ generate`

`champ status`

`champ version`

`champ preview`

`champ check`

`champ publish`

`champ install-skill`

Changeset Format

Configuration

Auto-linking

Issue references

PR numbers and commit hashes

Semantic Versioning

Workflow

GitHub Actions

Setup

License