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

Filter by extension

Filter by extension


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

### Housekeeping
- [ ] `CHANGELOG.md` entry under the current version heading
- [ ] `examples/<workflow>.yml` added or updated to match

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

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

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

PR description starts with `Closes #<this-issue>` so the Project card auto-moves to Done on merge.
Expand Down
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ $ ...
- [ ] Tests pass

### Housekeeping
- [ ] `CHANGELOG.md` entry under the current version heading
- [ ] PR title is a Conventional Commit — release-please writes `CHANGELOG.md` from it
- [ ] `examples/<workflow>.yml` added or updated to match any input change
- [ ] `yamllint`, `actionlint` and `bin/check-workflows.sh` pass locally

Expand Down
1 change: 0 additions & 1 deletion .github/workflows/ci-self-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ on:
push:
branches:
- main
- "release/**"
pull_request:

permissions:
Expand Down
46 changes: 46 additions & 0 deletions .github/workflows/pr-title.yml
Original file line number Diff line number Diff line change
@@ -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
66 changes: 66 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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 }}
Comment on lines +54 to +56
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
3 changes: 3 additions & 0 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
".": "1.0.0"
}
13 changes: 8 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>.yml` — exactly one caller example per workflow, matched by filename
- `bin/check-workflows.sh` — enforces the examples contract and the conventions below

Expand Down Expand Up @@ -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 <command>`. 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
Expand All @@ -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 `<version>/task/<kebab-slug>` off `main`. Never commit to `main` directly.
- [Conventional Commits](https://www.conventionalcommits.org/): `feat(ci): add lint-css workflow`.
- PR title `[<version>] <subject>`, 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 `<type>/<kebab-slug>` (`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.
12 changes: 1 addition & 11 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,14 +48,14 @@ caller at your branch.

## Pull request checklist

- [ ] Branch is `<version>/task/<kebab-slug>`, based on `main`.
- [ ] Branch is based on `main` and named `<type>/<kebab-slug>`, e.g. `fix/runs-on-input`.
- [ ] The three commands above pass locally.
- [ ] Every new or changed input has a `description:`.
- [ ] `examples/<workflow>.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

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

Expand Down
10 changes: 7 additions & 3 deletions bin/check-workflows.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 -----------------
Expand Down
54 changes: 54 additions & 0 deletions release-please-config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
{
"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
"packages": {
".": {
"release-type": "simple",
Comment thread
aryanjasala marked this conversation as resolved.
Resolved
"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
}
]
}
}
}
Loading