diff --git a/specs/2026-08-11-release-workflow-design.md b/specs/2026-08-11-release-workflow-design.md new file mode 100644 index 0000000..0ced0f1 --- /dev/null +++ b/specs/2026-08-11-release-workflow-design.md @@ -0,0 +1,166 @@ +# Release Workflow Design + +- **Date:** 2026-08-11 +- **Plugin:** Projects Portfolio (`projects-wp`) +- **Status:** Approved design, awaiting implementation plan + +## 1. Goals + +- A single tag push (`v*`) automatically produces a release-ready zip named `projects-portfolio-v.zip`. +- The zip contains exactly the files WordPress needs to install and use the plugin: `projects-portfolio.php` at the root of `projects-portfolio/`, with `admin/`, `assets/`, `includes/`, `languages/`, `templates/` subdirectories plus `README.md` and `LICENSE`. +- The same zip is uploaded as a workflow artifact AND attached to a GitHub release matching the tag. +- README gets a short "Building a release" section explaining how the workflow runs and what it produces. + +## 2. Non-goals + +- Publishing to WordPress.org — out of scope (different credentials, different approval workflow). +- Cross-repo publishing or PAT-based auth. +- Signing, cosign, or checksums for the zip. +- Auto-bumping `PROJECTS_PORTFOLIO_VERSION` or the plugin header before a tag is cut. The workflow assumes the tag is created *after* the version has been bumped in-tree. +- Backporting tags. The workflow only acts on the tag push, not on retags of older SHAs. + +## 3. Architecture + +A single GitHub Actions workflow file at `.github/workflows/release.yml` runs on every `v*` tag push. It performs four sequential steps inside a single job: + +1. **Checkout** — `actions/checkout@v4` at the tag's commit. +2. **Build zip** — bash script copies allowlisted runtime files into a staging directory `dist/staging/projects-portfolio/`, then runs `zip -r` from the staging root to produce `dist/projects-portfolio-v.zip`. +3. **Upload artifact** — `actions/upload-artifact@v4` with name `projects-portfolio-v` and path `dist/projects-portfolio-*.zip`. Fails if no file matches. +4. **Create release** — `softprops/action-gh-release@v2` with the tag, generated release notes, and the zip file. Replaces the asset if a release with the same tag already exists (default `action-gh-release@v2` behavior). + +The workflow uses the runner-provided `GITHUB_TOKEN` with `contents: write` permission. No additional secrets are needed. + +### 3.1 Why a staging directory + +WordPress's "Upload Plugin" zip-install expects `/.php` at the zip root. A direct `zip -r` of the working tree would put everything at the zip root — no enclosing folder — which would fail to install. The staging directory ensures the zip's internal layout has `projects-portfolio/` at the top with `projects-portfolio.php` inside it. + +### 3.2 Files added + +- `.github/workflows/release.yml` — the workflow. +- `README.md` — modified, with a new "Building a release" section after the existing "Connect Your Gitea Repo" section. + +No PHP files are touched. The PHPUnit suite is unaffected (no test bootstrap or production code changes). + +## 4. Trigger & permissions + +```yaml +on: + push: + tags: + - 'v*' + +permissions: + contents: write +``` + +`workflow_dispatch` is intentionally omitted. To re-run for an existing tag, use the GitHub UI's "Re-run all jobs" button. + +## 5. Zip filename + +`projects-portfolio-v.zip`, where `` is the tag name with the leading `v` stripped. Examples: + +- Tag `v1.1.0` → `projects-portfolio-v1.1.0.zip` +- Tag `v2.0.0-rc1` → `projects-portfolio-v2.0.0-rc1.zip` + +## 6. Allowlisted zip contents + +The build step copies these paths from the working tree into `dist/staging/projects-portfolio/`: + +``` +projects-portfolio.php +README.md +LICENSE +admin/ +assets/ +includes/ +languages/ +templates/ +``` + +The bundled `includes/plugin-update-checker/` library IS included — it's a runtime dependency used by `projects-portfolio.php`. + +## 7. Excluded paths + +The build step does **not** copy any of these. Most are already not tracked in git; the explicit list prevents accidental inclusion if any are added later: + +- `composer.json`, `composer.lock` — dev-only. +- `vendor/` — Composer dev dependencies. +- `tests/`, `phpunit.xml`, `phpunit.xml.dist`, `.phpunit.result.cache` — test infrastructure. +- `plans/`, `specs/` — design artifacts (not tracked, but listed for safety). +- `.github/` — the workflow file itself (would otherwise be included by the catch-all `cp -r`). +- `.gitignore`, `.vscode/`, `.claude/` — editor / project config (not tracked except `.gitignore`). + +If the build script can't find a tracked source path it expects (e.g. `projects-portfolio.php` renamed), `set -e` fails the step. + +## 8. Build step (verbatim) + +```bash +set -euo pipefail +VERSION="${GITHUB_REF_NAME#v}" +STAGE="dist/staging" +OUT="dist/projects-portfolio-v${VERSION}.zip" + +rm -rf dist +mkdir -p "$STAGE/projects-portfolio" + +cp projects-portfolio.php "$STAGE/projects-portfolio/" +cp README.md "$STAGE/projects-portfolio/" +cp LICENSE "$STAGE/projects-portfolio/" +cp -r admin/ "$STAGE/projects-portfolio/" +cp -r assets/ "$STAGE/projects-portfolio/" +cp -r includes/ "$STAGE/projects-portfolio/" +cp -r languages/ "$STAGE/projects-portfolio/" +cp -r templates/ "$STAGE/projects-portfolio/" + +( cd "$STAGE" && zip -r "../../$OUT" projects-portfolio ) + +echo "Built $OUT" +unzip -l "$OUT" +``` + +`unzip -l` prints the table of contents to the action log so the run is self-documenting. + +## 9. README addition + +Add a "Building a Release" section after the existing "Connect Your Gitea Repo" section: + +```markdown +## Building a Release + +Releases are automated via GitHub Actions. To cut a new release: + +1. Bump `PROJECTS_PORTFOLIO_VERSION` and the plugin header `Version:` in `projects-portfolio.php`. +2. Commit and push to `main`. +3. Tag the release commit: `git tag -a v1.1.0 -m "v1.1.0 — short summary"`. +4. Push the tag: `git push origin v1.1.0`. + +The `.github/workflows/release.yml` workflow runs and: + +- Builds `projects-portfolio-v.zip` containing only the runtime files (`projects-portfolio.php`, `admin/`, `assets/`, `includes/`, `languages/`, `templates/`, `README.md`, `LICENSE`). +- Uploads the zip as a workflow artifact. +- Creates (or updates) the matching GitHub Release with the zip attached. + +Dev-only paths (`composer.json`, `composer.lock`, `vendor/`, `tests/`, `plans/`, `specs/`, `.github/`, `.gitignore`, `.vscode/`, `.claude/`) are intentionally excluded. +``` + +## 10. Error handling + +| Failure | Behavior | +|---|---| +| Tag doesn't match `v*` | Workflow doesn't run. | +| `cp -r` finds a missing source path | `set -e` fails the step; no zip, no release. | +| `zip` command fails | `set -e` fails the step; no artifact upload, no release. | +| Artifact upload finds no file | `if-no-files-found: error` fails the step. | +| Release already exists for tag | `softprops/action-gh-release@v2` replaces the asset and updates notes (default behavior). | +| Missing `contents: write` permission | Job fails at checkout or release step with a clear permissions error. | + +## 11. Rollout + +1. Implement on a feature branch. +2. Merge into `main` (the workflow file is tracked and applies to all future tags). +3. To produce the first automated release: bump `PROJECTS_PORTFOLIO_VERSION` and the plugin header from `1.1.0` to `1.1.1`, commit, tag `v1.1.1`, push the tag. +4. Verify on the GitHub Actions run page that: artifact uploads, zip contents look right (via the `unzip -l` log line), GitHub release is created with the zip attached. + +## 12. New translatable strings + +None. The workflow file and README change introduce no user-facing strings. \ No newline at end of file