WordPress / WordPress/block-development-examples

Committed build/ output drifts from src/ — document the policy and enforce freshness in CI

Open
#149 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
334
Forks
52
PR merge metrics
No merged PRs in 30d

Description

Problem

All 29 build-capable example plugins commit their build/ directories (~190 tracked files). This appears deliberate — the Playground live demos load plugin files straight from trunk via each _playground/blueprint.json, so build/ must exist in git — but it is documented nowhere, and .gitignore contains an empty, typo'd stanza (# Ingnore "build" folders) suggesting the decision was never finished.

Because nothing verifies src/ and build/ stay in sync, they have drifted. Concrete example: plugins/editable-block-1b8c51 and plugins/interactive-blocks-demos-99def1/src/counter-web-component-99def1 have apiVersion mismatches baked into committed build/block.json. For a teaching repo this is the worst kind of bug: the Playground demo can run different code than the src/ people are reading.

Proposed fix
  1. Document the policy in a new CONTRIBUTING.md (the repo has none): build/ is committed on purpose because the Playground blueprints and zip downloads consume trunk directly; contributors must run pnpm build and commit the output. Link it from the root README.
  2. One-time rebuild: regenerate every plugin's build/ with its current toolchain so the tree starts fresh.
  3. CI freshness check: a workflow job that runs the build and fails the PR if git diff --exit-code 'plugins/*/build' shows changes, with a clear message: "run pnpm build and commit the result". Fail-on-diff (no auto-commit bot) so it works on forks without write access.
  4. Fix .gitignore: remove the empty misspelled stanza.
Notes
  • The freshness check assumes reproducible builds (same wp-scripts + Node → identical output). Aligning the divergent @wordpress/scripts versions across plugins is a separate normalization issue; when it lands, this check is exactly what forces the accompanying rebuild.
  • Hand-maintained asset files in no-build examples (plugins/minimal-block-no-build-e621a6/block.asset.php, plugins/editable-block-1b8c51/src/blocks/basic-editable-block-no-build-1b8c51/block.asset.php) are source, not build output — the check must not flag them.
Out of scope
  • Fixing the content-level inconsistencies revealed by the drift (apiVersion, text domains, leftover console.logs) — covered by the plugin normalization sweep issue.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the root README, .gitignore, and each plugin's _playground/blueprint.json, then run pnpm build to inspect the current generated output. Add CONTRIBUTING.md and its README link, regenerate committed build/ directories, remove the empty ignore stanza, and add a workflow that fails when git diff detects build changes; done means the tree is fresh and CI reports the pnpm build command clearly.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, javascript
Domain
build-system, ci-cd, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.