Skip to content

fix: keep docs artifacts stable across content-only commits - #259

Merged
hannesrudolph merged 2 commits into
mainfrom
fix/docs-incremental-publication
Oct 3, 2026
Merged

hannesrudolph merged 2 commits into
mainfrom
fix/docs-incremental-publication

Conversation

@hannesrudolph

Copy link
Copy Markdown
Member

A content-only docs commit changed the Git SHA stamped into every public HTML page, defeating R2's content diff even when article rendering was cached. A recent two-page update uploaded 31,117 objects. Stop that global churn by removing the per-page deployment SHA.

Analytics release now identifies the executing JavaScript as js-<12 hex>, derived from the complete emitted runtime before its identity is prepended. Serialized analytics/consent/config and hashed lazy-module paths participate. The full incoming commit is recorded separately as buildCommit in the final R2 catalog; per-object hashes remain authoritative for retained content during partial uploads. The unused generation timestamp is also removed from the fallback search index.

Consent, pageview ownership, private-surface handling, URLs, duplicate object compatibility, Pagefind coverage, upload ordering and deployment queue guards are unchanged. On the first rollout, a tab still using the previous attribute-based runtime reports its existing local fallback after navigating to new HTML; no forced reload is introduced.

Validation:

  • Node suite: 278 passed, 1 optional SDK skip.
  • Production-mode fixture: changing only the commit preserves every artifact and produces zero content PUTs; two body edits change only the expected HTML/Markdown and fallback/native search objects.
  • Final shell-catalog proof retains incoming buildCommit and older out-of-scope object hashes.
  • Targeted analytics tests preserve two-pageview ownership and executing-runtime release across newer PJAX content.
  • Full corpus: 15,459 pages / 91,197 objects (external source-code index excluded), full smoke passed; changing only GITHUB_SHA produced zero changed/deleted objects in the actual R2 dry-run. Structured Autoreview: clean.

The first deployment changes the shell and requires a full HTML update. The upload reduction applies to subsequent content-only builds.

@hannesrudolph
hannesrudolph requested a review from a team as a code owner October 3, 2026 05:02
${mountHomeHero.toString()}
${createHomeGlimm.toString()}
const docsAnalytics=(${createDocsAnalytics.toString()})(()=>import(withBase(${JSON.stringify("/assets/" + webVitalsAssetName)})));
const docsAnalytics=(${createDocsAnalytics.toString()})(()=>import(withBase(${JSON.stringify("/assets/" + webVitalsAssetName)})),docsRuntimeRelease);
@hannesrudolph
hannesrudolph merged commit d630125 into main Oct 3, 2026
5 checks passed
@hannesrudolph
hannesrudolph deleted the fix/docs-incremental-publication branch October 3, 2026 05:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants