README

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

Installation

composer require offload-project/change-champion --dev

Or install globally:

composer global require offload-project/change-champion

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:

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

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 (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 GitHub Actions (default: release/)
• versionPrefix - Prefix for version numbers in changelog headers (default: v for v1.0.0 format)
• draftRelease - Create GitHub releases as drafts for manual publishing (default: false)

Issue Linking

Issue references in changesets are automatically linked to the repository:

---
type: patch
---

Fix authentication bug. Fixes #123

Generates:

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

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

Semantic Versioning

Change-composer 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

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

GitHub Action

The easiest way to automate releases is with the change-champion action:

name: Release

on:
  push:
    branches: [ main ]
  pull_request:
    types: [ closed ]
    branches: [ main ]

permissions:
  contents: write
  pull-requests: write
  checks: read

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: offload-project/change-champion@v1.3.1  # Use latest version
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

This single workflow handles everything:

• Creates release PRs when changesets are merged
• Creates git tags and GitHub releases when release PRs are merged

Action Inputs

Action Outputs

GitHub Actions Workflows

Alternatively, install individual workflows for more control:

champ init --with-github-actions

This installs three workflows:

changeset-check.yml

Comments on PRs that don't include a changeset, reminding contributors to add one.

changeset-release.yml

When changesets are merged to main, automatically:

• Runs champ version to bump the version and update changelog
• Creates a "Release vX.X.X" pull request

changeset-publish.yml

When a release PR is merged, automatically:

• Creates a git tag
• Creates a GitHub Release with changelog content

Setup

After installing the workflows, enable the required permissions:

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

License

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