Automate releases and changelogs with Release Please #215

Problem

Releases are manual: pick a version, push a tag, write a GitHub release by hand (see the "Releasing" section in the README, #214). There is no changelog file, release notes live only in the release title, and the @version docblocks in classes/ValidFormBuilder/ValidForm.php still say 5.3.0. v5.3.1 never reached Packagist because of a stray version field in composer.json.

Commit messages already follow Conventional Commits, so the input for automation is there. Nothing consumes it yet.

Proposal

Adopt Release Please through its GitHub Action. It reads conventional commits on master, keeps a release PR open with the next version and a generated CHANGELOG.md, and on merge of that PR creates the tag and the GitHub release. Packagist keeps working as today through the existing webhook.

Versions verified on 2026-09-11:

What the flow becomes

1. Merge PRs into master as usual. fix: bumps patch, feat: bumps minor, feat!: or a BREAKING CHANGE: footer bumps major.
2. Release Please opens or updates a PR titled chore(master): release 5.4.0 with the changelog diff.
3. Merge that PR. The action creates tag v5.4.0, a GitHub release with the changelog section as body, and Packagist picks it up.

Nobody runs git tag by hand anymore. Version numbers are decided by commit types, not by memory.

Implementation

1. Workflow

.github/workflows/release-please.yml:

name: Release Please

on:
  push:
    branches:
      - master

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v5
        with:
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

The default GITHUB_TOKEN is enough as long as "Allow GitHub Actions to create and approve pull requests" is enabled under Settings > Actions > General. Note: PRs and tags created with GITHUB_TOKEN do not trigger other workflows, so the PHPUnit run will not start on the release PR itself. That is acceptable because the release PR only touches CHANGELOG.md and version strings. If we want CI on it anyway, use a fine-grained PAT via the token input.

2. Config

release-please-config.json:

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "php",
  "include-component-in-tag": false,
  "packages": {
    ".": {
      "extra-files": [
        "classes/ValidFormBuilder/ValidForm.php"
      ]
    }
  }
}

.release-please-manifest.json:

{
  ".": "5.3.2"
}

The php release type updates composer.json only if it already has a version field (verified in src/strategies/php.ts and src/updaters/php/root-composer-update-packages.ts). Ours has none and must stay that way, so Packagist keeps reading the version from the tag.

3. Docblock versions

Annotate the two @version lines in ValidForm.php so the generic updater keeps them current:

 * @version 5.3.2 // x-release-please-version

4. Follow-ups after the first merge

• Replace the "Releasing" section in the README with the new three-step flow.
• Decide whether the first release PR should be a patch or minor. Commits since v5.3.2 are the PHPUnit setup (feat) and the README docs, so Release Please will propose 5.4.0.

Out of scope

• Publishing to Packagist differently. The webhook stays.
• Backfilling CHANGELOG.md for versions before 5.3.2. The first generated changelog starts at the first automated release; older history stays in the GitHub releases list.

Estimate

About one hour: add three files, annotate two docblock lines, flip the Actions setting, merge, and review the first release PR.