From 9befeda5074921ea21290c377cf314a0396ba75f Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 04:45:33 +0530 Subject: [PATCH 1/7] ci: squash-merge bot pull requests and prefix Dependabot commits with 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. --- .github/dependabot.yml | 9 +++++++++ .github/workflows/auto-merge.yml | 4 ++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 186676fa..861c3ff5 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,6 +7,9 @@ updates: time: '00:00' timezone: 'Asia/Calcutta' open-pull-requests-limit: 10 + commit-message: + prefix: chore + include: scope labels: - GHA - Dependencies @@ -18,6 +21,9 @@ updates: time: '00:00' timezone: 'Asia/Calcutta' open-pull-requests-limit: 10 + commit-message: + prefix: chore + include: scope labels: - NPM - Dependencies @@ -38,6 +44,9 @@ updates: time: '00:00' timezone: 'Asia/Calcutta' open-pull-requests-limit: 10 + commit-message: + prefix: chore + include: scope labels: - Composer - Dependencies diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index ba30c9cc..dec175cb 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -32,7 +32,7 @@ jobs: if: | contains( github.event.workflow_run.head_commit.message, 'version-update:semver-minor' ) || contains( github.event.workflow_run.head_commit.message, 'version-update:semver-patch' ) - run: gh pr merge "$PR_NUMBER" --auto --merge --delete-branch + run: gh pr merge "$PR_NUMBER" --auto --squash --delete-branch env: GH_REPO: ${{ github.repository }} PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }} @@ -53,7 +53,7 @@ jobs: endsWith(github.event.workflow_run.head_commit.message, format('{0} {1}', 'rtBot', '<43742164+rtBot@users.noreply.github.com>')) && github.event.workflow_run.head_commit.author.name == 'rtBot' && github.event.workflow_run.head_commit.author.email == '43742164+rtBot@users.noreply.github.com' - run: gh pr merge "$PR_NUMBER" --auto --merge --delete-branch + run: gh pr merge "$PR_NUMBER" --auto --squash --delete-branch env: GH_REPO: ${{ github.repository }} PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }} From a41ccd43c265b225182957532e01ed5dacd5e032 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 04:45:33 +0530 Subject: [PATCH 2/7] ci: cut releases of the starter 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 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 --- .github/workflows/pr-title.yml | 34 ++++++++++++++++ .github/workflows/release.yml | 39 ++++++++++++++++++ .release-please-manifest.json | 3 ++ CHANGELOG.md | 2 + CONTRIBUTING.md | 2 +- bin/scaffold.config.js | 3 ++ docs/initialization.md | 2 +- docs/internal/maintenance.md | 12 +++++- release-please-config.json | 73 ++++++++++++++++++++++++++++++++++ style.css | 2 + 10 files changed, 169 insertions(+), 3 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/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml new file mode 100644 index 00000000..a8a40bdf --- /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 00000000..7cdb83e7 --- /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 00000000..895bf0e3 --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "2.0.0" +} diff --git a/CHANGELOG.md b/CHANGELOG.md index a99c2233..54d32b6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ All notable changes to this project are documented in this file. 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 ## 2.0.0 - 2026-10-01 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5758ecda..fbf9683c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Run the relevant focused tests and lint commands in [Local development](docs/loc - [ ] The relevant focused tests and lint commands pass. - [ ] New/changed behavior is covered by tests. -- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/). +- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/), and so does the PR title: pull requests are squash-merged, and the title becomes the commit on `main`. ## License diff --git a/bin/scaffold.config.js b/bin/scaffold.config.js index bf46a053..7c56406e 100644 --- a/bin/scaffold.config.js +++ b/bin/scaffold.config.js @@ -166,6 +166,9 @@ module.exports = { '.github/prompts', '.github/instructions', 'languages', + 'release-please-config.json', + '.release-please-manifest.json', + '.github/workflows/release.yml', ], }, diff --git a/docs/initialization.md b/docs/initialization.md index f33050a1..a0397d7c 100644 --- a/docs/initialization.md +++ b/docs/initialization.md @@ -60,7 +60,7 @@ npm run init -- --name="Acme Blog" --version=1.0.0 --yes --remove-examples | Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations. | | State | `.wp-scaffold.json` records identity and feature choices; do not hand-edit it. | | Autoload | Setup regenerates Composer's autoloader. | -| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed. Workflows, issue templates, the PR template, `dependabot.yml`, and `release.yml` stay untouched. | +| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, along with the starter's own release automation (`.github/workflows/release.yml`, `release-please-config.json`, `.release-please-manifest.json`). The other workflows, issue templates, the PR template, `dependabot.yml`, and `.github/release.yml` stay untouched. | | AI instructions | After a successful change, the wrapper runs `sync-ai`; in a standalone project with the framework installed, it refreshes the generated framework PHP instructions. It does not restore the removed prompts or theme-specific rules. | | Retained files | Theme source, `bin/`, Claude skills, documentation, and test infrastructure remain; files belonging to removed example sets do not. | diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index 0c392dfd..89fe0a14 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -18,7 +18,7 @@ If an installation route or feature cannot be exercised, report the missing prer ### Cleanup checks -Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, while workflows, issue templates, and the PR template stay untouched. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. +Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the release automation (`.github/workflows/release.yml`, `release-please-config.json`, `.release-please-manifest.json`), while the other workflows, issue templates, and the PR template stay untouched. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. Check references in retained documentation and AI instructions. Use upstream source links for optional examples or starter-only files that cleanup may remove. Do not silently change the cleanup contract as part of a documentation correction. @@ -90,6 +90,16 @@ node /path/to/action-docusaurus-build/cli.mjs build \ Check the homepage, navigation order, root-guide links, anchors, and mobile layout. The builder fails on broken internal links and missing repository-file links. Also check external links and root Markdown, which are not fully covered by the site build. Update incoming links whenever a guide is moved or removed, and [record the results](#record-validation-results). +## Releasing the theme + +Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release.yml`). Projects made from it do not inherit this: init removes the release workflow and config, and projects release with `npm run release:bump` and `npm run release:changelog`. + +1. Pull requests are squash-merged, so each PR title becomes one Conventional Commit on `main`. release-please reads those subjects and keeps a release pull request open that bumps the version in `package.json`, `package-lock.json` and `style.css` (between the `x-release-please-start-version` and `x-release-please-end` lines), and writes the next `CHANGELOG.md` section. +2. The title's type decides the version: `fix:` is a patch, `feat:` a minor, and `feat!:` (or a `BREAKING CHANGE:` footer) a major. Anything that changes what init generates, renames a script or a file a project relies on, or raises a minimum version is a `feat!:`. `docs:`, `test:`, `ci:`, `chore:` and `refactor:` cut no release. Dependabot pull requests are prefixed `chore` (see `.github/dependabot.yml`), so they cut no release on their own. Keep it that way: release-please cuts a release for any type with a visible changelog section, `build` included. +3. When you want to release, run the [release validation](#release-validation) against the release pull request's branch, reword its entries if a title reads badly, then squash-merge it. release-please tags `vX.Y.Z` and publishes the GitHub release with that section as the notes. + +The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no workflow runs on it, and the PR title check is not a required status check for that reason. A GitHub App token in the workflow would give the release pull request its own runs. Never push a `v*` tag or edit `.release-please-manifest.json` by hand. + ## Knowledge graph The graph is optional and may be stale. Verify exact behavior from current source when documenting it. For a deliberate artifact refresh, run local `graphify update .` and `graphify cluster-only . --no-label --no-viz`, then review the graph/report diff separately. Do not overwrite the theme's committed graph with a merged cross-repository graph during routine documentation work. diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 00000000..c3b80485 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,73 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "packages": { + ".": { + "release-type": "node", + "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 + } + ], + "extra-files": [ + { + "type": "generic", + "path": "style.css" + } + ] + } + } +} diff --git a/style.css b/style.css index fad34d79..e8f2de62 100644 --- a/style.css +++ b/style.css @@ -4,7 +4,9 @@ * Theme Name: Elementary Theme * Theme URI: https://rtcamp.com/ * Description: A modern starter theme for developing Full Site Editing (FSE) block-based WordPress themes with comprehensive developer tools and best practices. + * x-release-please-start-version * Version: 2.0.0 + * x-release-please-end * Author: rtCamp * Author URI: https://rtcamp.com/ * Tags: fse From ab9ac5ffb36926f664f7f5da4a931ffa1f4622e8 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 17:57:51 +0530 Subject: [PATCH 3/7] feat(init): give new themes release-please of their own 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. --- .../release-please/config.json | 0 .../release-please/manifest.json | 0 .../{release.yml => release-starter.yml} | 12 ++- CHANGELOG.md | 2 +- .../release/release-please-config.json | 73 ++++++++++++++++ bin/features/release/release.yml | 62 +++++++++++++ bin/scaffold.config.js | 86 ++++++++++++++++++- docs/initialization.md | 27 +++++- docs/internal/maintenance.md | 6 +- 9 files changed, 254 insertions(+), 14 deletions(-) rename release-please-config.json => .github/release-please/config.json (100%) rename .release-please-manifest.json => .github/release-please/manifest.json (100%) rename .github/workflows/{release.yml => release-starter.yml} (68%) create mode 100644 bin/features/release/release-please-config.json create mode 100644 bin/features/release/release.yml diff --git a/release-please-config.json b/.github/release-please/config.json similarity index 100% rename from release-please-config.json rename to .github/release-please/config.json diff --git a/.release-please-manifest.json b/.github/release-please/manifest.json similarity index 100% rename from .release-please-manifest.json rename to .github/release-please/manifest.json diff --git a/.github/workflows/release.yml b/.github/workflows/release-starter.yml similarity index 68% rename from .github/workflows/release.yml rename to .github/workflows/release-starter.yml index 7cdb83e7..eac59898 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release-starter.yml @@ -1,4 +1,4 @@ -name: Release +name: Release (starter) # 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 @@ -7,6 +7,12 @@ name: Release # 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. +# +# This file releases the starter itself, from the starter-only config in .github/release-please/. +# Init cleanup removes both. A project made from the starter gets its own +# .github/workflows/release.yml from bin/features/release/ when init's "release" feature is on +# (the default), with release-please-config.json and a fresh manifest at the root. Keep this +# workflow and the bin/features/release/ copy in step. on: push: @@ -35,5 +41,5 @@ jobs: 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 + config-file: .github/release-please/config.json + manifest-file: .github/release-please/manifest.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 54d32b6a..829424e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to this project are documented in this file. 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 diff --git a/bin/features/release/release-please-config.json b/bin/features/release/release-please-config.json new file mode 100644 index 00000000..c3b80485 --- /dev/null +++ b/bin/features/release/release-please-config.json @@ -0,0 +1,73 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "packages": { + ".": { + "release-type": "node", + "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 + } + ], + "extra-files": [ + { + "type": "generic", + "path": "style.css" + } + ] + } + } +} diff --git a/bin/features/release/release.yml b/bin/features/release/release.yml new file mode 100644 index 00000000..8e82cc3b --- /dev/null +++ b/bin/features/release/release.yml @@ -0,0 +1,62 @@ +name: Release + +# release-please reads the Conventional Commit subjects squash-merged to main and keeps one +# release pull request open that bumps the version (package.json, package-lock.json and the +# style.css header) 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. +# +# Before the first run: +# - Allow GitHub Actions to create pull requests (repository or organisation settings, Actions, +# General, Workflow permissions). Without it release-please cannot open its pull request. +# - Squash-merge pull requests and use the pull request title as the commit subject, so each title +# becomes one Conventional Commit on main (the PR Title workflow checks the format). +# +# The tag and the release are created with GITHUB_TOKEN, and GitHub starts no workflow runs for +# events GITHUB_TOKEN causes. A workflow that deploys `on: push: tags` never fires for these tags. +# Deploy from this workflow instead, in a job gated on the release output: +# +# deploy: +# needs: release-please +# if: needs.release-please.outputs.release-created == 'true' +# +# or switch the token below to a GitHub App token. The release pull request is opened with +# GITHUB_TOKEN too, so it gets no CI runs; that is why neither check should be a required status +# check unless you switch tokens. +# +# rtCamp/wp-shared-workflows is adding a reusable cd-release-please.yml. Once it is released, +# this file can shrink to a caller of it. + +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 + outputs: + release-created: ${{ steps.release.outputs.release_created }} + tag-name: ${{ steps.release.outputs.tag_name }} + version: ${{ steps.release.outputs.version }} + steps: + - name: Open or update the release pull request, or publish the release + id: 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/bin/scaffold.config.js b/bin/scaffold.config.js index 7c56406e..b0174a32 100644 --- a/bin/scaffold.config.js +++ b/bin/scaffold.config.js @@ -12,6 +12,62 @@ const tailwindEntry = () => 'functions.php'; const tailwindConst = (api) => `${api.identity.constantPrefix}_ENABLE_TAILWIND`; +// Release automation (release-please). The "release" feature copies the workflow +// and config from bin/features/release/; seedRelease then gives a new project a +// release history of its own. The starter's own config and manifest live in +// .github/release-please/, which cleanup removes. +const RELEASE_MANIFEST = '.release-please-manifest.json'; +const RELEASE_CONFIG = 'release-please-config.json'; + +// HEAD of the repository init runs in, or null without git or commits. +const gitHead = (root) => { + try { + return require('child_process') + .execFileSync('git', ['rev-parse', '--verify', '-q', 'HEAD'], { + cwd: root, + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'ignore'], + }) + .trim(); + } catch { + return null; + } +}; + +const seedRelease = (api) => { + // The manifest records the last released version, so a project that turns the + // feature off and on again keeps its history. "0.0.0" tells release-please + // nothing is released yet. + const fresh = !api.exists(RELEASE_MANIFEST); + if (fresh) { + api.editJson( + RELEASE_MANIFEST, + (manifest) => { + manifest['.'] = '0.0.0'; + }, + { create: true, indentFrom: RELEASE_CONFIG } + ); + } + const released = JSON.parse(api.read(RELEASE_MANIFEST))['.']; + api.editJson(RELEASE_CONFIG, (config) => { + // Until the first release, that release is the version init wrote. + if ('0.0.0' === released) { + config.packages['.']['initial-version'] = api.identity.version; + } + // Commits up to this one (the starter's history, when the clone keeps it) + // stay out of the first changelog entry. + const head = fresh ? gitHead(api.root) : null; + if (head) { + config['bootstrap-sha'] = head; + } + }); + // During first setup (no .wp-scaffold.json yet) CHANGELOG.md is still the + // starter's. Drop it: release-please writes a fresh one on the first release. + if (fresh && !api.exists('.wp-scaffold.json')) { + api.remove('CHANGELOG.md'); + } +}; + module.exports = { kind: 'theme', vendor: 'rtcamp', @@ -83,6 +139,29 @@ module.exports = { detect: (api) => true === api.readDefine(tailwindEntry(api), tailwindConst(api)), }, + { + key: 'release', + defaultOn: true, + label: 'Release automation (release-please)', + description: + 'A release pull request kept up to date from Conventional Commit PR titles; merging it bumps style.css and package.json, writes CHANGELOG.md, tags vX.Y.Z and publishes the GitHub release. Default on. Needs squash merges with the PR title as the commit subject, and Actions allowed to create pull requests.', + apply: { + files: [ + { + from: 'release/release.yml', + to: '.github/workflows/release.yml', + }, + { + from: 'release/release-please-config.json', + to: RELEASE_CONFIG, + }, + ], + }, + onEnable: seedRelease, + // Disabling removes the workflow and config (apply.files) and keeps the + // manifest, the record of what was released. + onDisable: () => {}, + }, { key: 'hmr', defaultOn: true, @@ -166,9 +245,10 @@ module.exports = { '.github/prompts', '.github/instructions', 'languages', - 'release-please-config.json', - '.release-please-manifest.json', - '.github/workflows/release.yml', + // The starter's own release workflow, config and manifest. A project gets + // its own from the "release" feature. + '.github/release-please', + '.github/workflows/release-starter.yml', ], }, diff --git a/docs/initialization.md b/docs/initialization.md index a0397d7c..d1295b39 100644 --- a/docs/initialization.md +++ b/docs/initialization.md @@ -55,12 +55,12 @@ npm run init -- --name="Acme Blog" --version=1.0.0 --yes --remove-examples | --- | --- | | Identity fields | Name, version, text domain, package, namespace, function prefix, constant prefix, and CSS prefix are derived and reviewed. | | Affected files | `style.css`, `functions.php`, `composer.json`, `package.json`, and text or file basenames containing starter identity tokens are personalized. | -| Version | Written to `style.css` and `package.json`. | +| Version | Written to `style.css` and `package.json`. With the release feature on, it also becomes `initial-version` in `release-please-config.json`, the version of the project's first release. | | Examples | Kept groups remain. Removed groups delete their configured paths and registration regions; markers are removed in either case. See [Included features](features.md). | -| Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations. | +| Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations; release automation (on by default) adds `.github/workflows/release.yml`, `release-please-config.json` and `.release-please-manifest.json`, and removes the starter's `CHANGELOG.md`. See [Releases](#releases). | | State | `.wp-scaffold.json` records identity and feature choices; do not hand-edit it. | | Autoload | Setup regenerates Composer's autoloader. | -| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, along with the starter's own release automation (`.github/workflows/release.yml`, `release-please-config.json`, `.release-please-manifest.json`). The other workflows, issue templates, the PR template, `dependabot.yml`, and `.github/release.yml` stay untouched. | +| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, along with the starter's own release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-please/`). The other workflows, issue templates, the PR template, `dependabot.yml`, and `.github/release.yml` stay untouched. | | AI instructions | After a successful change, the wrapper runs `sync-ai`; in a standalone project with the framework installed, it refreshes the generated framework PHP instructions. It does not restore the removed prompts or theme-specific rules. | | Retained files | Theme source, `bin/`, Claude skills, documentation, and test infrastructure remain; files belonging to removed example sets do not. | @@ -88,13 +88,32 @@ npm run init -- --list npm run init -- --list --json npm run init -- --enable=hmr --yes npm run init -- --disable=hmr --yes -npm run init -- --features=hmr --yes +npm run init -- --features=hmr,release --yes ``` `--features` sets the entire enabled set; `--enable` and `--disable` change one feature without replacing the others. Do not combine these forms. Help and `--list` are read-only. For machine-readable JSON without npm's banner, use `node bin/init.js --list --json`. Example removal belongs to initial setup: `--remove-examples=shortcode,patterns` removes those groups, and `--keep-examples` keeps every group. Do not use `--reinit` to restore examples or remove more groups after their markers have been consumed. Review source and registration together when making a manual change. +### Releases + +The `release` feature is on by default. It sets the project up for [release-please](https://github.com/googleapis/release-please): + +- `.github/workflows/release.yml` keeps one release pull request open on `main`, built from the Conventional Commit pull request titles merged since the last release. Merging it bumps `package.json`, `package-lock.json` and the `style.css` `Version:` line (between the `x-release-please-start-version` and `x-release-please-end` lines), writes the `CHANGELOG.md` section, tags `vX.Y.Z` and publishes the GitHub release. The `PR Title` workflow checks the title format. +- `release-please-config.json` carries `initial-version`, the version init wrote, so the first release is exactly that version. It also carries `bootstrap-sha` when init ran in a git repository, so commits from before init stay out of the first changelog entry. +- `.release-please-manifest.json` records the last released version. It starts at `0.0.0`, which release-please reads as "nothing released yet". Don't edit it, `CHANGELOG.md` or `v*` tags by hand once releases start. +- The starter's `CHANGELOG.md` is removed during setup; release-please writes a fresh one on the first release. + +Before the first release: + +- Allow GitHub Actions to create pull requests (repository or organisation settings, Actions, General, Workflow permissions). Client organisations often switch this off. +- Allow only squash merges, with the pull request title as the commit subject. +- If you deploy on tags: the tag and release are created with `GITHUB_TOKEN`, and GitHub starts no workflow runs for events `GITHUB_TOKEN` causes, so a workflow triggered `on: push: tags` never runs for them. Deploy from `release.yml` in a job with `needs: release-please` and `if: needs.release-please.outputs.release-created == 'true'`, or switch the workflow to a GitHub App token. The same limit means the release pull request gets no CI runs, so don't make checks on it required unless you switch tokens. + +A project that does not release versions (a site deployed from a branch, for example) can turn it off with `npm run init -- --disable=release --yes`; that removes the workflow and config and keeps the manifest. Then release by hand with `npm run release:bump` and `npm run release:changelog`, which need a `CHANGELOG.md` with an `## Unreleased` heading. If an existing project that already tags releases turns the feature on, set `.release-please-manifest.json` to its latest released version before the first run. + +rtCamp/wp-shared-workflows is adding a reusable `cd-release-please.yml`. Once it is released, the project workflow can shrink to a caller of it; the starter does not use it yet. + ### Optional dependencies - **Tailwind:** `npm run init -- --enable=tailwind --yes` changes declarations and creates the entry/config files; npm installation is separate. See [Tailwind](tailwind.md) for the theme integration and installation checks. diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index 89fe0a14..77769bc6 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -18,7 +18,7 @@ If an installation route or feature cannot be exercised, report the missing prer ### Cleanup checks -Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the release automation (`.github/workflows/release.yml`, `release-please-config.json`, `.release-please-manifest.json`), while the other workflows, issue templates, and the PR template stay untouched. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. +Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the starter's release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-please/`), while the other workflows, issue templates, and the PR template stay untouched. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. Check references in retained documentation and AI instructions. Use upstream source links for optional examples or starter-only files that cleanup may remove. Do not silently change the cleanup contract as part of a documentation correction. @@ -92,13 +92,13 @@ Check the homepage, navigation order, root-guide links, anchors, and mobile layo ## Releasing the theme -Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release.yml`). Projects made from it do not inherit this: init removes the release workflow and config, and projects release with `npm run release:bump` and `npm run release:changelog`. +Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-starter.yml`), from the starter-only config and manifest in `.github/release-please/`. Cleanup removes all three. Projects get release-please of their own through init's `release` feature: it copies `bin/features/release/release.yml` to `.github/workflows/release.yml` and copies `bin/features/release/release-please-config.json` to the root, then seeds a `0.0.0` manifest, `initial-version` and `bootstrap-sha` and removes the starter's `CHANGELOG.md` (see [initialization.md](../initialization.md#releases)). When you change the starter's workflow or config, make the same change in the `bin/features/release/` copies unless it is starter-only. 1. Pull requests are squash-merged, so each PR title becomes one Conventional Commit on `main`. release-please reads those subjects and keeps a release pull request open that bumps the version in `package.json`, `package-lock.json` and `style.css` (between the `x-release-please-start-version` and `x-release-please-end` lines), and writes the next `CHANGELOG.md` section. 2. The title's type decides the version: `fix:` is a patch, `feat:` a minor, and `feat!:` (or a `BREAKING CHANGE:` footer) a major. Anything that changes what init generates, renames a script or a file a project relies on, or raises a minimum version is a `feat!:`. `docs:`, `test:`, `ci:`, `chore:` and `refactor:` cut no release. Dependabot pull requests are prefixed `chore` (see `.github/dependabot.yml`), so they cut no release on their own. Keep it that way: release-please cuts a release for any type with a visible changelog section, `build` included. 3. When you want to release, run the [release validation](#release-validation) against the release pull request's branch, reword its entries if a title reads badly, then squash-merge it. release-please tags `vX.Y.Z` and publishes the GitHub release with that section as the notes. -The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no workflow runs on it, and the PR title check is not a required status check for that reason. A GitHub App token in the workflow would give the release pull request its own runs. Never push a `v*` tag or edit `.release-please-manifest.json` by hand. +The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no workflow runs on it, and the PR title check is not a required status check for that reason. A GitHub App token in the workflow would give the release pull request its own runs. Never push a `v*` tag or edit `.github/release-please/manifest.json` by hand. ## Knowledge graph From ec6e4db46643afd13b0fdff18f572bab042b9929 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 18:08:16 +0530 Subject: [PATCH 4/7] docs(init): drop the note about a reusable release workflow 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. --- bin/features/release/release.yml | 3 --- docs/initialization.md | 1 - 2 files changed, 4 deletions(-) diff --git a/bin/features/release/release.yml b/bin/features/release/release.yml index 8e82cc3b..c7bd8828 100644 --- a/bin/features/release/release.yml +++ b/bin/features/release/release.yml @@ -22,9 +22,6 @@ name: Release # or switch the token below to a GitHub App token. The release pull request is opened with # GITHUB_TOKEN too, so it gets no CI runs; that is why neither check should be a required status # check unless you switch tokens. -# -# rtCamp/wp-shared-workflows is adding a reusable cd-release-please.yml. Once it is released, -# this file can shrink to a caller of it. on: push: diff --git a/docs/initialization.md b/docs/initialization.md index d1295b39..f9325aba 100644 --- a/docs/initialization.md +++ b/docs/initialization.md @@ -112,7 +112,6 @@ Before the first release: A project that does not release versions (a site deployed from a branch, for example) can turn it off with `npm run init -- --disable=release --yes`; that removes the workflow and config and keeps the manifest. Then release by hand with `npm run release:bump` and `npm run release:changelog`, which need a `CHANGELOG.md` with an `## Unreleased` heading. If an existing project that already tags releases turns the feature on, set `.release-please-manifest.json` to its latest released version before the first run. -rtCamp/wp-shared-workflows is adding a reusable `cd-release-please.yml`. Once it is released, the project workflow can shrink to a caller of it; the starter does not use it yet. ### Optional dependencies From 5a194f2a14446ec827cbc9785e058341d3c4d59a Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Wed, 4 Nov 2026 18:45:20 +0530 Subject: [PATCH 5/7] ci: release only the starter itself, drop the init release feature 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. --- .github/release-please/config.json | 4 - .github/workflows/pr-title.yml | 5 +- .github/workflows/release-starter.yml | 9 +- CHANGELOG.md | 2 +- .../release/release-please-config.json | 73 ---------------- bin/features/release/release.yml | 59 ------------- bin/scaffold.config.js | 84 +------------------ docs/initialization.md | 24 +----- docs/internal/maintenance.md | 2 +- 9 files changed, 12 insertions(+), 250 deletions(-) delete mode 100644 bin/features/release/release-please-config.json delete mode 100644 bin/features/release/release.yml diff --git a/.github/release-please/config.json b/.github/release-please/config.json index c3b80485..0ef2d523 100644 --- a/.github/release-please/config.json +++ b/.github/release-please/config.json @@ -27,10 +27,6 @@ "type": "build", "section": "Changed" }, - { - "type": "security", - "section": "Security" - }, { "type": "docs", "section": "Documentation", diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml index a8a40bdf..14f5bd9f 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-starter.yml b/.github/workflows/release-starter.yml index eac59898..a5d02a44 100644 --- a/.github/workflows/release-starter.yml +++ b/.github/workflows/release-starter.yml @@ -8,11 +8,8 @@ name: Release (starter) # (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. # -# This file releases the starter itself, from the starter-only config in .github/release-please/. -# Init cleanup removes both. A project made from the starter gets its own -# .github/workflows/release.yml from bin/features/release/ when init's "release" feature is on -# (the default), with release-please-config.json and a fresh manifest at the root. Keep this -# workflow and the bin/features/release/ copy in step. +# This file releases the starter itself, from the config and manifest in .github/release-please/. +# Init cleanup removes all of them, so projects made from the starter don't inherit them. on: push: @@ -40,6 +37,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: .github/release-please/config.json manifest-file: .github/release-please/manifest.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 829424e8..918cedbb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to this project are documented in this file. 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 diff --git a/bin/features/release/release-please-config.json b/bin/features/release/release-please-config.json deleted file mode 100644 index c3b80485..00000000 --- a/bin/features/release/release-please-config.json +++ /dev/null @@ -1,73 +0,0 @@ -{ - "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", - "packages": { - ".": { - "release-type": "node", - "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 - } - ], - "extra-files": [ - { - "type": "generic", - "path": "style.css" - } - ] - } - } -} diff --git a/bin/features/release/release.yml b/bin/features/release/release.yml deleted file mode 100644 index c7bd8828..00000000 --- a/bin/features/release/release.yml +++ /dev/null @@ -1,59 +0,0 @@ -name: Release - -# release-please reads the Conventional Commit subjects squash-merged to main and keeps one -# release pull request open that bumps the version (package.json, package-lock.json and the -# style.css header) 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. -# -# Before the first run: -# - Allow GitHub Actions to create pull requests (repository or organisation settings, Actions, -# General, Workflow permissions). Without it release-please cannot open its pull request. -# - Squash-merge pull requests and use the pull request title as the commit subject, so each title -# becomes one Conventional Commit on main (the PR Title workflow checks the format). -# -# The tag and the release are created with GITHUB_TOKEN, and GitHub starts no workflow runs for -# events GITHUB_TOKEN causes. A workflow that deploys `on: push: tags` never fires for these tags. -# Deploy from this workflow instead, in a job gated on the release output: -# -# deploy: -# needs: release-please -# if: needs.release-please.outputs.release-created == 'true' -# -# or switch the token below to a GitHub App token. The release pull request is opened with -# GITHUB_TOKEN too, so it gets no CI runs; that is why neither check should be a required status -# check unless you switch tokens. - -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 - outputs: - release-created: ${{ steps.release.outputs.release_created }} - tag-name: ${{ steps.release.outputs.tag_name }} - version: ${{ steps.release.outputs.version }} - steps: - - name: Open or update the release pull request, or publish the release - id: 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/bin/scaffold.config.js b/bin/scaffold.config.js index b0174a32..b8047791 100644 --- a/bin/scaffold.config.js +++ b/bin/scaffold.config.js @@ -12,62 +12,6 @@ const tailwindEntry = () => 'functions.php'; const tailwindConst = (api) => `${api.identity.constantPrefix}_ENABLE_TAILWIND`; -// Release automation (release-please). The "release" feature copies the workflow -// and config from bin/features/release/; seedRelease then gives a new project a -// release history of its own. The starter's own config and manifest live in -// .github/release-please/, which cleanup removes. -const RELEASE_MANIFEST = '.release-please-manifest.json'; -const RELEASE_CONFIG = 'release-please-config.json'; - -// HEAD of the repository init runs in, or null without git or commits. -const gitHead = (root) => { - try { - return require('child_process') - .execFileSync('git', ['rev-parse', '--verify', '-q', 'HEAD'], { - cwd: root, - encoding: 'utf8', - stdio: ['ignore', 'pipe', 'ignore'], - }) - .trim(); - } catch { - return null; - } -}; - -const seedRelease = (api) => { - // The manifest records the last released version, so a project that turns the - // feature off and on again keeps its history. "0.0.0" tells release-please - // nothing is released yet. - const fresh = !api.exists(RELEASE_MANIFEST); - if (fresh) { - api.editJson( - RELEASE_MANIFEST, - (manifest) => { - manifest['.'] = '0.0.0'; - }, - { create: true, indentFrom: RELEASE_CONFIG } - ); - } - const released = JSON.parse(api.read(RELEASE_MANIFEST))['.']; - api.editJson(RELEASE_CONFIG, (config) => { - // Until the first release, that release is the version init wrote. - if ('0.0.0' === released) { - config.packages['.']['initial-version'] = api.identity.version; - } - // Commits up to this one (the starter's history, when the clone keeps it) - // stay out of the first changelog entry. - const head = fresh ? gitHead(api.root) : null; - if (head) { - config['bootstrap-sha'] = head; - } - }); - // During first setup (no .wp-scaffold.json yet) CHANGELOG.md is still the - // starter's. Drop it: release-please writes a fresh one on the first release. - if (fresh && !api.exists('.wp-scaffold.json')) { - api.remove('CHANGELOG.md'); - } -}; - module.exports = { kind: 'theme', vendor: 'rtcamp', @@ -139,29 +83,6 @@ module.exports = { detect: (api) => true === api.readDefine(tailwindEntry(api), tailwindConst(api)), }, - { - key: 'release', - defaultOn: true, - label: 'Release automation (release-please)', - description: - 'A release pull request kept up to date from Conventional Commit PR titles; merging it bumps style.css and package.json, writes CHANGELOG.md, tags vX.Y.Z and publishes the GitHub release. Default on. Needs squash merges with the PR title as the commit subject, and Actions allowed to create pull requests.', - apply: { - files: [ - { - from: 'release/release.yml', - to: '.github/workflows/release.yml', - }, - { - from: 'release/release-please-config.json', - to: RELEASE_CONFIG, - }, - ], - }, - onEnable: seedRelease, - // Disabling removes the workflow and config (apply.files) and keeps the - // manifest, the record of what was released. - onDisable: () => {}, - }, { key: 'hmr', defaultOn: true, @@ -245,8 +166,9 @@ module.exports = { '.github/prompts', '.github/instructions', 'languages', - // The starter's own release workflow, config and manifest. A project gets - // its own from the "release" feature. + // The starter's own release workflow, config and manifest. Projects don't + // release with them, and the starter-only paths keep a re-init from + // removing a project's own release files. '.github/release-please', '.github/workflows/release-starter.yml', ], diff --git a/docs/initialization.md b/docs/initialization.md index f9325aba..368430a6 100644 --- a/docs/initialization.md +++ b/docs/initialization.md @@ -55,9 +55,9 @@ npm run init -- --name="Acme Blog" --version=1.0.0 --yes --remove-examples | --- | --- | | Identity fields | Name, version, text domain, package, namespace, function prefix, constant prefix, and CSS prefix are derived and reviewed. | | Affected files | `style.css`, `functions.php`, `composer.json`, `package.json`, and text or file basenames containing starter identity tokens are personalized. | -| Version | Written to `style.css` and `package.json`. With the release feature on, it also becomes `initial-version` in `release-please-config.json`, the version of the project's first release. | +| Version | Written to `style.css` and `package.json`. | | Examples | Kept groups remain. Removed groups delete their configured paths and registration regions; markers are removed in either case. See [Included features](features.md). | -| Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations; release automation (on by default) adds `.github/workflows/release.yml`, `release-please-config.json` and `.release-please-manifest.json`, and removes the starter's `CHANGELOG.md`. See [Releases](#releases). | +| Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations. | | State | `.wp-scaffold.json` records identity and feature choices; do not hand-edit it. | | Autoload | Setup regenerates Composer's autoloader. | | Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, along with the starter's own release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-please/`). The other workflows, issue templates, the PR template, `dependabot.yml`, and `.github/release.yml` stay untouched. | @@ -88,31 +88,13 @@ npm run init -- --list npm run init -- --list --json npm run init -- --enable=hmr --yes npm run init -- --disable=hmr --yes -npm run init -- --features=hmr,release --yes +npm run init -- --features=hmr --yes ``` `--features` sets the entire enabled set; `--enable` and `--disable` change one feature without replacing the others. Do not combine these forms. Help and `--list` are read-only. For machine-readable JSON without npm's banner, use `node bin/init.js --list --json`. Example removal belongs to initial setup: `--remove-examples=shortcode,patterns` removes those groups, and `--keep-examples` keeps every group. Do not use `--reinit` to restore examples or remove more groups after their markers have been consumed. Review source and registration together when making a manual change. -### Releases - -The `release` feature is on by default. It sets the project up for [release-please](https://github.com/googleapis/release-please): - -- `.github/workflows/release.yml` keeps one release pull request open on `main`, built from the Conventional Commit pull request titles merged since the last release. Merging it bumps `package.json`, `package-lock.json` and the `style.css` `Version:` line (between the `x-release-please-start-version` and `x-release-please-end` lines), writes the `CHANGELOG.md` section, tags `vX.Y.Z` and publishes the GitHub release. The `PR Title` workflow checks the title format. -- `release-please-config.json` carries `initial-version`, the version init wrote, so the first release is exactly that version. It also carries `bootstrap-sha` when init ran in a git repository, so commits from before init stay out of the first changelog entry. -- `.release-please-manifest.json` records the last released version. It starts at `0.0.0`, which release-please reads as "nothing released yet". Don't edit it, `CHANGELOG.md` or `v*` tags by hand once releases start. -- The starter's `CHANGELOG.md` is removed during setup; release-please writes a fresh one on the first release. - -Before the first release: - -- Allow GitHub Actions to create pull requests (repository or organisation settings, Actions, General, Workflow permissions). Client organisations often switch this off. -- Allow only squash merges, with the pull request title as the commit subject. -- If you deploy on tags: the tag and release are created with `GITHUB_TOKEN`, and GitHub starts no workflow runs for events `GITHUB_TOKEN` causes, so a workflow triggered `on: push: tags` never runs for them. Deploy from `release.yml` in a job with `needs: release-please` and `if: needs.release-please.outputs.release-created == 'true'`, or switch the workflow to a GitHub App token. The same limit means the release pull request gets no CI runs, so don't make checks on it required unless you switch tokens. - -A project that does not release versions (a site deployed from a branch, for example) can turn it off with `npm run init -- --disable=release --yes`; that removes the workflow and config and keeps the manifest. Then release by hand with `npm run release:bump` and `npm run release:changelog`, which need a `CHANGELOG.md` with an `## Unreleased` heading. If an existing project that already tags releases turns the feature on, set `.release-please-manifest.json` to its latest released version before the first run. - - ### Optional dependencies - **Tailwind:** `npm run init -- --enable=tailwind --yes` changes declarations and creates the entry/config files; npm installation is separate. See [Tailwind](tailwind.md) for the theme integration and installation checks. diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index 77769bc6..8e00da96 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -92,7 +92,7 @@ Check the homepage, navigation order, root-guide links, anchors, and mobile layo ## Releasing the theme -Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-starter.yml`), from the starter-only config and manifest in `.github/release-please/`. Cleanup removes all three. Projects get release-please of their own through init's `release` feature: it copies `bin/features/release/release.yml` to `.github/workflows/release.yml` and copies `bin/features/release/release-please-config.json` to the root, then seeds a `0.0.0` manifest, `initial-version` and `bootstrap-sha` and removes the starter's `CHANGELOG.md` (see [initialization.md](../initialization.md#releases)). When you change the starter's workflow or config, make the same change in the `bin/features/release/` copies unless it is starter-only. +Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-starter.yml`), from the config and manifest in `.github/release-please/`. Init cleanup removes the workflow and that folder, so projects made from the starter don't inherit them; projects release by hand with `npm run release:bump` and `npm run release:changelog`. 1. Pull requests are squash-merged, so each PR title becomes one Conventional Commit on `main`. release-please reads those subjects and keeps a release pull request open that bumps the version in `package.json`, `package-lock.json` and `style.css` (between the `x-release-please-start-version` and `x-release-please-end` lines), and writes the next `CHANGELOG.md` section. 2. The title's type decides the version: `fix:` is a patch, `feat:` a minor, and `feat!:` (or a `BREAKING CHANGE:` footer) a major. Anything that changes what init generates, renames a script or a file a project relies on, or raises a minimum version is a `feat!:`. `docs:`, `test:`, `ci:`, `chore:` and `refactor:` cut no release. Dependabot pull requests are prefixed `chore` (see `.github/dependabot.yml`), so they cut no release on their own. Keep it that way: release-please cuts a release for any type with a visible changelog section, `build` included. From 963b963c2b95ed7c3a16ac008f620b63da5052db Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 5 Nov 2026 02:52:41 +0530 Subject: [PATCH 6/7] ci: keep the starter's release config in .github/release-starter/ 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. --- .github/{release-please => release-starter}/config.json | 0 .github/{release-please => release-starter}/manifest.json | 0 .github/workflows/release-starter.yml | 6 +++--- bin/scaffold.config.js | 8 ++++---- docs/initialization.md | 2 +- docs/internal/maintenance.md | 6 +++--- 6 files changed, 11 insertions(+), 11 deletions(-) rename .github/{release-please => release-starter}/config.json (100%) rename .github/{release-please => release-starter}/manifest.json (100%) diff --git a/.github/release-please/config.json b/.github/release-starter/config.json similarity index 100% rename from .github/release-please/config.json rename to .github/release-starter/config.json diff --git a/.github/release-please/manifest.json b/.github/release-starter/manifest.json similarity index 100% rename from .github/release-please/manifest.json rename to .github/release-starter/manifest.json diff --git a/.github/workflows/release-starter.yml b/.github/workflows/release-starter.yml index a5d02a44..977556b5 100644 --- a/.github/workflows/release-starter.yml +++ b/.github/workflows/release-starter.yml @@ -8,7 +8,7 @@ name: Release (starter) # (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. # -# This file releases the starter itself, from the config and manifest in .github/release-please/. +# This file releases the starter itself, from the config and manifest in .github/release-starter/. # Init cleanup removes all of them, so projects made from the starter don't inherit them. on: @@ -38,5 +38,5 @@ jobs: uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 with: token: ${{ github.token }} - config-file: .github/release-please/config.json - manifest-file: .github/release-please/manifest.json + config-file: .github/release-starter/config.json + manifest-file: .github/release-starter/manifest.json diff --git a/bin/scaffold.config.js b/bin/scaffold.config.js index b8047791..467dff24 100644 --- a/bin/scaffold.config.js +++ b/bin/scaffold.config.js @@ -166,10 +166,10 @@ module.exports = { '.github/prompts', '.github/instructions', 'languages', - // The starter's own release workflow, config and manifest. Projects don't - // release with them, and the starter-only paths keep a re-init from - // removing a project's own release files. - '.github/release-please', + // The starter's own release workflow, config and manifest. Cleanup also runs + // on re-init and --clean, so both paths are named for the starter: a + // project's own release-please files never live there. + '.github/release-starter', '.github/workflows/release-starter.yml', ], }, diff --git a/docs/initialization.md b/docs/initialization.md index 368430a6..e3f360e1 100644 --- a/docs/initialization.md +++ b/docs/initialization.md @@ -60,7 +60,7 @@ npm run init -- --name="Acme Blog" --version=1.0.0 --yes --remove-examples | Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations. | | State | `.wp-scaffold.json` records identity and feature choices; do not hand-edit it. | | Autoload | Setup regenerates Composer's autoloader. | -| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, along with the starter's own release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-please/`). The other workflows, issue templates, the PR template, `dependabot.yml`, and `.github/release.yml` stay untouched. | +| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, along with the starter's own release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-starter/`). The other workflows, issue templates, the PR template, `dependabot.yml`, and `.github/release.yml` stay untouched. | | AI instructions | After a successful change, the wrapper runs `sync-ai`; in a standalone project with the framework installed, it refreshes the generated framework PHP instructions. It does not restore the removed prompts or theme-specific rules. | | Retained files | Theme source, `bin/`, Claude skills, documentation, and test infrastructure remain; files belonging to removed example sets do not. | diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index 8e00da96..be4fa3e9 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -18,7 +18,7 @@ If an installation route or feature cannot be exercised, report the missing prer ### Cleanup checks -Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the starter's release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-please/`), while the other workflows, issue templates, and the PR template stay untouched. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. +Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the starter's release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-starter/`), while the other workflows, issue templates, and the PR template stay untouched. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. Check references in retained documentation and AI instructions. Use upstream source links for optional examples or starter-only files that cleanup may remove. Do not silently change the cleanup contract as part of a documentation correction. @@ -92,13 +92,13 @@ Check the homepage, navigation order, root-guide links, anchors, and mobile layo ## Releasing the theme -Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-starter.yml`), from the config and manifest in `.github/release-please/`. Init cleanup removes the workflow and that folder, so projects made from the starter don't inherit them; projects release by hand with `npm run release:bump` and `npm run release:changelog`. +Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-starter.yml`), from the config and manifest in `.github/release-starter/`. Init cleanup removes the workflow and that folder, so projects made from the starter don't inherit them; projects release by hand with `npm run release:bump` and `npm run release:changelog`. 1. Pull requests are squash-merged, so each PR title becomes one Conventional Commit on `main`. release-please reads those subjects and keeps a release pull request open that bumps the version in `package.json`, `package-lock.json` and `style.css` (between the `x-release-please-start-version` and `x-release-please-end` lines), and writes the next `CHANGELOG.md` section. 2. The title's type decides the version: `fix:` is a patch, `feat:` a minor, and `feat!:` (or a `BREAKING CHANGE:` footer) a major. Anything that changes what init generates, renames a script or a file a project relies on, or raises a minimum version is a `feat!:`. `docs:`, `test:`, `ci:`, `chore:` and `refactor:` cut no release. Dependabot pull requests are prefixed `chore` (see `.github/dependabot.yml`), so they cut no release on their own. Keep it that way: release-please cuts a release for any type with a visible changelog section, `build` included. 3. When you want to release, run the [release validation](#release-validation) against the release pull request's branch, reword its entries if a title reads badly, then squash-merge it. release-please tags `vX.Y.Z` and publishes the GitHub release with that section as the notes. -The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no workflow runs on it, and the PR title check is not a required status check for that reason. A GitHub App token in the workflow would give the release pull request its own runs. Never push a `v*` tag or edit `.github/release-please/manifest.json` by hand. +The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no workflow runs on it, and the PR title check is not a required status check for that reason. A GitHub App token in the workflow would give the release pull request its own runs. Never push a `v*` tag or edit `.github/release-starter/manifest.json` by hand. ## Knowledge graph From 7494fff1a3e5529940973c01769eb37d66438adc Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 5 Nov 2026 13:25:46 +0530 Subject: [PATCH 7/7] ci: make Dependabot updates releasable 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. --- .github/dependabot.yml | 6 +++--- docs/internal/maintenance.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 861c3ff5..9ddf86d9 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -8,7 +8,7 @@ updates: timezone: 'Asia/Calcutta' open-pull-requests-limit: 10 commit-message: - prefix: chore + prefix: build include: scope labels: - GHA @@ -22,7 +22,7 @@ updates: timezone: 'Asia/Calcutta' open-pull-requests-limit: 10 commit-message: - prefix: chore + prefix: build include: scope labels: - NPM @@ -45,7 +45,7 @@ updates: timezone: 'Asia/Calcutta' open-pull-requests-limit: 10 commit-message: - prefix: chore + prefix: build include: scope labels: - Composer diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index be4fa3e9..079a16c8 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -95,7 +95,7 @@ Check the homepage, navigation order, root-guide links, anchors, and mobile layo Releases of the theme itself are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-starter.yml`), from the config and manifest in `.github/release-starter/`. Init cleanup removes the workflow and that folder, so projects made from the starter don't inherit them; projects release by hand with `npm run release:bump` and `npm run release:changelog`. 1. Pull requests are squash-merged, so each PR title becomes one Conventional Commit on `main`. release-please reads those subjects and keeps a release pull request open that bumps the version in `package.json`, `package-lock.json` and `style.css` (between the `x-release-please-start-version` and `x-release-please-end` lines), and writes the next `CHANGELOG.md` section. -2. The title's type decides the version: `fix:` is a patch, `feat:` a minor, and `feat!:` (or a `BREAKING CHANGE:` footer) a major. Anything that changes what init generates, renames a script or a file a project relies on, or raises a minimum version is a `feat!:`. `docs:`, `test:`, `ci:`, `chore:` and `refactor:` cut no release. Dependabot pull requests are prefixed `chore` (see `.github/dependabot.yml`), so they cut no release on their own. Keep it that way: release-please cuts a release for any type with a visible changelog section, `build` included. +2. The title's type decides the version: `fix:` is a patch, `feat:` a minor, and `feat!:` (or a `BREAKING CHANGE:` footer) a major. Anything that changes what init generates, renames a script or a file a project relies on, or raises a minimum version is a `feat!:`. `docs:`, `test:`, `ci:`, `chore:` and `refactor:` cut no release. Dependabot pull requests are prefixed `build` (see `.github/dependabot.yml`), which lists them under Changed and makes them releasable: `composer create-project` installs the latest tag, so a dependency fix only reaches new projects once it is released. Each merge only updates the open release pull request, so merge that when you want to release, for example after a batch of security updates. 3. When you want to release, run the [release validation](#release-validation) against the release pull request's branch, reword its entries if a title reads badly, then squash-merge it. release-please tags `vX.Y.Z` and publishes the GitHub release with that section as the notes. The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no workflow runs on it, and the PR title check is not a required status check for that reason. A GitHub App token in the workflow would give the release pull request its own runs. Never push a `v*` tag or edit `.github/release-starter/manifest.json` by hand.