Skip to content

docs: preview generated v1 and v2 SDK documentation - #30

Draft
roncohen wants to merge 5 commits into
mainfrom
docs/sdk-versioning-preview
Draft

roncohen wants to merge 5 commits into
mainfrom
docs/sdk-versioning-preview

Conversation

@roncohen

@roncohen roncohen commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Preview the full generated Node, Browser, React and Vue SDK documentation with native GitBook v1/v2 variants. SDK READMEs and source comments in reflagcom/javascript remain authoritative; these are deterministic generated copies, not separately maintained SDK prose.

Mapping update after the real site export

  • Merged docs main at 38f10c754fe5055639f68c134c2e391344777cac with a normal merge. All exported production content/navigation/assets match that main commit.
  • Preserved the actual existing space space-1, including title, reflag-docs path, default status and repository-root (/) content directory.
  • Wrapped that space in the default Documentation section. GitBook cannot mix sections with top-level spaces.
  • Added a non-default JavaScript SDKs section at javascript-sdks, with sdk-preview-v2 and sdk-preview-v1 mapped to the complete generated variant directories. V2 is the default only within the SDK section.
  • Replaced the repository-root v2-only .gitbook.yaml fallback with explicit neutral defaults: root: ./, structure.readme: README.md, structure.summary: SUMMARY.md. Removing the config entirely produced 404s in a GitBook revision; the explicit root config restores the real homepage/navigation.
  • The standalone nested fixture retains its sample shared page; that sample does not replace the real documentation space in the root mapping.
  • Corrected both landing pages so they no longer imply that a single-space revision preview has a native variant picker.

Sources and generated content

  • v1: published-source commit b4fe5b3d9386b87c6546175c323862d9878e1430; Node 1.8.3, Browser/React 1.7.4, Vue 1.5.7. Browser/React/Vue package trees match published-tag commit 70b7fbe7e65e95e7bce5ccad64400b0c3e06f63c.
  • v2: candidate source 9f3a0ae027e386747a2d4cf7683a68dcab70b355; all four packages 2.0.0-next.0. This is unreleased source documentation, not a package release or packed/deployed acceptance.
  • Each variant contains four generated README/API-reference pairs plus Browser feedback, referenced assets, complete navigation and source/version/output-hash provenance.
  • Native, OpenFeature, Management and CLI retain independent contracts; they are not silently promoted into this selector.

Validation

  • Immutable checker install, both mappings against GitBook's published schema, generated hashes, equivalent paths, complete SDK navigation and local links/assets/anchors: pass.
  • 19 tests pass, including regressions protecting the production space identity, root content directory, documentation default and root homepage/navigation instead of the v2-only fallback.
  • Scoped formatting, zero-warning lint and whitespace checks against current main: pass. Unchanged whitespace in the incoming GitBook export was not rewritten.
  • Current CI passed, independently rebuilding both exact source checkouts, comparing generated output and compiling six React smoke examples against matching real v1/v2 declarations. The six smoke examples are not every partial example in the generated references.

GitBook preview / publication boundary

Working current-head content preview — browser-verified Getting started, React SDK and its API reference; the homepage/sidebar now render without 404s. GitBook statuses are successful on e47acbe1c12be4627cf03607da65f5065767f16b.

The native selector is still not activated/verified. This restored preview renders existing space-1 content and the existing site's navigation, not the proposed new SDK section/variants. It is not evidence that PR previews apply site-wide structure changes. Earlier v2-only and broken QKL5NIcHVQZMxg8rYJEv revisions are superseded.

No site was created, no live GitBook connection/default/sync direction was changed, and this PR is not merged or published. Do not switch the live connection to this branch or merge to main just to obtain a preview. Existing route/identity acceptance and mobile/full SDK switching remain gates.

The six local shared-v2 guide edits are excluded. The automatic release-scoped publisher remains a separate unfinished JavaScript-repository task and must preserve SDK-source ownership, published package/major boundaries and archives. Shared-v2 migration, compatible released SDK/CLI artifacts and server/snapshot readiness still gate production cutover.

@roncohen roncohen changed the title docs: add source-controlled SDK versioning preview docs: preview generated v1 and v2 SDK documentation Nov 6, 2026
Preserve space-1 and the production documentation default, add the SDK variant section, remove the v2-only root fallback, and guard the exported mapping in tests.
No content changes. Test preview generation after GitBook posted new site-wide preview statuses on the previous head rather than the merge head.
Keep README.md and SUMMARY.md at the repository root instead of the old v2-only fallback. Guard the neutral root configuration and homepage in tests.
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.

1 participant