Add the backfill census: changelog backfill inventory - #3764
Open
cotti wants to merge 1 commit into
Open
Conversation
products.yml alone cannot say which products have release-note surfaces because the release-notes feature defaults to enabled. The census enumerates every release-notes product, merges the hand-maintained source seed, and writes the versioned inventory document planning consumes. Products the seed does not cover stay visible as source-unresolved entries with a warning, so "we looked and decided no" is always distinguishable from "we never looked" and an unresolved scope can never silently produce empty bundles. Stack-versioned semver sources default to the epic's 9.0.0 cutoff; unresolved products get a scheme derived from their versioning system, always paired with a note so a guess never reads as confirmed fact. Attributed repositories are checked against the local assembler.yml allowlist (planning re-validates against the deployed identity). The inventory contract now allows a null source repository/ref for source-unresolved entries only — the census records products whose location is unknown, which the previous required fields could not express. Part of elastic/docs-eng-team#673 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
reakaleek
approved these changes
Aug 4, 2026
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.
Why
Backfill planning needs a full census before any selective run:
config/products.ymlcannot identify release-note surfaces on its own because therelease-notesfeature defaults to enabled, and only products with published history or native artifacts should produce backfill actions — while everything else must stay visible so an unresolved scope can never silently produce empty bundles.Part of elastic/docs-eng-team#673 (sub-issue of the backfill epic elastic/docs-eng-team#656). Stacked on #3681 — the census writes the v1 inventory contract that PR introduces.
What
A new
docs-builder changelog backfill inventorycommand (read-only apart from the local output file) backed byInventoryCensusService:products.ymland merges a hand-maintained census seed (YAML) mapping products to their release-note sources — repository, ref, paths, target scheme, cutoff, substitutions, attributed repositories, adoption state, and classification.source-unresolvedentries with a warning; products can instead be deliberately deferred underunmapped, each with an auditable reason.source-unresolvedis not seedable — it is the census's own conclusion, never an operator claim.9.0.0cutoff when none is given; unresolved products get a target scheme derived from their versioning system (serverless/project → date, ech → monthly), always paired with a note so a guess never reads as confirmed fact.assembler.ymllink allowlist (advisory — planning re-validates against the deployed scrubber allowlist identity, docs-eng-team#671 / Publish and resolve the deployed scrubber allowlist identity #3763).BackfillDocuments: enveloped, schema-versioned, validated, content-addressed. Same inputs produce the same hash.One contract adjustment to the parent PR's
InventoryDocument:SourceRepository/GitRefare now null-able only forsource-unresolvedentries — the census records products whose location is unknown, which the previously required fields could not express. Validation still demands both for every other classification.Verified end-to-end against the real repo config: 87 release-notes products enumerated; with a sample seed, the elasticsearch source got the stack default cutoff and
elastic/cloudcorrectly reported off-allowlist.