Release and Publishing Workflow

Release Surfaces

Versioning and Branch Flow

Use pull requests for all release-bound changes. The release candidate SHOULD land on main through a dedicated release-preparation pull request before the tag or GitHub release is published.

The expected flow is:

1. merge feature, bug fix, and documentation pull requests into main while keeping Unreleased current;
2. run the release verification checklist against the current main ;
3. trigger the changelog workflow manually through workflow_dispatch to infer the next version or accept an explicit version;
4. review the release notes preview written to .dev-tools/release-notes.md in the release-preparation branch;
5. review and merge the release-preparation pull request created from that workflow;
6. let the merged release workflow create or update the GitHub release and tag from the released changelog section;
7. confirm Packagist, reports, and wiki publication.

This means an ordinary feature or bug-fix pull request merged into main does not publish a GitHub release by itself. Publication happens only after the dedicated release/v... pull request created by the changelog workflow is merged.

Do not retag an existing published version. If a release needs correction, prepare a follow-up changelog entry, open a new release-preparation pull request, and publish a new version tag.

Pre-Release Verification

Run the full project gate before tagging:

composer install
composer dev-tools

For documentation-heavy releases, also verify the generated reports and wiki commands directly:

composer dev-tools reports
composer dev-tools wiki

Before creating the tag, check the repository state:

git status --short
git log --oneline origin/main..HEAD

The working tree should be clean, and the release commit should already be on main .

Tagging and GitHub Release Notes

The changelog workflow now handles the tag and GitHub release publication after the release-preparation pull request is merged. Manual tagging SHOULD only be used for recovery or exceptional maintenance.

The same workflow also owns pull-request changelog validation. Regular feature and fix pull requests SHOULD expect changelog:check to run against the base branch and fail when no meaningful Unreleased entry is added. Generated release/v... pull requests are excluded from that validation because the release-preparation flow intentionally empties Unreleased after promotion.

If maintainers must recover the release manually, create the tag from the verified main commit:

git switch main
git pull --ff-only
git tag <version>
git push origin <version>

When the workflow publishes the GitHub release, the notes come from the matching released changelog section. Those notes SHOULD include:

• user-facing changes;
• breaking changes or migration notes;
• new or changed commands;
• documentation and workflow changes that affect consumer repositories;
• verification performed before the release.

Workflow Permissions

The manual release-preparation step depends on GitHub Actions being allowed to open pull requests on behalf of the repository workflow token.

Configure the repository under Settings > Actions > General :

1. enable Read and write permissions under Workflow permissions ;
2. enable Allow GitHub Actions to create and approve pull requests .

If either control appears disabled or grayed out, the restriction is usually coming from repository permissions or organization policy rather than branch protection. In that case, an organization or repository administrator MUST adjust the policy before the workflow can prepare release pull requests.

Branch protection matters later, when the generated release/v... pull request is reviewed and merged, but it does not control whether the workflow is allowed to create that pull request in the first place.

Packagist Publication

Packagist uses the Git repository metadata for fast-forward/dev-tools. After pushing a tag, confirm the version appears on Packagist and that Composer can resolve it from a clean consumer project.

composer show fast-forward/dev-tools --all

If Packagist does not show the version, inspect the package webhook or trigger a manual update from the Packagist package page.

Reports and Wiki Publication

Reports and wiki publication are tied to main workflows, not to the tag itself:

• the reports workflow publishes generated reports to GitHub Pages after changes land on main ;
• the wiki workflow promotes generated wiki content after changes land on main ;
• pull request previews remain review artifacts and should not be treated as final release output.

When a release contains documentation changes, validate the final Pages and wiki output after the merge to main and before announcing the release broadly.

Post-Release Validation

After the tag and release notes are published:

1. confirm the tag exists on GitHub;
2. confirm the version appears on Packagist;
3. install the tagged version in a temporary consumer project;
4. verify GitHub Pages reports reflect the release commit;
5. verify the GitHub Wiki reflects the release commit;
6. check that no release pull request preview artifacts are left active by mistake;
7. open follow-up issues for any release automation or changelog improvements discovered during the process.

Current Automation and Remaining Manual Checks

Maintainers still decide when to prepare a release and when to merge the release-preparation pull request. After that merge, the workflow owns the tag and GitHub release publication so branch protection rules remain intact.

Further automation may still help validate Packagist publication, summarize post-release checks, or backfill historical changelog sections. Those improvements should remain separate from this guide unless the release process itself changes again.