diff --git a/.github/ISSUE_TEMPLATE/task.md b/.github/ISSUE_TEMPLATE/task.md index 92f0582..be825e7 100644 --- a/.github/ISSUE_TEMPLATE/task.md +++ b/.github/ISSUE_TEMPLATE/task.md @@ -103,7 +103,6 @@ $ ... - [ ] ### Housekeeping -- [ ] `CHANGELOG.md` entry under the current version heading - [ ] `examples/.yml` added or updated to match --- @@ -118,19 +117,18 @@ $ ... | | | |---|---| -| **Base your branch on** | `release/` | -| **Branch name** | `/task/` | -| **PR target** | `release/` | -| **PR title** | `[] ` | -| **Commit style** | [Conventional Commits](https://www.conventionalcommits.org/) | +| **Base your branch on** | `main` | +| **Branch name** | `/`, e.g. `fix/runs-on-input` | +| **PR target** | `main` | +| **PR title** | A [Conventional Commit](https://www.conventionalcommits.org/) `(): ` | ```bash git fetch origin -git checkout release/ +git checkout main git pull -git checkout -b /task/ +git checkout -b / # work, commit -git push -u origin /task/ +git push -u origin / ``` PR description starts with `Closes #` so the Project card auto-moves to Done on merge. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d405f28..543b407 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,7 +33,7 @@ $ ... - [ ] Tests pass ### Housekeeping -- [ ] `CHANGELOG.md` entry under the current version heading +- [ ] PR title is a Conventional Commit — release-please writes `CHANGELOG.md` from it - [ ] `examples/.yml` added or updated to match any input change - [ ] `yamllint`, `actionlint` and `bin/check-workflows.sh` pass locally diff --git a/.github/workflows/ci-self-check.yml b/.github/workflows/ci-self-check.yml index 9f6d7d9..7b616da 100644 --- a/.github/workflows/ci-self-check.yml +++ b/.github/workflows/ci-self-check.yml @@ -4,7 +4,6 @@ on: push: branches: - main - - "release/**" pull_request: permissions: diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml new file mode 100644 index 0000000..5ceb5b1 --- /dev/null +++ b/.github/workflows/pr-title.yml @@ -0,0 +1,46 @@ +name: PR Title + +# Squash merges use the PR title as the commit subject, and release-please reads those subjects to +# pick the next version and write CHANGELOG.md. A title that is not a Conventional Commit is +# invisible to it. +on: + pull_request: + branches: + - main + types: + - opened + - edited + - synchronize + - reopened + - ready_for_review + +permissions: + pull-requests: read + +concurrency: + group: pr-title-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + pr-title: + name: Validate PR title + if: github.event.pull_request.draft == false + runs-on: ubuntu-latest + steps: + - name: Validate PR title + uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # No `ci`: nearly everything in this repo is CI, so a change callers see is `fix`/`feat` + # and one that only touches this repo's own files is `chore`. + with: + types: | + feat + fix + perf + revert + docs + chore + refactor + test + build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..aff690e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,66 @@ +name: Release + +on: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +# Serialize runs so two merges in quick succession can't race on the release PR or the alias tags. +concurrency: + group: release-${{ github.repository }} + 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 }} + sha: ${{ steps.release.outputs.sha }} + major: ${{ steps.release.outputs.major }} + minor: ${{ steps.release.outputs.minor }} + steps: + - name: Prepare 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 + + # Consumers pin @vX or @vX.Y (see README "Versioning"). release-please only creates the exact + # vX.Y.Z tag, so move both aliases onto the release commit. + move-alias-tags: + name: Move major and minor alias tags + needs: release-please + if: needs.release-please.outputs.release-created == 'true' + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Point vX and vX.Y at the release commit + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + SHA: ${{ needs.release-please.outputs.sha }} + MAJOR: ${{ needs.release-please.outputs.major }} + MINOR: ${{ needs.release-please.outputs.minor }} + run: | + set -euo pipefail + for tag in "v${MAJOR}" "v${MAJOR}.${MINOR}"; do + if gh api "repos/${REPO}/git/ref/tags/${tag}" >/dev/null 2>&1; then + gh api -X PATCH "repos/${REPO}/git/refs/tags/${tag}" -f sha="$SHA" -F force=true >/dev/null + else + gh api -X POST "repos/${REPO}/git/refs" -f ref="refs/tags/${tag}" -f sha="$SHA" >/dev/null + fi + echo "${tag} -> ${SHA}" + done diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000..37fcefa --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "1.0.0" +} diff --git a/AGENTS.md b/AGENTS.md index cfa6e06..5576e20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,9 @@ Nothing to build, no `package.json`, no `node_modules`. Every file here is YAML - `.github/workflows/cd-*.yml` — opt-in deploy leaves: `github-release`, `wp-org`, `s3`, `built-branch` - `.github/workflows/wp-cd.yml` — optional CD orchestrator; fans out to `github-release`, `wp-org` and `s3` by `deploy-target` - `.github/workflows/version-monitor.yml` — monthly version-bump check that opens a draft PR -- `.github/workflows/ci-self-check.yml` — this repo's own CI; the only workflow not `on: workflow_call` +- `.github/workflows/ci-self-check.yml` — this repo's own CI +- `.github/workflows/release.yml`, `pr-title.yml` — this repo's own release automation. These and `ci-self-check.yml` are the only workflows not `on: workflow_call`, so they have no caller example +- `release-please-config.json`, `.release-please-manifest.json` — release-please config and the current version - `examples/.yml` — exactly one caller example per workflow, matched by filename - `bin/check-workflows.sh` — enforces the examples contract and the conventions below @@ -109,6 +111,7 @@ Use `bash -eo pipefail -c`, never bare `bash -c`: `-e` is not inherited, so a ba - **Everything gated on what changed**: `ci-detect-changes.yml` buckets the diff and every downstream job keys off it, so a docs-only PR runs almost nothing. - **Logic that needs a real language lives elsewhere**: `@rtcamp/wp-tooling`, invoked as `npx wp-tooling `. Repo-local automation is Bash under `bin/`. - **Examples are executable documentation**: one per workflow, verified in CI, comment-free, pinned `@v1`. They target a `wp-content`-shaped monorepo because that is the shape people get wrong. Anything consuming a build artifact shows the producing `ci-build` job and the `needs:` edge in the same file. +- **Releases are cut by release-please**: `release.yml` reads the Conventional Commit subjects merged to `main`, keeps a release PR open that bumps `.release-please-manifest.json` and writes `CHANGELOG.md`, and merging that PR tags `vX.Y.Z` and publishes the GitHub Release. - **Prefer official tooling**: `actions/checkout`, `actions/setup-node`, `shivammathur/setup-php`, and WordPress/Automattic-maintained actions over third-party ones. ## Common pitfalls @@ -119,13 +122,13 @@ Use `bash -eo pipefail -c`, never bare `bash -c`: `-e` is not inherited, so a ba - The self-hosted runners are ARC pods on Ubuntu 24.04 x64 with a minimal image, not GitHub's `ubuntu-latest`. They have `git`, `curl`, `jq`, `zip`, `rsync`, `python3`, `gh` and `docker`, but no Docker Compose v2, `yq`, `pip`, `aws` or `svn`, and no Node or PHP until `setup-node`/`setup-php` run. wp-env needs Compose v2, so jobs that boot wp-env fail on these runners until the image or the workflow provides it. `/usr/local/bin` needs `sudo`, which is passwordless. Install what a step needs, pinned and checksum-verified, as `ci-self-check.yml` does for `actionlint` and `yq` and `cd-s3.yml` does for the AWS CLI. apt's `yq` is kislyuk's jq wrapper, not the mikefarah `yq` this repo uses. - `actionlint` shells out to whatever `shellcheck` is on `PATH`, and rule behaviour differs between shellcheck releases — a local pass does not guarantee a CI pass. Write shell that is clean on older versions too: prefer `guard || continue` and explicit `if` blocks over `A && B || C`, which SC2015 flags on shellcheck 0.10 and earlier. - A green `bin/check-workflows.sh` proves input *names* are right, not input *values*. A wrong `build-command` or `artifact-path` only surfaces in a real consumer run. +- Never hand-edit `CHANGELOG.md` or `.release-please-manifest.json`, and never push a `v*` tag by hand; release-please owns all three. To fix an entry, edit the open release PR. - `cd-github-release.yml` is for consumers, not this repo's own releases. It takes release notes from the `CHANGELOG.md` heading whose version matches the tag — `## v1.2.3 - 2026-10-01`, `## [1.2.3] - 2026-10-01` or release-please's `## [1.2.3](compare-url) (2026-10-01)`, with component tags such as `acme-blocks-v1.2.3` reduced to their version — and deliberately fails rather than publishing empty notes, so a hand-cut release renames `## Unreleased` to its version before tagging. When a release for the tag already exists, as release-please creates one, it only attaches the asset and leaves the notes alone. - Consumers pin `@v1`, never a branch such as `@release/v1.0.0`. A moving ref has already broken real consumer runs mid-change. ## PR instructions -- Task branches `/task/` off `main`. Never commit to `main` directly. -- [Conventional Commits](https://www.conventionalcommits.org/): `feat(ci): add lint-css workflow`. -- PR title `[] `, targeting `main`. Squash merge. -- Ensure the Code quality commands pass, the caller example is updated alongside the workflow, and a `CHANGELOG.md` entry is added — see `CONTRIBUTING.md` for the full checklist. +- GitHub flow: branch off `main`, PR back into `main`. A release is a tag on `main` that release-please cuts. Name branches `/` (`fix/runs-on-input`). Never commit to `main` directly. +- [Conventional Commits](https://www.conventionalcommits.org/) for the PR title, typed by what changes for callers: `fix:` or `feat:` for any change to a reusable workflow, and `feat!:` for anything a caller has to change for (a removed, renamed or newly required input, a new `permissions:` entry, a renamed job `name:`). `docs:` and `chore:` (e.g. `chore(self-check): ...`) are only for this repo's own files and don't cut a release. `ci:` isn't accepted here: nearly everything in this repo is CI, so the title check makes the choice explicit. Example: `feat(lint-css): Add lint-css workflow`. +- Ensure the Code quality commands pass, the caller example is updated alongside the workflow, and the PR title says what changed for a consumer — see `CONTRIBUTING.md` for the full checklist. - Ask first before removing or renaming an input, adding a deploy target, or granting a job `contents: write` it does not already need. diff --git a/CHANGELOG.md b/CHANGELOG.md index d967234..da48406 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,17 +2,7 @@ All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - -## Unreleased - -### Added - -- `ci-lint-js.yml` and `ci-lint-css.yml` take a `lint-files-command` (`wp-ci.yml`: `lint-js-files-command`, `lint-css-files-command`) that lints only the files passed to it, such as `npm run lint:js:files`. When it is set and every changed path is an existing JS file or stylesheet, only those files are linted. Left empty, the default, every run lints the whole project with `lint-command`. - -### Changed - -- `ci-lint-js.yml` and `ci-lint-css.yml` no longer pass deleted files to the linter, which failed any change that removed a JS or SCSS file. A removed file, `package.json`, `package-lock.json` or a lint config now lints the whole project with `lint-command`, since any of them can break files the change did not touch: ESLint, Prettier and Babel configs for `ci-lint-js.yml`, and Stylelint configs and `.stylelintignore` for `ci-lint-css.yml`. A `::notice::` names the file that triggered it. `lint-command` is the whole-project command again and no longer receives file arguments. +Entries are generated by [release-please](https://github.com/googleapis/release-please) from Conventional Commit subjects. Don't edit this file by hand. ## v1.0.0 - 2026-10-01 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9b4212..8cbf013 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,14 +48,14 @@ caller at your branch. ## Pull request checklist -- [ ] Branch is `/task/`, based on `main`. +- [ ] Branch is based on `main` and named `/`, e.g. `fix/runs-on-input`. - [ ] The three commands above pass locally. - [ ] Every new or changed input has a `description:`. - [ ] `examples/.yml` added or updated to match. -- [ ] `CHANGELOG.md` entry added under the current version heading. +- [ ] PR title is a [Conventional Commit](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:` for a breaking change) with the changelog entry. - [ ] Breaking changes to an input surface are called out in the PR description. - [ ] Smoke-tested against a consumer repo, or explicitly noted why not. -- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/). +- [ ] PRs are squash-merged to `main`. ## License diff --git a/README.md b/README.md index 8ee5af3..bfaf9e0 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,8 @@ Pin a version tag. `@v1` and `@v1.2` are aliases that move forward to compatible | `@v1.2` | Latest patch of the `v1.2` line | | `@v1.2.3` | One exact release | +Releases are cut by [release-please](https://github.com/googleapis/release-please) from the Conventional Commits merged to `main`. + Within a major version, inputs are only ever added, and always with a default. Removing or renaming an input, or making one required, ships as a new major. diff --git a/bin/check-workflows.sh b/bin/check-workflows.sh index c523ebc..3f951cb 100755 --- a/bin/check-workflows.sh +++ b/bin/check-workflows.sh @@ -19,7 +19,6 @@ cd "$ROOT" WORKFLOW_DIR=".github/workflows" EXAMPLE_DIR="examples" -SELF_CHECK="ci-self-check.yml" EXPECTED_REF="v1" USES_PREFIX="rtCamp/wp-shared-workflows/.github/workflows" # Reusable workflows run in the caller's repo, so the caller picks the runner. @@ -44,19 +43,24 @@ done as_json() { yq -o=json '.' "$1"; } +is_reusable() { as_json "$1" | jq -e '.["on"] | type == "object" and has("workflow_call")' >/dev/null; } + # --- 1. one example per workflow, one workflow per example ------------------- for wf in "$WORKFLOW_DIR"/*.yml; do base="$(basename "$wf")" - [ "$base" = "$SELF_CHECK" ] && continue + is_reusable "$wf" || continue [ -f "$EXAMPLE_DIR/$base" ] || err "$wf has no caller example — create $EXAMPLE_DIR/$base" done for ex in "$EXAMPLE_DIR"/*.yml; do base="$(basename "$ex")" - [ -f "$WORKFLOW_DIR/$base" ] || + if [ ! -f "$WORKFLOW_DIR/$base" ]; then err "$ex has no matching workflow at $WORKFLOW_DIR/$base — rename or remove it" + elif ! is_reusable "$WORKFLOW_DIR/$base"; then + err "$ex matches $WORKFLOW_DIR/$base, which is repo-local (no on: workflow_call) — remove the example" + fi done # --- 2 + 3. every example call matches the workflow it calls ----------------- diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 0000000..0939f77 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,54 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "packages": { + ".": { + "release-type": "simple", + "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": "docs", + "section": "Documentation", + "hidden": true + }, + { + "type": "chore", + "section": "Miscellaneous", + "hidden": true + }, + { + "type": "refactor", + "section": "Refactoring", + "hidden": true + }, + { + "type": "test", + "section": "Tests", + "hidden": true + }, + { + "type": "build", + "section": "Build", + "hidden": true + } + ] + } + } +}