Skip to content

contributor-workflows.md

Latest commit

 

History

History
196 lines (138 loc) · 11.4 KB

contributor-workflows.md

File metadata and controls

196 lines (138 loc) · 11.4 KB
Raw

Contributor Workflows

This page describes the day-to-day workflows for maintainers changing Build with WordPress. Use it with the Architecture and Generated outputs references when preparing a pull request.

Prerequisites

  • Node.js compatible with the repository's scripts. The telemetry bundle targets Node 18.
  • pnpm 10.8.1, as declared by package.json.
  • WordPress Studio installed when manually testing generated packages that launch studio mcp or use the Studio CLI.
  • Git access to Automattic/wordpress-cursor-plugin only when running the Cursor export workflow.

Install dependencies:

pnpm install

CI-parity install:

pnpm install --frozen-lockfile

Core commands

Command Source Purpose
pnpm build package.json Bundles telemetry MCP and regenerates all plugin packages.
pnpm build:telemetry-mcp package.json Rebuilds only dist/wordpress-telemetry-mcp.mjs.
pnpm verify package.json Runs generated-output verification across plugin packages.
pnpm export:cursor package.json Exports plugins/cursor/ to the standalone Cursor plugin repository branch.

Standard change workflow

  1. Identify the source boundary for the change:
    • portable WordPress behavior: skills/;
    • generated package layout or manifest logic: scripts/build-plugins.mjs;
    • generated-output test contract: scripts/verify-plugins.mjs;
    • telemetry MCP behavior: scripts/wordpress-telemetry-mcp.mjs and possibly scripts/build-telemetry-mcp.mjs.
  2. Make the source change.
  3. Run pnpm build.
  4. Run pnpm verify.
  5. Inspect generated package diffs under plugins/.
  6. Update documentation when the architecture, public generated files, setup workflow, or integration contract changes.

Avoid editing generated packages as the only source of a change. If a file under plugins/ should change, update the generator or skill source that writes it.

Change recipes

Update WordPress workflow guidance

  1. Edit the relevant skill in skills/.

  2. If the skill appears in a new location or requires new metadata, update scripts/build-plugins.mjs.

  3. Run:

    pnpm build
pnpm verify

  4. Spot-check representative generated skill copies in plugin outputs.

Update MCP server configuration

  1. Update the MCP generation logic in scripts/build-plugins.mjs.
  2. Update scripts/verify-plugins.mjs so it fails on the old or invalid config shape.
  3. Run pnpm build && pnpm verify.
  4. Manually smoke test at least one MCP-enabled generated surface if the command, args, or server names changed.

Expected MCP server names are:

  • wordpress-studio
  • wordpress-telemetry

Update telemetry behavior

  1. Edit scripts/wordpress-telemetry-mcp.mjs.

  2. Keep the tool name record_workflow_event stable unless you also update every generated instruction and verification contract that refers to it.

  3. Run:

    pnpm build:telemetry-mcp
pnpm build
pnpm verify

  4. Confirm telemetry remains non-blocking and respects WP_SITE_CREATOR_NO_TELEMETRY=1.

Add a generated agent surface

  1. Add generator support in scripts/build-plugins.mjs.
  2. Add a generated output directory under plugins/<surface>/ through the build.
  3. Include skills when the surface supports them.
  4. Include wordpress-studio and wordpress-telemetry MCP setup when the surface supports MCP.
  5. Add a verifier function in scripts/verify-plugins.mjs for the files users or marketplaces consume.
  6. Add the surface to the package matrix in README.md and Generated outputs.
  7. Run pnpm build && pnpm verify.

Export Cursor output

Cursor output has an additional publishing workflow because Cursor consumes a standalone plugin repository.

Reviewable dry run:

pnpm build
pnpm verify
pnpm export:cursor -- --dry-run

The dry run prints the subtree split, push target, and cleanup command without creating a local split branch, pushing to the standalone repository, or touching a standalone checkout.

Maintainer export:

pnpm export:cursor

The export script pushes a subtree split of plugins/cursor to Automattic/wordpress-cursor-plugin on sync/from-build-with-wordpress. Open or update a pull request from that branch to the standalone repository's main branch.

Before submitting or updating the Cursor listing:

  1. Confirm the standalone branch contains .cursor-plugin/plugin.json, README.md, mcp.json, rules/wordpress-studio.mdc, and the generated skills/ tree.
  2. Review .cursor-plugin/plugin.json for the listing-facing name, displayName, version, description, author, homepage, repository, license, keywords, rules, skills, and mcpServers fields.
  3. Confirm the standalone README describes the generated package, export source of truth, and MCP setup.
  4. Submit to Cursor only after the standalone repository PR is accepted.

Manual smoke testing

After verification passes, manually test representative generated output when the change affects runtime behavior:

  1. Open or copy a generated plugins/<surface>/ package into the corresponding agent's expected project root.
  2. Confirm the agent sees the WordPress instructions and skills.
  3. For MCP-enabled surfaces, confirm wordpress-studio and wordpress-telemetry are available.
  4. Try representative tasks:
    • create a new site;
    • build or edit a theme;
    • create a custom block;
    • create a custom plugin;
    • run a performance, accessibility, or frontend audit.
  5. If Studio MCP is unavailable, confirm the generated Studio guidance routes the agent to the Studio CLI fallback path.

