Type
Task
Scope
Multi-theme or Platform
Skillset
engineering
Description
What
.gitignore lines 7-9 read:
# Scratch output of the schema doc generator: written by add-schema-version and
# by the schema repo's PR preview workflow (SCHEMA_PREVIEW=true). See README.
schema/reference/
The path and the entry are correct and should stay. The second half of the comment is not currently true.
Why the entry stays
schema/reference/ is read by exactly one thing: a SCHEMA_PREVIEW=true build, where the schema docs instance builds current from schema/ (docusaurus.config.js lines 55-59) and sidebars-schema.js line 10 autogenerates from dirName: 'reference'. Verified on a clean checkout at fccbbe22:
npm run build — succeeds, never creates schema/reference/SCHEMA_PREVIEW=true npm run docusaurus -- build — fails on broken links to /schema/reference/* when the directory is absent
That generated tree is a rolling build of an unreleased schema branch, so it must not be committed next to the released snapshots in schema_versioned_docs/. scripts/add-schema-version.mjs also writes there, and cleans up in a finally (lines 110-112), so it only leaves debris if the run is interrupted.
What is wrong
The schema repo's PR preview workflow does not write to schema/reference/ today. It still writes to docs/schema/reference — the path used before #512 moved the schema instance out of docs/. Filed as OvertureMaps/schema#755.
Worth noting for whoever fixes that: schema/reference/ is root-anchored, so it does not match docs/schema/reference/. Output at the old path shows up as untracked (?? docs/schema/), confirmed with git check-ignore -v --no-index.
Also stale from the same move: sidebars-schema.js line 2 still describes the instance as "docs/schema and schema_versioned_docs/".
Acceptance criteria
Type
Task
Scope
Multi-theme or Platform
Skillset
engineering
Description
What
.gitignorelines 7-9 read:The path and the entry are correct and should stay. The second half of the comment is not currently true.
Why the entry stays
schema/reference/is read by exactly one thing: aSCHEMA_PREVIEW=truebuild, where theschemadocs instance buildscurrentfromschema/(docusaurus.config.jslines 55-59) andsidebars-schema.jsline 10 autogenerates fromdirName: 'reference'. Verified on a clean checkout atfccbbe22:npm run build— succeeds, never createsschema/reference/SCHEMA_PREVIEW=true npm run docusaurus -- build— fails on broken links to/schema/reference/*when the directory is absentThat generated tree is a rolling build of an unreleased schema branch, so it must not be committed next to the released snapshots in
schema_versioned_docs/.scripts/add-schema-version.mjsalso writes there, and cleans up in afinally(lines 110-112), so it only leaves debris if the run is interrupted.What is wrong
The schema repo's PR preview workflow does not write to
schema/reference/today. It still writes todocs/schema/reference— the path used before #512 moved the schema instance out ofdocs/. Filed as OvertureMaps/schema#755.Worth noting for whoever fixes that:
schema/reference/is root-anchored, so it does not matchdocs/schema/reference/. Output at the old path shows up as untracked (?? docs/schema/), confirmed withgit check-ignore -v --no-index.Also stale from the same move:
sidebars-schema.jsline 2 still describes the instance as "docs/schema and schema_versioned_docs/".Acceptance criteria
.gitignorecomment describes only what actually writes toschema/reference/, or is corrected in step with [BUG](ci) Schema PR preview generates docs to the pre-#512 path, leaving the schema sidebar empty schema#755sidebars-schema.jsdocstring refers toschema/rather thandocs/schemaschema/reference/entry itself remains