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/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" 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/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 }} diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml new file mode 100644 index 0000000..14f5bd9 --- /dev/null +++ b/.github/workflows/pr-title.yml @@ -0,0 +1,31 @@ +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 + steps: + - name: Validate pull request title + uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1 + env: + GITHUB_TOKEN: ${{ github.token }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..82fdbd7 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,41 @@ +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). 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: + 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: ${{ 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 fdafee2..afe34ae 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, see [Releasing](docs/maintainers.md#releasing). ### Added @@ -180,7 +181,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..c8d7cf0 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,62 @@ 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 +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!:`, 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. + + 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 ``` -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. + 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. +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..9aaa75e --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,63 @@ +{ + "$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": "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 + } + ] + } + } +}