Repository navigation
Conversation
The preview needs one checked-in source of truth for its toolchain, upstreams, runtime, limits, and behavioral smoke targets. Loose refs make the cache lie and make builds drift. Validate official repositories and full commits, resolve beta to a concrete versioned download, bind every material base input into the cache key, and keep arbitrary forks inert. Review follow-ups: move from Node 20 when the harness is exercised on a supported release; make cache-key field naming and ordering explicit when the build caller lands.
The base cache is only valid when every material input names the same build. Bind the runner, PHP version, concrete WordPress beta, dependency manifest, and harness into one exact key. Stage only eligible Core PHP as parser input. Fetch the pinned commit before every checkout; otherwise a reused clone breaks as soon as a dependency pin moves.
The DevHub themes do not carry a complete immutable Node toolchain. Letting their ranges resolve at build time makes the invariant cache depend on the day it was built. Pin Yarn and the WordPress build packages in the central manifest and lock their dependency graph. A changed pin now changes the exact base-cache identity.
Rebuilding themes, plugins, parser dependencies, and the empty DevHub site on every preview wastes the expensive half of the job. Build that state once under the exact cache key and write the completion marker last. The untrimmed base was 98,884,490 bytes. Drop unused CJK preview fonts before packaging; the real cold build falls to 43,224,482 bytes and leaves room for the reference import without weakening the 100 MiB limit.
The preview must parse the exact Core checkout without loading it. Stage only eligible PHP, run the pinned parser, and normalize source roots for the later import. Current trunk yields 1,318 files, 764 classes, 7,316 methods, 4,386 functions, 1,031 hooks, and 2,397 filters. Fixed low floors catch collapse without pretending counts are stable. Empty output is advisory metadata, not a publisher candidate.
The invariant base is not a runnable reference. Restore it, import every parser record, cache source, remove the parser, and only then lock the runtime. An oversized result must never reach publication.
Runtime policy cannot live only in build metadata. Install it after import, show the exact source and run on every page, and expose the final state for behavioral validation. Block WordPress HTTP requests so the preview cannot quietly depend on the network.
Parser success does not prove a runnable preview. Boot the exported snapshot and exercise the index, representative symbols, search, provenance, import completion, and runtime policy through Playground. Return defects as validation state so advisory mode can report them without publishing the candidate.
Workflow YAML must not own build semantics. Resolve the pinned inputs, build or reuse the exact base, parse Core, package once, boot the result, and emit one terminal handoff from a repository-local command. A behavioral failure is never publishable; a fatal build still reports identity and still fails.
The parser importer includes the Core version file. Pointing every record at the pull request source let untrusted PHP run during snapshot import. Give that one record a trusted empty replacement and create it before import. Route and search checks also accepted generic responses. Require representative symbol content and the expected search result path. Non-blocking: imported WordPress version metadata remains unset. Exact source-link behavior is deferred.
Preview builds must use the exact fork head without write authority. Run only for the one-shot label or a labeled synchronize event, and bind the invariant base to one exact cache key. A repeated SHA must not burn another full import when its public snapshot is healthy. Reuse only after the Playground proxy returns the expected headers, bytes, and digest. A rerun bypasses reuse. A missing handoff is a build failure. Publication remains a separate trusted change; this slice is already at the complexity tripwire.
The publisher must not infer trust from a successful build job. Bind every handoff to the enabled repository, exact workflow attempt, fetched pull request, trunk base, head repository, head SHA, schema, filename, size, and digest. Fresh and reused candidates share the same runtime and dependency checks. Failed or advisory results are terminal states, never publishable candidates. The snapshot is hashed but never opened. The network layer must refresh the latest run immediately before every mutation. A cached lookup defeats same-SHA supersession.
Fork workflow runs do not reliably carry pull request associations. Resolve the open pull request from the exact head owner, branch, repository, and SHA instead of trusting an empty field. Latest-wins needs a fresh workflow lookup, including rerun attempts. Keep that query and the release, comment, and label calls behind one narrow GitHub API client so transaction ordering remains visible in the publisher.
A release upload is not a usable preview until the public path returns the expected bytes. Validate the public metadata, launch pointer, proxy headers, size, and digest before accepting it. Obsolete fork runs exit without touching current state. Previous-preview discovery fetches accepted metadata twice. That is redundant network work, not a correctness defect.
Publication is the privileged boundary. Recheck the current head before every mutation, validate public delivery before moving the comment, and upload before deleting the old preview. Failed cleanup touches only asset IDs uploaded by this invocation. Comment, cleanup, and label failures remain visible instead of masquerading as supersession.
Publication failures must not erase the last working preview or leave the request label stuck behind unrelated cleanup. Exercise fresh publication, advisory failure, missing artifacts, latest-wins, retry collisions, public delivery failure, reuse, and ordinary transport errors. Mutation ordering is inferred from final state and injected failures rather than a separate operation log. The product boundary is still covered.
The build job cannot publish with repository authority. Run the publisher from default-branch code, bind the handoff to the exact workflow attempt and pull request, and validate public delivery before moving the sticky comment. GitHub still emits workflow runs when the build job is skipped. Ignore those exact attempts and exclude them from latest-wins selection or an unrelated label consumes the real preview request.
Pull request caches live under refs/pull/<number>/merge. List that exact scope and delete only returned cache IDs; a broad cache deletion can destroy the shared trunk base. The cache assertions share the release transport test. That is test organization, not a boundary gap.
A new unlabeled commit makes the published preview stale; closing the pull request removes only that PR's release assets and merge-ref docs caches. Recheck the exact head or closed state before every mutation. Do not mark the comment expired until every preview asset is gone. The tests assert final deletion sets rather than a separate ordering log; the transaction order remains explicit in the driver.
Fork pull requests need trusted stale and cleanup mutations without ever running their code. Use default-branch lifecycle code, separate stale permissions from destructive cleanup, and cancel obsolete events per pull request.
A missing label is not proof that an old stale run still owns the comment. Bind stale mutation to the absence of a non-skipped current-SHA build, and retain the prior attempted SHA when no healthy preview exists. Close cleanup must run after both the cache-writing build and trusted publisher. Cancel the build, queue cleanup durably behind publication, then enumerate assets and PR-scoped caches. Public proxy retries and reuse-validator deduplication remain follow-ups. Partial asset cleanup deliberately leaves the historical comment unchanged until a rerun completes deletion.
Label absence is not ownership. Compare the exact marked comment before mutation so a newer publisher state wins. Keep the original attempted SHA across stale transitions. Enter build concurrency only from the eligible open-PR job so closed events cannot cancel cleanup. Non-blocking follow-up: the stale lifecycle job retains an unused actions: read permission.
The stable link needs an immutable candidate identity before it can move. Bind trunk snapshots to the exact SHA, run, attempt, runtime, and size boundary, then validate the Blueprint through the public proxy. Non-blocking follow-ups: consolidate the duplicated snapshot-size constant and document the public-Blueprint validator's boundary-4 justification.
The publisher cannot trust its trigger once trunk moves. Read the current trunk ref and newest workflow attempt before each mutation, and use GitHub's asset rename operation for the stable pointer transaction. Non-blocking follow-up: add direct coverage for ordering two valid trunk runs.
Two asset renames can strand the stable URL between names. Validate an immutable Blueprint commit publicly, move one Git ref atomically, and re-read its SHA before deleting the previous snapshot. Unknown ref state retains both asset generations. The pointer cannot outlive the snapshot it names. Non-blocking follow-ups: exercise the stable branch URL in staging and tolerate unreachable pointer commits from failed attempts.
The pointer transaction is only useful if failures cannot erase its target. Cover public candidate rejection, atomic-ref ambiguity, unknown ref state, cleanup failure, and strict mutation ordering. Non-blocking follow-ups: assert metadata-fetch ordering and unchanged ref identity in invalid terminal cases directly.
The shared cache and stable pointer rot if trunk does not exercise the real build. Build the exact pushed SHA with read-only authority, then hand it to queued default-branch publisher code. Non-blocking follow-ups: reduce duplicated PR/trunk orchestration and broaden the publisher concurrency comment.
The preview is useless if contributors cannot operate or recover it. Document the exact local command, pins, cache scopes, label lifecycle, publication names, rollback behavior, and justified validators. Keep the repository README on one stable Blueprint URL. Trunk publication moves the ref, not this link.
A validated commit is not the URL contributors open. The public proxy can still serve the old Blueprint after the ref moves; deleting that snapshot then breaks the stable link. Fetch the stable URL before cleanup. If delivery has not caught up, retain both complete generations. Non-blocking follow-up: retry transient public-pointer propagation before retaining both generations.
Job-level environment expressions cannot read the runner context. Both preview builds would fail workflow validation before the local pipeline started. Use the runner-provided temporary directory inside each shell step. Keep the required publication queue and narrowly silence the repository's older actionlint for that one current GitHub syntax key. Non-blocking follow-up: upgrade actionlint when it accepts GitHub's current concurrency queue key, then remove the narrow suppressions.
The preview scripts passed their own tests but failed Core's JavaScript gate. Format the affected modules, write command output directly to the intended streams, and remove test-only shadowing. The transaction logic and emitted diagnostics do not change.
The build helpers failed Core's PHP standards gate. Apply the project formatter and make the fixed five-post-type query explicit so PHPCS can verify the prepared statement without a suppression. Build and runtime behavior do not change.
Stale comments used the current head as their hidden source, losing the identity of the retained preview. Delayed synchronize jobs could also overwrite a terminal comment for the current head. Keep the retained preview identity and ignore only genuine terminal state for the event SHA. Otherwise the comment can claim the wrong commit or regress after publication. Non-blocking follow-ups: make terminal state machine-readable and simplify the A-to-B-to-A stale wording.
A shared proxy failure made previous-preview discovery return nothing. Failure reporting then erased the last successful link even though its assets remained. Recover only the publisher-rendered link and source identity from the existing bot comment. A candidate failure must report the failure without making the previous preview unavailable.
The upstream README must target WordPress, but that URL cannot prove the staging pointer. Use the staging repository only in the staging branch so its next push exercises the real stable entry point.
The validator forced one worker even though the pinned CLI warns that low worker counts can deadlock on file locks. A ready server could then stop answering health checks and invalidate every snapshot. Use the CLI default and lock that command line down.
GitHub exposes four CPUs, so Playground selected three workers and exported a malformed SQLite database in both staging builds. Invoke the pinned programmatic API with its recommended six workers and validate with the same count. If this is wrong, every reference route dies with a database error.
Playground exports a live filesystem after running the Blueprint. Multiple build workers left SQLite corrupt after the full reference import. Build with one worker, then boot the finished snapshot with six. If this regresses, every reference route dies before publication.
GitHub can expose a stale ref immediately after creating the stable pointer. Treating that read as proof of failure deleted the assets the new pointer named. Any unconfirmed mutation now retains both generations; the next successful publication cleans the orphan.
The staging lifecycle needs a fork head distinct from its base. Change one PHPDoc sentence so the parser input and exact source SHA can be verified without changing executable Core behavior.
The latest-wins test needs a new fork head while the label remains present. Change parser-visible prose without changing executable Core behavior so the obsolete run must yield to the new SHA.
Fork pull_request runs do not receive the base repository's Actions variables. The old condition made the required fork lifecycle impossible to exercise in staging.\n\nAllow the hard-coded staging repository to run only the untrusted read-only build. Keep trunk, publication, lifecycle, and cleanup behind DOCS_PREVIEW_STAGING.
Fork pull_request runs cannot read the base repository's Actions variables. The old check silently left every fork in advisory mode, so DOCS_PREVIEW_ENFORCE did not enforce anything.\n\nApply the exact base-repository value in the trusted publisher after it records the failure and preserves the live preview.
The publisher collapsed multiple failures into an AggregateError and discarded every cause. That leaves a broken comment or label path with no actionable log.\n\nPrint the nested causes after the transaction has already failed. Publication behavior and exit status stay unchanged.
The trusted publisher could upload snapshots but GitHub rejected every PR comment and label mutation. Declaring pull requests read-only made the required lifecycle impossible.\n\nGrant write access to pull requests and drop the redundant issue scope. The trunk publisher remains unchanged.
The staging gate needs proof that publisher failure leaves the live preview untouched. Point the trusted publisher at a reserved invalid proxy identity. This commit is temporary and must be reverted after the failure is recorded.
The forced publisher failure has one purpose and must not survive the staging test. Restore the real Playground CORS proxy exactly; leaving the fault in place would break every later publication.
Stale lifecycle work discarded the last working link when public revalidation was temporarily unavailable. Its token also used a different PR write scope than the publisher.\n\nReuse the marked comment's last-successful identity as the fallback and grant the same pull-request write permission. A proxy outage now leaves the working preview reachable while the comment moves to Stale.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Code Reference documentation previewStatus: Ready Source: f0ad54004db0c6a9e944182256f15472a352af24 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Staging only, on the fork. Exercises the simplified pipeline end to end: build, publish, the one persistent comment, the stale path on a further push, and cleanup on close.
The single Core change adds a sentence to the
wp_parse_argsdocblock. The build's own validation already fetches/reference/functions/wp_parse_args/, so that sentence appearing on the preview proves the snapshot was built from this pull request's head rather than from trunk.The trunk path was verified separately by run 34192383016.