Skip to content
WP Wireframe

Contributing

Working on the package

Section titled “Working on the package”
Terminal window
git clone https://github.com/tdrayson/wp-wireframe.git
cd wp-wireframe
composer install
npm install
npm run start    # watch mode
npm run build    # production build → src/assets/

The compiled bundle in src/assets/ is committed, so consumers never need a JS build.

To release, bump the version in bootstrap.php (the Versions::register() call) and tag v{version}. The release workflow fails if the two differ.

Working on the docs

Section titled “Working on the docs”

The docs are an Astro Starlight site in docs/.

Terminal window
cd docs
npm install
npm run dev      # serves at http://localhost:4321/wp-wireframe/docs/
npm run build    # builds to docs/dist and fails on broken internal links

changelog.md is generated from the root CHANGELOG.md on every dev/build run — edit the root file, not the generated page. Internal links must include the base path, e.g. /wp-wireframe/docs/features/action-field/.

Pushes to main that touch docs/ or CHANGELOG.md publish the site via .github/workflows/docs.yml.

Playground previews

Section titled “Playground previews”

Every pull request, including ones from forks, gets a sticky comment with a WordPress Playground link that boots a site with every plugin in examples/ installed against the PR’s code, plus Options View for inspecting saved values. Published releases get the same link appended to their release notes, and the newest release is always at latest/blueprint.json.

Two workflows split the work so fork PRs never run with a write token:

  • playground.yml builds a zip per example from the PR’s code with a read-only token and uploads them as an artifact.
  • playground-publish.yml runs from main on workflow_run, validates the artifact, publishes it to gh-pages under pr/<number>/, and posts the comment. Changes to it only take effect once merged.
  • playground-cleanup.yml deletes pr/<number>/ when the PR is closed or merged. It only checks out gh-pages, so it is safe on pull_request_target.

GitHub Pages serves the gh-pages branch: PR previews live under pr/<number>/ (overwritten on each push), releases under <tag>/ (kept), the newest release’s blueprint under latest/, and these docs under docs/. Every workflow that writes to gh-pages shares the gh-pages-publish concurrency group so their pushes never race.

To publish the preview for an existing release tag, run gh workflow run playground.yml -f tag=v1.2.3.

One-time repository setup is documented at the top of .github/workflows/playground.yml.