Skip to content

Contributing and Releases

Jump to bottom
Jon Imms edited this page Jun 25, 2026 · 1 revision

Contributing & Releases

How to set up the StrataWP monorepo locally, make changes, and ship releases with Changesets.

StrataWP is a Turborepo + pnpm workspaces monorepo. Whether you're fixing a bug in a single package or adding a new one, the loop is the same: install once at the root, work inside the affected package, and run tests and lint before opening a pull request. This page walks through each step.

Note The canonical contributor guide lives at CONTRIBUTING.md. This page expands on it with full commands and the release workflow. If the two ever disagree, the in-repo file wins.

Prerequisites

Before you clone, make sure your machine has:

Tool Version Notes
Node.js 18+ Root engines field requires node >=18.18.
pnpm 8+ Root engines requires pnpm >=8.0.0; the repo is pinned to pnpm@8.12.1 via packageManager.
PHP 8.1+ Needed for the PHP framework (Composer package stratawp/core) and the example themes.
Composer v2 Installs the PHP dependencies (stratawp/core) for the example themes.

Tip Install pnpm with Corepack so the pinned version is used automatically:

corepack enable
corepack prepare pnpm@8.12.1 --activate

1. Set up the repo

  1. Clone the repository and move into it:

    git clone https://github.com/JonImmsWordpressDev/strataWP.git