CI and automation

The repository includes GitHub Actions workflows for documentation maintenance and skills maintenance under .github/workflows/:

  • developer-docs-agent.yml runs the technical documentation agent lane for bootstrap and maintenance documentation updates.
  • skills-agent.yml runs the skills maintenance lane.

Manual documentation runs default to maintenance and should make the smallest source-grounded documentation update needed for newly merged code or finish with no changes when docs are current. Select bootstrap only to intentionally create or improve the initial documentation structure.

Developer docs workflow contract

developer-docs-agent.yml calls the reusable Automattic/docs-agent/.github/workflows/maintain-docs.yml workflow for the technical documentation lane. The caller grants its github.token the publication permissions declared by the workflow and explicitly forwards OPENAI_API_KEY for live runs and the required EXTERNAL_PACKAGE_SOURCE_POLICY package allowlist.

  • workflow_dispatch offers run_kind choices of maintenance (the default) and bootstrap; pushes to trunk run with run_kind: maintenance.
  • docs_branch is docs-agent/build-with-wordpress-developer-docs-v2 and base_ref is trunk.
  • writable documentation paths are limited to README.md, docs/**, and plugins/**/README.md.
  • Docs Agent selects its native package from the reusable workflow revision pinned in this file: Automattic/docs-agent/.github/workflows/maintain-docs.yml@7b67d341eea16b75b8e055507d36a8d8e69a1fe3.
  • maintenance is bounded to the known Figma Studio handoff diagnostics source delta from PR #100; that delta is marked as not requiring a documentation change, so the technical lane may finish with no changes after confirming the Figma handoff documentation still matches source behavior. Bootstrap requires README.md, docs/README.md, at least three topic pages, and a README link to the docs index.
  • manual workflow_dispatch runs set require_pr: true; push-triggered maintenance runs do not require a PR and may finish with no changes when the documentation already matches source behavior.
  • verification commands are pnpm install --frozen-lockfile, pnpm build, and pnpm verify.
  • the developer-docs drift check is scoped to non-documentation paths: git diff --exit-code -- . ':(top,exclude)README.md' ':(top,glob,exclude)docs/**' ':(top,glob,exclude)plugins/**/README.md'. This means the build must not produce uncommitted generated-package or source changes outside the workflow's writable documentation paths.

When changing the docs workflow, keep this contract aligned with the repository documentation structure in the docs index. When changing generated-output behavior, update the generator, verifier, documentation, and generated files in the same pull request so maintenance runs can finish cleanly.

Skills workflow contract

skills-agent.yml uses the same pinned reusable Docs Agent workflow with audience: skills. It is triggered manually and on a weekly Monday schedule, writes only to skills/**, generated skill copies under plugins/**/skills/**, and plugin README files, and runs the same install, build, and verify commands as the developer-docs workflow. Its bounded source delta covers the live skill sources, package generator scripts, and packaged skill outputs, and permits an evidence-backed no-change result when those surfaces are current. Its drift check is intentionally broad: git diff --exit-code, so generated skill package output must be committed after the build. The workflow does not pass run_kind or require_pr; the native skills lane should make the smallest source-grounded skill update needed or finish with no changes when skills are current. Keep this workflow focused on live skill content; generated package structure and developer documentation belong in the technical docs workflow and the generator/verifier source.

The CI workflow provides automated validation for pull requests and pushes to trunk and feat/native-docs-agent. It checks out Docs Agent at 7b67d341eea16b75b8e055507d36a8d8e69a1fe3 and the accepted WP Codebox reusable-workflow and helper revision at a6fe2d208e990a8d04104aa74aacbb8d1539fbc1, installs pnpm 10.8.1, runs pnpm test, then runs pnpm build and pnpm verify. The workflow contract test rejects producer revision, reusable workflow, source-delta, bootstrap, secret forwarding, writable path, verification command, drift check, or schema drift. This repository does not currently require the workflow as a merge gate.

Pull request checklist

Before requesting review:

  • Source changes are in skills/ or scripts/, not only in generated output.
  • pnpm build has been run when generated output should change.
  • pnpm verify passes locally or in CI.
  • Generated package diffs are expected and bounded.
  • Documentation is updated for public contracts, setup commands, generated files, or integration behavior.
  • Cursor export dry run has been run when plugins/cursor/ changes, and non-dry-run export is intentionally run or intentionally deferred.

Contributor design principles

  • Prefer one shared source of WordPress behavior and many native generated package shapes.
  • Keep the generated output reviewable by making verifier expectations explicit.
  • Preserve stable public names: wordpress-studio, wordpress-telemetry, WordPress Studio, and record_workflow_event.
  • Keep telemetry non-blocking and opt-out aware.
  • Keep Studio runtime ownership separate from this repository's agent-facing packaging responsibilities.

Related documentation