Repository navigation
ci: release the starter with release-please - #835
Conversation
… chore Merge commits put non-Conventional subjects on main, and Dependabot's copied "Chore(deps): Bump" style is not a valid Conventional Commit type. Both would trip the new PR title check and release-please.
Pull request titles become the Conventional Commit subjects on main. release-please reads them, keeps a release pull request open that bumps package.json, package-lock.json and the style.css Version header, and writes CHANGELOG.md; merging it tags vX.Y.Z and publishes the release. - release.yml and pr-title.yml (the 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 - "## Unreleased" stays, since projects made from the starter finalise it with npm run release:changelog; release-please inserts below it - init cleanup removes the release workflow and config, so a new theme does not inherit the starter's version history - contributing, initialization and maintainer docs follow the new flow
Init used to remove the release workflow and config, so a new theme fell back to release:bump and release:changelog. A new "release" feature (on by default) now sets the project up for release-please: - it copies bin/features/release/release.yml to .github/workflows/release.yml and release-please-config.json to the root; - it seeds .release-please-manifest.json at 0.0.0 (nothing released yet), sets initial-version to the version init wrote, so the first release is exactly that version, and sets bootstrap-sha to the HEAD init ran on, so starter commits stay out of the first changelog; - during first setup it removes the starter's CHANGELOG.md, which release-please writes afresh on the first release. Turning the feature off removes the workflow and config and keeps the manifest; turning it on again carries on from the recorded version. The starter's own release machinery moves to starter-only paths (.github/workflows/release-starter.yml, .github/release-please/), which cleanup removes, so it never ships into a project, including one that opts out. The project workflow documents the GITHUB_TOKEN limits: tags it creates don't start `on: push: tags` workflows, so deploys belong in the release workflow, gated on its release-created output.
wp-shared-workflows is not adding cd-release-please.yml after all: the release workflow stays a plain release-please-action job in each project.
There was a problem hiding this comment.
🟡 Changes recommended
The workflow fails for fork PRs and rejects security titles supported by the release configuration, while release toggling loses the original changelog boundary and the new initialization/deletion behavior lacks automated tests.
2 open issues
What changed in this PR
Adds release-please automation for the starter and an enabled-by-default release feature for themes created through init, keeping project release history separate from the starter.
Changes:
- Adds release workflows and configuration to update versions, generate changelogs, and publish releases.
- Extends init with release-state seeding, feature toggles, and starter-only cleanup.
- Aligns PR title validation, automated merges, Dependabot prefixes, and documentation with Conventional Commits.
| File | Description |
|---|---|
style.css |
Adds markers for automated theme version updates. |
docs/internal/maintenance.md |
Documents starter releases and validation procedures. |
docs/initialization.md |
Explains project release setup, toggles, and cleanup. |
CONTRIBUTING.md |
Requires Conventional Commit PR titles. |
CHANGELOG.md |
Explains automated entries and retains the manual-release heading. |
bin/scaffold.config.js |
Adds the release feature, state seeding, and cleanup targets. |
bin/features/release/release.yml |
Provides the generated project release workflow. |
bin/features/release/release-please-config.json |
Defines project version updates and changelog sections. |
.github/workflows/release-starter.yml |
Automates releases of the starter itself. |
.github/workflows/pr-title.yml |
Adds Conventional Commit title validation. |
.github/workflows/auto-merge.yml |
Switches automated merges to squash merging. |
.github/release-please/manifest.json |
Seeds the starter’s released version at 2.0.0. |
.github/release-please/config.json |
Configures starter version updates and changelog sections. |
.github/dependabot.yml |
Sets consistent chore prefixes across ecosystems. |
Review effort: Balanced
New themes no longer get release-please from init: the release feature, its bin/features/release/ templates and the seeding of a fresh release history are gone, so there is one release workflow to maintain and Dependabot keeps its pins current. Init cleanup still removes the starter's own release workflow, config and manifest, which live at starter-only paths, so projects keep releasing by hand as before. Also from review: the PR title check no longer uses wip mode, which posts a commit status a fork's read-only token can't write; the workflows use github.token; and the security changelog section is gone, since the title check doesn't accept a security type.
Init cleanup also runs on re-init and --clean and deletes its targets recursively, so the generic .github/release-please/ would take a project's own release-please config and manifest with it if the project used that layout. Name the folder for the starter, like release-starter.yml, so cleanup only ever removes the starter's files.
There was a problem hiding this comment.
🔵 Needs a closer look
The cleanup contract lacks regression coverage using the real scaffold config to verify that init, re-init, and --clean remove starter release files while preserving project-owned release configuration and unrelated workflows.
1 open issue
Review effort: Balanced
New projects come from composer create-project, which installs the latest tag, so a dependency fix on main reaches nobody until it is released. Prefix Dependabot commits with build, which the changelog lists under Changed and release-please counts as releasable. Each merge only updates the open release pull request; a release still happens only when a maintainer merges that.
There was a problem hiding this comment.
🔵 Needs a closer look
Human assessment is needed because existing tests bypass the real scaffold configuration, leaving starter-file cleanup and preservation of project-owned release files unverified.
No open issues 🎉
1 resolved since last review
Review effort: Balanced
Adi-ty
left a comment
There was a problem hiding this comment.
Approving! Just two things to check:
- The Dependabot PRs here use
chore(deps)titles, so they won't trigger a release. - The
--squashchange looks good, but auto-merge is currently disabled in repo settings, causing the workflow to fail. We need to either enable "Allow auto-merge" in repo settings or remove--autofrom the workflow.

What this PR does
Releases the starter itself with release-please, the flow proposed in rtCamp/wp-shared-workflows#45: pull requests are squash-merged with Conventional Commit titles, release-please keeps one release pull request open that bumps the version and writes
CHANGELOG.md, and merging it tagsvX.Y.Zand publishes the GitHub release.Projects made from the starter are unchanged: init cleanup removes these release files, and projects keep releasing by hand with
npm run release:bumpandnpm run release:changelog.Closes
N/A
Changes
.github/workflows/release-starter.ymlrunsgoogleapis/release-please-actionv5.0.0 (pinned by SHA) on every push tomain, with write permissions on that job only..github/release-starter/config.jsonusesrelease-type: node(package.json,package-lock.jsonand thestyle.cssVersion:line, the last throughextra-filesandx-release-please-start-version/x-release-please-endmarker lines, since WordPress reads the rest of theVersion:line as the value). Commit types map to Keep a Changelog headings:featAdded,fixFixed,perf/revert/buildChanged;docs,chore,ci,test,refactorandstyleare hidden and cut no release.manifest.jsonstarts at2.0.0, the latest release..github/workflows/release-starter.ymland.github/release-starter/. Both are named for the starter: cleanup also runs on re-init and--clean, so a generic path such as.github/release-please/could delete a project's own release-please files..github/workflows/pr-title.yml(new), the same Conventional Commit title check plugin-elementary runs.auto-merge.ymlsquash-merges Dependabot pull requests instead of merge-committing them.pr-title.ymldropswipmode: it posts a commit status, which a fork pull request's read-only token can't write.dependabot.ymlsets thebuildprefix (build(deps)/build(deps-dev)withinclude: scope). New projects come fromcomposer create-project, which installs the latest tag, so dependency fixes have to be released to reach anyone:buildis listed under Changed and counts as releasable. Each merge only updates the open release pull request; a release happens when a maintainer merges that.CHANGELOG.mdkeeps## Unreleased(projects inherit this file andrelease:changelogneeds that heading); release-please inserts each release below it, and a comment says not to add entries there in the starter.CONTRIBUTING.mdasks for a Conventional PR title;docs/internal/maintenance.mdgains a "Releasing" section;docs/initialization.mdlists the new cleanup targets.How I verified
actionlintandyamllintpass on the workflows; the JSON files parse;bin/scaffold.config.jsloads.Version:line, and the changelog updater puts a sample release between## Unreleasedand## 2.0.0.mainalready has 8 Dependabot bumps since v2.0.0 (Chore(deps): Bump shell-quote from 1.10.0 to 1.12.0 #814 to Chore(deps): Bump follow-redirects from 1.16.0 to 1.16.2 #823, including the shell-quote, proxy-addr, follow-redirects and fast-uri security fixes). They are titledChore(deps), which isn't releasable, socomposer create-projectstill installs v2.0.0's lockfile. The first releasable merge (abuild(deps)bump or afix:, for example fix(ci): separate file and project lint commands #834) opens a 2.0.1 release PR, and that release carries those fixes too.Acceptance criteria
Runtime behavior
Release (starter)run passesCode quality
Housekeeping
CHANGELOG.mdentry: release-please writes itReviewer notes
Repository settings to change when this merges:
PR_TITLE).GITHUB_TOKEN, which starts no workflow runs. A GitHub App token would fix that later.Release automation for projects made from the starter is left for later: it needs a one-time setup hook in wp-tooling's init engine to give each project a fresh release history.