cd strataWP

  2. Install all workspace dependencies from the root. pnpm links the workspace packages together automatically:

    pnpm install

    Expected: pnpm resolves the lockfile and installs dependencies for every workspace package under packages/* and examples/*.

    Warning Always run pnpm install from the repository root, not inside an individual package. Installing inside a sub-package breaks the workspace symlinks Turborepo relies on.

  3. Start the monorepo in development mode:

    pnpm dev

    This runs turbo dev across packages that define a dev task (persistent, non-cached). Leave it running while you work.

2. Common root scripts

All scripts run from the repository root. Turborepo fans them out to the relevant packages and caches results where it can.

Command What it does
pnpm dev Start all package dev servers (turbo dev).
pnpm build Production build of every package (turbo build).
pnpm test Run unit tests across packages (turbo test).
pnpm typecheck TypeScript validation across packages (turbo typecheck).
pnpm lint Lint all TypeScript/JavaScript with ESLint (eslint .).
pnpm lint:fix Lint and auto-fix where possible (eslint . --fix).
pnpm lint:php Lint PHP via scripts/lint-php.mjs.
pnpm format Format .ts, .tsx, .md, and .json files with Prettier.
pnpm format:check Check formatting without writing changes.
pnpm test:e2e Run the Playwright accessibility E2E suite inside examples/basic-theme (playwright.a11y.config.ts).
pnpm test:perf Run Lighthouse CI (lhci autorun).
pnpm clean Run turbo clean and remove node_modules.

Tip To work on a single package, scope the command with a pnpm filter, for example:

pnpm --filter @stratawp/cli test

3. Contribution workflow

Follow these steps for each change. They mirror the Development Workflow section of CONTRIBUTING.md.

  1. Create a branch off your work:

    git checkout -b feature/your-feature-name

  2. Make your changes.

  3. Run the tests:

    pnpm test

  4. Lint your code:

    pnpm lint

  5. Commit using Conventional Commits (see below).

  6. Push your branch and open a pull request.

Conventional Commits

Commit messages use the Conventional Commits format so history stays parseable:

Prefix Use for
feat: New features
fix: Bug fixes
docs: Documentation changes
chore: Maintenance tasks
refactor: Code refactoring
test: Test additions or changes

Examples:

git commit -m "feat(cli): add block generator command"
git commit -m "fix(vite-plugin): resolve HMR issue with PHP files"
git commit -m "docs: update README with new examples"

Code style

  • TypeScript — formatted with Prettier (config included). Run pnpm format.
  • PHP — follow the WordPress Coding Standards.
  • Commit messages — Conventional Commits format.

Pull request checklist

Before requesting review, confirm:

  1. Documentation is updated if your change needs it.
  2. New features have tests.
  3. All tests pass (pnpm test).
  4. CHANGELOG.md is updated if applicable — for versioned package changes, add a changeset instead (see below).
  5. A maintainer is requested for review.

Tip Use issues for bugs and feature requests, and discussions for open-ended questions or ideas.

4. Releases with Changesets

StrataWP uses Changesets to version and publish its npm packages. The flow is: contributors add a changeset describing their change, then a maintainer versions and publishes.

Step 1 — Add a changeset (contributors)

When your change affects a published package, record it:

pnpm changeset

This launches an interactive prompt to pick the affected packages, choose a semver bump (patch / minor / major), and write a short summary. It writes a markdown file under .changeset/ — commit that file with your PR.

Note Not every PR needs a changeset. Docs-only edits, internal tooling, and test-only changes that don't affect any published package can skip it.

Step 2 — Version packages (maintainers)

When it's time to cut a release, apply all pending changesets to bump versions and update changelogs:

pnpm version-packages

This runs changeset version, which consumes the files in .changeset/, updates each package's version, and regenerates per-package changelog entries. Review and commit the result.

Step 3 — Publish (maintainers only)

pnpm release

This runs turbo build && changeset publish — it builds every package first, then publishes the newly versioned packages to npm.

Warning pnpm release publishes to the public npm registry. Only maintainers with publish rights should run it, and only after pnpm version-packages has been committed.

Release workflow reference

Command Underlying script Who runs it
pnpm changeset changeset Contributors
pnpm version-packages changeset version Maintainers
pnpm release turbo build && changeset publish Maintainers

5. Theme release (GitHub Actions)

Publishing packages to npm is separate from shipping a distributable example theme. The Build and Release Theme workflow (.github/workflows/release-theme.yml) automatically packages the Basic theme into an installable zip whenever a GitHub Release is published.

When a release is published, the workflow:

  1. Checks out the code and sets up Node.js 20 and pnpm 9.
  2. Installs dependencies with pnpm install --frozen-lockfile.
  3. Builds all packages with pnpm build.
  4. Sets up PHP 8.1 with Composer v2, then runs composer install --no-dev --optimize-autoloader in examples/basic-theme.
  5. Stamps the release tag (with the leading v stripped) into the theme's style.css Version: header.
  6. Stages the production files (dist, vendor, templates, parts, patterns, inc, languages, root PHP files, style.css, theme.json, screenshot.png) and zips them into strata-basic.zip. (Each copy is best-effort, so optional paths that don't exist — such as languages — are skipped without failing the build.)
  7. Attaches strata-basic.zip to the GitHub Release.

Note To trigger this workflow, publish a release from a tag such as v2.0.0. The tag name drives the version written into style.css.

Warning The pinned tool versions differ between local development and this CI workflow — local development targets Node 18+ and pnpm 8.12.1, while the theme-release workflow runs on Node 20 and pnpm 9. Stick with the local versions in the prerequisites table for day-to-day work; the workflow is self-contained.

6. Changelog and roadmap

  • Changelog — every notable change is recorded in CHANGELOG.md, organized by version. The current release is v2.0.0 ("Focus"), which sharpened the framework's scope by removing three packages from the monorepo. When in doubt about whether a change is user-facing, add a changeset (see above) and let the release process fold it into the changelog.
  • Roadmap — planned direction and the rationale behind what is (and isn't) being built lives in ROADMAP.md. It captures the v2.0 scope, the packages under review for v2.1 (@stratawp/explorer and @stratawp/headless), and the ranked investment list for upcoming work. Read it before proposing a large feature so your work aligns with where the project is heading.

Tip The roadmap is explicit about what StrataWP will not build (admin UIs, an embedded AI SDK, a component registry). Checking it first can save you from building something that's intentionally out of scope.

License

By contributing, you agree that your contributions are licensed under GPL-3.0-or-later — the same license as StrataWP itself, and as WordPress.

Related pages

StrataWP v2.0.0 · GPL-3.0-or-later · Built by Jon Imms Repository · README

Home

Start here

Building themes

Shipping

Extending & contributing

Help

Clone this wiki locally