Fast Forward Changelog

Independent Markdown fragments, automated PR checks and a reviewed version PR for PHP packages. Contributors add .changelog/*.md; the version workflow collects them into CHANGELOG.md and removes the consumed fragments.

The package is in 0.x development. Public interfaces may change before 1.0; review release notes and integration contracts before upgrading.

🤖 GitHub Actions

Use guided setup via CPX to choose the release branch, publication behavior and optional agent skill, then review the generated workflow. Existing integrations are preserved. For manual setup, create .github/workflows/changelog.yml:

name: Changelog

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]

  pull_request_target:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled, closed]

  push:
    branches: [main]

  workflow_dispatch:

permissions: {}

jobs:
  changelog:
    permissions:
      contents: write
      pull-requests: write
      issues: read
      statuses: write

    uses: php-fast-forward/changelog/.github/workflows/changelog.yml@v0

    with:
      base-branch: main
      source: tags
      comment-mode: always
      prepare-release: true
      publish: true

The v0 branch follows published 0.x releases, including potentially breaking minor updates. Select a full release tag or SHA when you need a fixed revision. The example states publication intent explicitly so it also works with releases whose default was disabled. The defaults below describe this source revision; verify the documentation at your selected ref before adoption.

Each contribution PR adds a fragment. This workflow checks it, updates one PR comment and creates notes for Dependabot updates. After contributions merge, it prepares changelog/version: review that PR to update the central history and remove the consumed fragments. The workflow never merges it for you.

Main settings

All lifecycle inputs are optional. These are the main defaults:

Input	Default	Purpose
base-branch	Repository default branch	Release line; match the caller's event filters.
fragment-directory	.changelog	Pending Markdown fragments.
changelog-file	CHANGELOG.md	Consolidated version history.
comment-mode	always	Sticky PR feedback: always, on-failure or never.
prepare-release	true	Create or refresh the version PR after base pushes.
publish	true	Publish the approved version PR's tag/release after merge. Set false for a pilot.
version-pr-title	chore(release): {repository} v{current_version} → v{next_version}	Supports {repository}, {repository_name}, {current_version} and {next_version}.
runs-on	'["ubuntu-latest"]'	Linux runner labels as JSON; Docker, Bash and Git are required.

See the complete workflow and Action reference for every input, type, default, secret, output and permission. The lifecycle guide explains event handling and individual recipes cover custom composition. For another release branch, adjust both event filters and base-branch. See setup and event policies before adoption.

Your project needs no PHP or Composer installation for automation. The default token needs the repository's Actions PR-creation permission; use an optional GitHub App when generated PRs need automatic downstream CI. Review the approved-merge publication contract before merging the generated version PR.

For an optional validation-only trial, add publish: false to with. Merging the version PR then updates history without creating a tag or GitHub release; later version PRs continue from that recorded version. Remove the override when you want normal automatic publication.

🛠️ CLI

Use PHP ^8.5 and CPX to run the CLI without adding it to the application's Composer dependencies. From your project:

cpx --skip-local fast-forward/changelog add \
  "Fixes Markdown parsing." --category=fixed --no-interaction
cpx --skip-local fast-forward/changelog check --no-interaction

--skip-local selects CPX's separate installation. The commands create one fragment and validate pending notes; no init is needed. See local setup and previews and the command reference. The Docker CLI is an alternative with its own PHP runtime.

🧠 Agent skill

Manage project instructions from GitHub with llm/skills:

composer require --dev llm/skills
composer skills:init
composer skills:add php-fast-forward/changelog

Approve only the intended Composer plugin. Version skills.json and the intended manifest/lock changes under the project's policy; ignore the generated .agents/ directory and exclude it from archives. With auto-sync enabled, composer install reconstructs the instructions. The Changelog package is not a project dependency for this route.

The project installer offers the same setup. The skill guide explains ownership, updates, NPX as an optional alternative and legacy native copies. Installing instructions does not activate an agent session; the skill consults the selected runtime's help and documentation.

🔌 Further integration

Use the optional Composer/PHP integration for classes inside an existing application, or individual actions for custom automation. Localized headings and trusted PHP templates are covered in history and templates.

🤝 Contributing

See CONTRIBUTING.md and this repository's own changelog flow. Add one fragment per observable change and run composer check before a PR.

🛡 License

MIT © 2026 Felipe Sayao Lobato Abreu. See LICENSE.

🔗 Links

Documentation · Packagist · Issues · Support · Security · Code of Conduct