Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
16 changes: 7 additions & 9 deletions .github/ISSUE_TEMPLATE/task.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,6 @@ $ ...
- [ ]

### Housekeeping
- [ ] `CHANGELOG.md` entry under `## [Unreleased]`

---

Expand All @@ -117,19 +116,18 @@ $ ...

| | |
|---|---|
| **Base your branch on** | `release/<milestone>` |
| **Branch name** | `<milestone>/task/<slug>` |
| **PR target** | `release/<milestone>` |
| **PR title** | `[<milestone>] <commit-subject>` |
| **Commit style** | [Conventional Commits](https://www.conventionalcommits.org/) |
| **Base your branch on** | `main` |
| **Branch name** | `<type>/<slug>`, e.g. `fix/feature-selector-closure` |
| **PR target** | `main` |
| **PR title** | A [Conventional Commit](https://www.conventionalcommits.org/) `<type>(<scope>): <changelog entry>` |

```bash
git fetch origin
git checkout release/<milestone>
git checkout main
git pull
git checkout -b <milestone>/task/<slug>
git checkout -b <type>/<slug>
# work, commit
git push -u origin <milestone>/task/<slug>
git push -u origin <type>/<slug>
```

PR description starts with `Closes #<this-issue>` so the Project card auto-moves to Done on merge.
Expand Down
6 changes: 6 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ updates:
labels:
- "dependencies"
open-pull-requests-limit: 10
commit-message:
prefix: "chore"
include: "scope"
groups:
composer:
patterns:
Expand All @@ -19,3 +22,6 @@ updates:
labels:
- "dependencies"
open-pull-requests-limit: 10
commit-message:
prefix: "chore"
include: "scope"
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/auto-merge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
31 changes: 31 additions & 0 deletions .github/workflows/pr-title.yml
Original file line number Diff line number Diff line change
@@ -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 }}
41 changes: 41 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
".": "2.1.0"
}
6 changes: 3 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
67 changes: 47 additions & 20 deletions docs/maintainers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.

63 changes: 63 additions & 0 deletions release-please-config.json
Original file line number Diff line number Diff line change
@@ -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
}
]
}
}
}
Loading