From 957b1d5c2abf32dc7787451373d083311178fedb Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 04:42:37 +0530 Subject: [PATCH 1/6] ci: squash-merge Dependabot pull requests Merge commits put subjects like "Merge pull request #n" on main, which release-please cannot read, and the repository moves to squash-only. --- .github/workflows/auto-merge.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index 1c1e6f3..b4a508d 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -36,7 +36,7 @@ jobs: if: >- steps.metadata.outputs.update-type == 'version-update:semver-minor' || steps.metadata.outputs.update-type == 'version-update:semver-patch' - run: gh pr merge --auto --merge "$PR_URL" + run: gh pr merge --auto --squash "$PR_URL" env: PR_URL: ${{ github.event.pull_request.html_url }} GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 5831ca89ae42c52175938a8907020ede3483cb31 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 04:42:38 +0530 Subject: [PATCH 2/6] ci: cut releases with release-please Pull request titles become the Conventional Commit subjects on main. release-please reads them, keeps a release pull request open that bumps .release-please-manifest.json and writes CHANGELOG.md, and merging it tags vX.Y.Z for Packagist and publishes the GitHub release. - release.yml and pr-title.yml (the PR title check is not required: the release pull request is opened with GITHUB_TOKEN and gets no runs) - changelog sections mapped to Keep a Changelog headings - the [Unreleased] heading goes, since release-please would insert new releases above it - maintainer docs, contributing checklist, PR and task templates follow the new flow, including which title type a contract change needs - the release config is export-ignored from the Composer dist --- .gitattributes | 2 + .github/ISSUE_TEMPLATE/task.md | 16 ++++---- .github/pull_request_template.md | 2 +- .github/workflows/pr-title.yml | 34 ++++++++++++++++ .github/workflows/release.yml | 39 +++++++++++++++++++ .release-please-manifest.json | 3 ++ CHANGELOG.md | 6 +-- CONTRIBUTING.md | 6 ++- docs/maintainers.md | 55 +++++++++++++++----------- release-please-config.json | 67 ++++++++++++++++++++++++++++++++ 10 files changed, 193 insertions(+), 37 deletions(-) create mode 100644 .github/workflows/pr-title.yml create mode 100644 .github/workflows/release.yml create mode 100644 .release-please-manifest.json create mode 100644 release-please-config.json diff --git a/.gitattributes b/.gitattributes index d50f1e3..99d0134 100644 --- a/.gitattributes +++ b/.gitattributes @@ -30,6 +30,8 @@ /AGENTS.md export-ignore /CONTRIBUTING.md export-ignore /SECURITY.md export-ignore +/release-please-config.json export-ignore +/.release-please-manifest.json export-ignore # Ship on purpose: README.md and LICENSE.md, inc/, plus ai/ and # bin/sync-ai-instructions.js, which consumers run from vendor/ via `npm run sync-ai`. diff --git a/.github/ISSUE_TEMPLATE/task.md b/.github/ISSUE_TEMPLATE/task.md index 99652d4..cfa009c 100644 --- a/.github/ISSUE_TEMPLATE/task.md +++ b/.github/ISSUE_TEMPLATE/task.md @@ -103,7 +103,6 @@ $ ... - [ ] ### Housekeeping -- [ ] `CHANGELOG.md` entry under `## [Unreleased]` --- @@ -117,19 +116,18 @@ $ ... | | | |---|---| -| **Base your branch on** | `release/` | -| **Branch name** | `/task/` | -| **PR target** | `release/` | -| **PR title** | `[] ` | -| **Commit style** | [Conventional Commits](https://www.conventionalcommits.org/) | +| **Base your branch on** | `main` | +| **Branch name** | `/`, e.g. `fix/feature-selector-closure` | +| **PR target** | `main` | +| **PR title** | A [Conventional Commit](https://www.conventionalcommits.org/) `(): ` | ```bash git fetch origin -git checkout release/ +git checkout main git pull -git checkout -b /task/ +git checkout -b / # work, commit -git push -u origin /task/ +git push -u origin / ``` PR description starts with `Closes #` so the Project card auto-moves to Done on merge. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2ba8011..2dc5cdd 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,7 +33,7 @@ $ ... - [ ] Tests pass ### Housekeeping -- [ ] `CHANGELOG.md` entry under `## [Unreleased]` +- [ ] PR title is a Conventional Commit; release-please writes `CHANGELOG.md` from it ## Reviewer notes diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml new file mode 100644 index 0000000..a8a40bd --- /dev/null +++ b/.github/workflows/pr-title.yml @@ -0,0 +1,34 @@ +name: PR Title Validation + +# Pull requests are squash-merged and the PR title becomes the commit on main. release-please +# reads those subjects to pick the next version and write CHANGELOG.md, so the title has to be a +# Conventional Commit: feat -> minor, fix -> patch, a "!" after the type -> major. +# +# Not a required status check: the release pull request is opened with GITHUB_TOKEN, which +# starts no workflow runs, so this check never reports on it. + +on: + pull_request: + types: [opened, synchronize, edited, reopened, ready_for_review] + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: {} + +jobs: + run: + name: Validate PR title + if: github.event.pull_request.draft == false + runs-on: ubuntu-latest + permissions: + pull-requests: read + statuses: write + steps: + - name: Validate pull request title + uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + wip: true diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..7cdb83e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,39 @@ +name: Release + +# release-please reads the Conventional Commit subjects squash-merged to main and keeps one +# release pull request open that bumps the version and writes CHANGELOG.md. Merging that pull +# request tags vX.Y.Z on main and publishes the GitHub release with the changelog entry as notes. +# +# The release pull request is opened with GITHUB_TOKEN, so GitHub starts no workflow runs on it +# (no tests, no PR title check). That is why neither check is a required status check. Switching +# the token below to a GitHub App token would give the release pull request its CI runs. + +on: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +# Serialise runs so two merges in quick succession can't race on the release pull request. +concurrency: + group: release + cancel-in-progress: false + +jobs: + release-please: + name: Release Please + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + steps: + - name: Open or update the release pull request, or publish the release + uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + config-file: release-please-config.json + manifest-file: .release-please-manifest.json diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000..969d3db --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "2.1.0" +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d9aaa5..9a201f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,9 @@ All notable changes to `rtcamp/wp-primitives` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] +From 2.2.0 on, entries are written by [release-please](https://github.com/googleapis/release-please) +from the Conventional Commit pull request titles merged to `main`. Don't edit this file by hand; +to reword an entry, edit the open release pull request. ## [2.1.0] - 2026-10-02 @@ -169,7 +170,6 @@ Initial release. Requires PHP 8.2+. - Reference documentation under `docs/`, a GPL-2.0-or-later `LICENSE.md`, and a WordPress integration test suite running against `@wordpress/env`. -[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v2.1.0...HEAD [2.1.0]: https://github.com/rtCamp/wp-primitives/compare/v2.0.0...v2.1.0 [2.0.0]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...v2.0.0 [1.0.1]: https://github.com/rtCamp/wp-primitives/compare/v1.0.0...v1.0.1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e602c34..3c3aa4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,8 +60,10 @@ contract-change, and documentation guidance. - [ ] Any change to `inc/Contracts/` is flagged as breaking in the PR description. - [ ] Contract changes are reflected in `ai/primitives-php.instructions.md`. - [ ] User-visible behavior is reflected in `README.md` or `docs/`. -- [ ] A `CHANGELOG.md` entry is added under `## [Unreleased]`. -- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/). +- [ ] The PR title is a [Conventional Commit](https://www.conventionalcommits.org/) + that reads as the changelog entry (`fix:`, `feat:`, `feat!:` for a breaking + change). Pull requests are squash-merged, and release-please writes + `CHANGELOG.md` from the title, so don't edit `CHANGELOG.md` by hand. ## License diff --git a/docs/maintainers.md b/docs/maintainers.md index 52973e3..c9e2ba1 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -84,7 +84,8 @@ For every behavior change: 1. add or update the matching test; 2. implement the smallest compatible change; 3. update the relevant consumer or maintainer documentation; -4. add an entry under `CHANGELOG.md` → `[Unreleased]`; +4. give the pull request a Conventional Commit title that reads as the + changelog entry (see [Releasing](#releasing) for which type to use); 5. run lint, analysis, and integration tests. For a change under `inc/Contracts/`, also: @@ -142,36 +143,46 @@ Use the repository pull-request template. A change is ready for review when: - new or changed behavior has test coverage; - compatibility implications are stated; - user-facing documentation is current; -- `CHANGELOG.md` contains an `[Unreleased]` entry; -- commits follow Conventional Commits. +- the pull request title is a Conventional Commit with the right type. ## Releasing The package is published on Packagist as `rtcamp/wp-primitives`, which reads versions straight from git tags through the repository's Packagist webhook. -A release is therefore a tag on `main`: - -1. Open a pull request that moves the `[Unreleased]` entries under a new - `## [X.Y.Z] - YYYY-MM-DD` heading and updates the compare links at the bottom - of `CHANGELOG.md`. Pick the version from the changes: anything breaking in - `inc/Contracts/` or in documented behaviour is a major, new API is a minor, - fixes only is a patch. -2. Merge it, then tag the merge commit with an annotated tag and push the tag: - - ```bash - git switch main && git pull - git tag -a vX.Y.Z -m "vX.Y.Z" - git push origin vX.Y.Z - ``` - -3. Create the GitHub release from that tag and paste the version's changelog - section as the notes (`gh release create vX.Y.Z --title vX.Y.Z --notes-file - notes.md`). `.github/release.yml` keeps Dependabot pull requests out of - generated notes if you use `--generate-notes` instead. +Releases are cut by [release-please](https://github.com/googleapis/release-please) +(`.github/workflows/release.yml`): + +1. Pull requests are squash-merged, so each PR title becomes one commit on + `main`. release-please reads those subjects and keeps a release pull request + open that bumps `.release-please-manifest.json` and adds the next + `CHANGELOG.md` section. +2. The PR title's type decides the version, so pick it from the change, not the + files touched: + + | Change | Title | + | --- | --- | + | Anything breaking in `inc/Contracts/` or in documented behaviour, including a new abstract method or a new interface method | `feat!:` (or a `BREAKING CHANGE:` footer), major | + | New API: a new class, an optional method with a default body, a new hook | `feat:`, minor | + | Fixes that keep the contract | `fix:`, patch | + | Docs, tests, CI, refactors with no behaviour change | `docs:`, `test:`, `ci:`, `refactor:`, `chore:`, no release | + + A `feat!:` also needs its entry in [upgrading.md](upgrading.md) in the same + pull request. +3. When you want to release, review the release pull request: reword entries + there if a title reads badly, then squash-merge it. release-please tags + `vX.Y.Z` on the merge commit and publishes the GitHub release with that + section as the notes. 4. Confirm Packagist picked the tag up: `composer show rtcamp/wp-primitives --all` lists the new version within a minute or two. If it does not, check the webhook delivery under the repository's Settings > Webhooks. +The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no +workflow runs on it. It only changes `CHANGELOG.md` and the manifest, and the +checks ran on every commit it lists, so it is safe to merge without them. +Switching the workflow to a GitHub App token would give it its own runs. + +Never push a `v*` tag or edit `.release-please-manifest.json` by hand. + Never move, delete or re-push a published tag: consumers and Packagist have already resolved it. Fix forward with a patch release instead. diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 0000000..e7c1f63 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,67 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "packages": { + ".": { + "release-type": "php", + "changelog-path": "CHANGELOG.md", + "include-v-in-tag": true, + "include-component-in-tag": false, + "changelog-sections": [ + { + "type": "feat", + "section": "Added" + }, + { + "type": "fix", + "section": "Fixed" + }, + { + "type": "perf", + "section": "Changed" + }, + { + "type": "revert", + "section": "Changed" + }, + { + "type": "build", + "section": "Changed" + }, + { + "type": "security", + "section": "Security" + }, + { + "type": "docs", + "section": "Documentation", + "hidden": true + }, + { + "type": "style", + "section": "Styles", + "hidden": true + }, + { + "type": "chore", + "section": "Miscellaneous", + "hidden": true + }, + { + "type": "refactor", + "section": "Code Refactoring", + "hidden": true + }, + { + "type": "test", + "section": "Tests", + "hidden": true + }, + { + "type": "ci", + "section": "Continuous Integration", + "hidden": true + } + ] + } + } +} From 240bc7f91dc8144592cd15e29a07f68154afae7d Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 04:45:33 +0530 Subject: [PATCH 3/6] ci: prefix Dependabot commits with chore Dependabot picks its commit style from history unless told. Pinning chore(deps) keeps its titles valid for the PR title check and keeps dependency bumps out of release-please's releasable commits. --- .github/dependabot.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9e5e657..38c08bd 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,6 +7,9 @@ updates: labels: - "dependencies" open-pull-requests-limit: 10 + commit-message: + prefix: "chore" + include: "scope" groups: composer: patterns: @@ -19,3 +22,6 @@ updates: labels: - "dependencies" open-pull-requests-limit: 10 + commit-message: + prefix: "chore" + include: "scope" From 709968cb9dd9ca5f94b3fb4ea5b8cc19a5279929 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Fri, 6 Nov 2026 05:21:34 +0530 Subject: [PATCH 4/6] ci: drop wip mode and the security section from the release setup The title check's wip mode posts a commit status, which a fork pull request's read-only token can't write, so it now just passes or fails and needs only pull-requests: read. Both workflows use github.token. The security changelog section is gone: the title check doesn't accept a security type, so security fixes are titled fix(security). --- .github/workflows/pr-title.yml | 5 +---- .github/workflows/release.yml | 2 +- release-please-config.json | 4 ---- 3 files changed, 2 insertions(+), 9 deletions(-) diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml index a8a40bd..14f5bd9 100644 --- a/.github/workflows/pr-title.yml +++ b/.github/workflows/pr-title.yml @@ -24,11 +24,8 @@ jobs: runs-on: ubuntu-latest permissions: pull-requests: read - statuses: write steps: - name: Validate pull request title uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1 env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - wip: true + GITHUB_TOKEN: ${{ github.token }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7cdb83e..432075e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -34,6 +34,6 @@ jobs: - name: Open or update the release pull request, or publish the release uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 with: - token: ${{ secrets.GITHUB_TOKEN }} + token: ${{ github.token }} config-file: release-please-config.json manifest-file: .release-please-manifest.json diff --git a/release-please-config.json b/release-please-config.json index e7c1f63..9aaa75e 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -27,10 +27,6 @@ "type": "build", "section": "Changed" }, - { - "type": "security", - "section": "Security" - }, { "type": "docs", "section": "Documentation", From fd43ef4f2798327ae13744800e2a0047c98f4ec7 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Fri, 6 Nov 2026 05:56:25 +0530 Subject: [PATCH 5/6] docs(ci): note how release PRs get checks if tests become required auto-merge.yml expects the Test and Measure jobs to be required so a red Dependabot update can't merge, but a release pull request opened with GITHUB_TOKEN starts no runs and would wait on them forever. The release workflow's comment now says so and names the two ways out: a GitHub App token, or a maintainer pushing an empty commit to the release branch. --- .github/workflows/release.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 432075e..82fdbd7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -5,8 +5,10 @@ name: Release # request tags vX.Y.Z on main and publishes the GitHub release with the changelog entry as notes. # # The release pull request is opened with GITHUB_TOKEN, so GitHub starts no workflow runs on it -# (no tests, no PR title check). That is why neither check is a required status check. Switching -# the token below to a GitHub App token would give the release pull request its CI runs. +# (no tests, no PR title check). Keep the PR title check out of the required checks. If the Test +# and Measure jobs become required, as auto-merge.yml expects for Dependabot, a release pull +# request waits on checks that never start: switch the token below to a GitHub App token, which +# starts them, or have a maintainer push an empty commit to the release branch, which does too. on: push: From 557a6e09dfd055fda8828a73a9144fed4d3bacd3 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Tue, 10 Nov 2026 00:48:02 +0530 Subject: [PATCH 6/6] docs: reword release entries through the merged PR, not the release PR release-please rebuilds the release pull request and its branch on every run, so a hand edit there is lost. Point at a BEGIN_COMMIT_OVERRIDE block in the merged PR's description instead. Drop the BREAKING CHANGE footer option: the squash body comes from the branch's commit messages, so a footer in the PR description never reaches main. --- CHANGELOG.md | 2 +- docs/maintainers.md | 26 +++++++++++++++++++++----- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 48f2edd..afe34ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). From 2.2.0 on, entries are written by [release-please](https://github.com/googleapis/release-please) from the Conventional Commit pull request titles merged to `main`. Don't edit this file by hand; -to reword an entry, edit the open release pull request. +to reword an entry, see [Releasing](docs/maintainers.md#releasing). ### Added diff --git a/docs/maintainers.md b/docs/maintainers.md index c9e2ba1..c8d7cf0 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -161,17 +161,33 @@ Releases are cut by [release-please](https://github.com/googleapis/release-pleas | Change | Title | | --- | --- | - | Anything breaking in `inc/Contracts/` or in documented behaviour, including a new abstract method or a new interface method | `feat!:` (or a `BREAKING CHANGE:` footer), major | + | Anything breaking in `inc/Contracts/` or in documented behaviour, including a new abstract method or a new interface method | `feat!:`, major | | New API: a new class, an optional method with a default body, a new hook | `feat:`, minor | | Fixes that keep the contract | `fix:`, patch | | Docs, tests, CI, refactors with no behaviour change | `docs:`, `test:`, `ci:`, `refactor:`, `chore:`, no release | A `feat!:` also needs its entry in [upgrading.md](upgrading.md) in the same pull request. -3. When you want to release, review the release pull request: reword entries - there if a title reads badly, then squash-merge it. release-please tags - `vX.Y.Z` on the merge commit and publishes the GitHub release with that - section as the notes. + + The `!` has to be in the title. The squash commit's body is built from the + branch's commit messages, so a `BREAKING CHANGE:` footer written in the PR + description never reaches `main`. +3. When you want to release, review the release pull request, then + squash-merge it. release-please tags `vX.Y.Z` on the merge commit and + publishes the GitHub release with that section as the notes. + + Don't edit the release pull request or its branch: release-please rebuilds + both on every run, so the edit is lost. To reword an entry, edit the + description of the merged pull request it came from and add: + + ```text + BEGIN_COMMIT_OVERRIDE + fix: the wording you want + END_COMMIT_OVERRIDE + ``` + + The next release-please run (any push to `main`, or re-running the + workflow) rebuilds the release pull request from it. 4. Confirm Packagist picked the tag up: `composer show rtcamp/wp-primitives --all` lists the new version within a minute or two. If it does not, check the webhook delivery under the repository's Settings > Webhooks.