Skip to content

[Add] a per-site project type driving clone, status and build (#251) - #255

Open
juanmaguitar wants to merge 1 commit into
trunkfrom
juanmaguitar/support-gutenberg-as-a-contribution-target-not-o
Open

[Add] a per-site project type driving clone, status and build (#251)#255
juanmaguitar wants to merge 1 commit into
trunkfrom
juanmaguitar/support-gutenberg-as-a-contribution-target-not-o

Conversation

@juanmaguitar

@juanmaguitar juanmaguitar commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Why

The toolkit assumes every site is a wordpress-develop checkout — the repo it clones, how it
decides a site is "built", and the run/build commands are all hard-wired to WordPress Core. A
contributor who wants to work on the block editor (Gutenberg) has no path in, even though the shape
of the work is nearly identical. Part of #251.

What changes

Each site gets a project type, chosen once at creation, and that single choice drives the parts
of the flow that differ. This PR covers setup/clone, built-status, and run/build; serving
Gutenberg in a real WordPress (PR next) and the GitHub-issue work-item / pull-request flow (PR after)
follow.

  • src/project-type.cjs — one registry describing each target (Core, Gutenberg): clone
    URL/branch, PR upstream, built-check marker path, dev/build scripts, allowed terminal scripts —
    plus the serve strategy, patch layout and work-item provider the later PRs will read.
    getProjectType / projectTypeForSite default to Core for any unknown or missing id, so sites
    created before this field existed need no migration and the Core path stays byte-identical.
  • wordpress:setup resolves the type once and uses it for both the clone and the siteMeta it
    writes, so the two cannot disagree; site:status returns it.
  • Built-check is per project: Core's build/wp-includes/js/dist vs Gutenberg's
    build/block-library.
  • git:update-trunk pulls from the site's own upstream — updating a Gutenberg checkout from
    Core's trunk would overwrite it with a different project.
  • Wizard + terminal: a "Contribute to" choice (default Core); the dev-server plan (npm run dev
    vs Core's grunt -- _watch) and the terminal allow-list come from the chosen type. The sidebar
    button, modal and docs are retitled to the type-neutral "contributor site"; the create-site and
    empty-state screenshots are regenerated.

Deliberately not here: no Gutenberg serve yet (a Gutenberg site can clone/install/build but its
Playground preview comes in the next PR), and the work item is still Trac-only (GitHub issues land
with the PR flow).

How to test this

Platforms: any — no path/spawn/line-ending behavior changes; the marker path is composed with
path.join.

Starting state: the app open on the site list.

  1. Click Create a contributor site. → Modal titled "Create a contributor site" with a
    Contribute to choice, WordPress Core (Trac tickets) selected.
  2. Create a site as Core (don't touch the choice). → Clones wordpress-develop; install, build, and
    dev server behave exactly as before.
  3. Create a second site, pick Gutenberg (GitHub issues). → Clones WordPress/gutenberg; after
    npm run build the checklist reports it built (marker build/block-library); the terminal's
    npm run <script> list is Gutenberg's; starting the dev server runs npm run dev (not Grunt).
  4. On the Gutenberg site, Update to latest trunk. → Pulls from WordPress/gutenberg, not
    wordpress-develop.

What must not have happened:

  • No existing site changed behavior. A site with no projectType reads as Core everywhere, with
    no store rewrite on status read.
  • A Gutenberg site must not be reported "built" merely because a build/wp-includes/js/dist
    exists — the marker is its own (test/ipc-wiring.test.cjs pins this negative case).
  • The Core clone/build/watch path is byte-identical — same clone args, same grunt -- _watch.

Automated: npm run lint clean; npm test797 pass, 0 fail. New/extended coverage in
test/project-type.test.cjs, test/dev-server-command.test.cjs (Gutenberg npm run dev branch),
and test/ipc-wiring.test.cjs (clone URL, built marker incl. the negative, and update-trunk URL per
type; setup persistence + normalization).

Risks and limitations

⚠️ Do not merge this before the rest of the Gutenberg stack. The wizard exposes a live
Gutenberg choice, but only clone/status/build honor the type here — serving Gutenberg in
Playground and the GitHub-issue patch/PR flow land in the following PRs. This PR and its
follow-ups (serve; work-item + PR) are meant to merge together, so the choice never reaches a
user in a half-working state. Merged alone, a contributor who picks Gutenberg would get a site
that clones and builds but cannot be previewed or produce a valid patch/PR. Review outcome below.

  • Some UI/docs copy still uses Core's src/ framing (e.g. "Edited files in src/? Run npm run
    build"); a Gutenberg-aware copy pass rides with the later, user-facing PRs.

Related

Part of #251.


Design decisions and alternatives considered
  • One registry, not scattered if (type === …). The Core assumptions were spread across clone,
    status, dev-server-command.cjs, and the trunk-update URL. Consolidating them into
    src/project-type.cjs turns each hard-wired constant into a lookup whose Core value reproduces
    today's behavior, so the Core diffs read as pure refactors.
  • Default-to-Core on read, so no migration. Existing siteMeta records simply lack the field;
    projectTypeForSite(undefined) yields Core. Nothing is rewritten on disk.
  • Folded the "honor the type" work into the same PR as the picker. An earlier plan split this
    into an inert spine + a follow-up; combining them means the wizard never exposes a choice the app
    ignores, which removed a self-review finding entirely. Still under the size guideline (~490 lines).
  • git:update-trunk had to become type-aware here, not later — a Gutenberg site updating from
    Core's trunk is a data-loss bug, so it could not wait for a serve/PR PR.
Review outcome (required — see AGENTS.md)

1 [fix here] · 0 [follow-up]. Ran the review in
.github/instructions/code-review.instructions.md against the branch; judgement pass dispatched to
a fresh subagent. npm run lint clean, 797 tests pass.

  • 🟡 Architecture · [fix here] — the wizard exposes a live Gutenberg option while three registry
    facts (serve.strategy, patch.layout, pr.*/workItem) are not yet consumed, so a Gutenberg
    site can clone/build but not be served or produce a valid patch/PR. Resolved by merge strategy,
    not by code:
    this PR and the serve + work-item/PR follow-ups merge together (see the banner in
    Risks), so the option never reaches a user in the broken state. Deliberately kept the choice live
    rather than gating it, because the stack lands atomically.
  • No findings on the default-to-core seam across the new consumers, electron-store migration,
    site:status marker/meta ordering, renderer memoization stability, IPC validation, cross-platform
    path composition, or test quality (the per-type tests, including the negative built-marker case,
    go red if a consumer stops honoring the type).
Screenshots or recording

The create-site modal now offers a Contribute to choice (WordPress Core / Gutenberg), Core
preselected, and the sidebar button + modal are retitled. Regenerated docs screenshots:
docs/public/screenshots/create-site-modal.png and empty-state.png.

@juanmaguitar
juanmaguitar force-pushed the juanmaguitar/support-gutenberg-as-a-contribution-target-not-o branch from b571e5d to 716def9 Compare August 11, 2026 08:57
@juanmaguitar juanmaguitar changed the title [Add] a per-site project type, defaulting to WordPress Core (#251) [Add] a per-site project type driving clone, status and build (#251) Aug 11, 2026
@juanmaguitar juanmaguitar added the gutenberg-contributions Support Gutenberg as a contribution target (#251) label Aug 11, 2026
@juanmaguitar
juanmaguitar force-pushed the juanmaguitar/support-gutenberg-as-a-contribution-target-not-o branch from 716def9 to 1c66b4e Compare August 11, 2026 10:57
The toolkit assumed every site was a wordpress-develop checkout — the repo it
clones, how it decides a site is "built", and the run/build commands were all
hard-wired to WordPress Core. A contributor who wants to work on the block
editor (Gutenberg) had no path in, even though the shape of the work is nearly
identical.

Give each site a project type, chosen once at creation, and let that single
choice drive the parts of the flow that differ. This PR covers clone, status
and run/build; serving Gutenberg in a real WordPress and the GitHub-issue work
item / pull-request flow follow in later PRs.

- src/project-type.cjs: one registry describing each target (Core, Gutenberg) —
  clone URL/branch, PR upstream, built-check path, dev/build scripts, allowed
  terminal scripts, plus the serve strategy, patch layout and work-item provider
  the later PRs will read. getProjectType / projectTypeForSite default to Core
  for any unknown or missing id, so sites created before this field existed need
  no migration and the Core path is byte-identical.
- wordpress:setup resolves the type once and uses it for both the clone and the
  siteMeta it writes, so the two cannot disagree; site:status returns it.
- site:status answers "is it built?" from the type's marker path (Core's
  wp-includes dist dir vs Gutenberg's build/block-library).
- git:update-trunk pulls from the site's own upstream, not always
  wordpress-develop — updating a Gutenberg checkout from Core's trunk would
  overwrite it with a different project.
- The create-site wizard gains a "Contribute to" choice (default Core), and the
  dev-server plan and terminal allow-list come from the chosen type. The sidebar
  button, modal and docs are retitled from "WordPress Core site" to the
  type-neutral "contributor site"; the create-site and empty-state screenshots
  are regenerated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@juanmaguitar
juanmaguitar force-pushed the juanmaguitar/support-gutenberg-as-a-contribution-target-not-o branch from 1c66b4e to 747ac9b Compare August 11, 2026 13:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

gutenberg-contributions Support Gutenberg as a contribution target (#251)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant