Skip to content

docs: show v2 SDKs with linked legacy v1 pages - #31

Draft
roncohen wants to merge 18 commits into
mainfrom
docs/manual-sdk-versioning
Draft

roncohen wants to merge 18 commits into
mainfrom
docs/manual-sdk-versioning

Conversation

@roncohen

@roncohen roncohen commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Preview

Open the latest GitBook preview

Summary

Use ordinary pages, not GitBook variants:

  • Browser / React / Vue / Node.js v2 stay at the existing supported-languages/... URLs.
  • Complete v1 guides, references, Browser feedback and images live in repository legacy/v1/, rendered by GitBook as legacy-sdks/v1/....
  • Equivalent guide/reference/feedback pages link both ways. Each current SDK guide/reference/feedback page has one “This page covers SDK v2.” line in its introduction and one short “Using v1? Legacy docs · Upgrade guide.” footer. Next.js has the same scope line and footer. Shared handbook pages and guides carry no footer; the Supported languages overview links the upgrade guide near the top. No opening banner.
  • Current SDK guides and shared examples assume a new integration. Neutral headings such as Read flags, ordinary unpinned installation commands, and no repeated old-wrapper comparisons. Explicit @2 commands and upgrade compatibility details are confined to the migration guide.
  • Plain-language pass: the four SDK guides share one task-based outline (Get started → Read flags → Track usage → Update context → Bootstrap from the server → Opt-in → Toolbar → Type safety → Configuration). Implementation internals such as check fields, deduplication, ETags and cache mechanics are removed rather than relocated. Toolbar guidance for React/Vue and the Browser CSP section are restored. Handbook pages and guides no longer carry v1-shaped caveats, and the migration guide opens with a summary of what changes.
  • Handbook: separate Multivariate flags and Remote config entries. Remote config is one short paragraph linking to the full Multivariate guide, with clearer explanations of defaults, targeting and use cases instead of blanket access prohibitions or runtime/type-system detours.
  • Remote config migration: six steps cover new flag keys, copying payloads versus keys, per-environment targeting, and retaining existing Boolean access checks/v1 consumers. The SDK upgrade guide links to the detailed steps and uses a distinct new flag key. An approval-first AI-agent prompt describes reading legacy configs through MCP and proposing a migration. Per Ron's instruction, the documentation assumes MCP is ready and uses present-tense wording.
  • Migrating from v1 is last in Supported languages. Legacy installs/CDN remain pinned to @1; Native keeps links to its supported v1 contracts.
  • Historical sdk/... copies, reference anchors, package/major ownership, deterministic imports and provenance manifests are preserved. Source/version records stay in manifests only; neither current nor legacy SDK pages display generation/provenance notices.

gitbook-docs.yaml, live settings/defaults and pre-existing draft spaces are unchanged. This fresh PR supersedes the variants approach in #30; it does not configure a native version picker.

Canonical SDK sources

SDK READMEs/source comments in reflagcom/javascript remain authoritative. The first-time-reader edits are in small, docs-only source PRs, stacked on the respective v2 feature branches:

Merge those source edits into the SDK branches before releasing, so subsequent regeneration retains the first-time-reader wording. The site-only scope line and legacy links are added by the docs importer after copying, based on the package major; every sync reapplies them without changing the source READMEs. No runtime code, package versions or feature-branch working trees were changed.

Content Pinned JavaScript source
Published v1 SDKs / Native b4fe5b3d9386b87c6546175c323862d9878e1430
Browser / React / Vue v2 ed0e7725719756855c20e939265713914e956b8b
Node v2 81297fbca156feadd3e666188f5141f42e0488dd

Verification

  • 19 importer / isolation / provenance / link / GitBook-anchor / presentation tests, including the handbook split/migration links and missing/duplicated/misplaced scope-line and fenced-heading controls
  • All 89 navigation entries, 33 generated Markdown pages, assets, reciprocal links and local anchors checked
  • Canonical generation and deterministic imports (import --check) from clean pinned source checkouts; v1/Native output and site configuration unchanged
  • 29 examples/declaration guards compile against matching built v1/v2 SDK declarations with zero diagnostics
  • Scoped formatting, zero-warning lint and whitespace checks
  • Prior-head remote CI (00dd0b4) passed all checks
  • Earlier remote CI (3d3b61e) passed all checks
  • Prior-head remote CI (42cf05d): navigation/isolation, all three source rebuilds, matching-SDK example compilation and all GitBook statuses pass
  • Latest-head CI (c35d60b) running for the one-sentence MCP wording update
  • Handbook browser QA at 42cf05d (links/layout unchanged by the latest sentence update): cleaned-up prose, both examples, all ten heading targets, SDK-upgrade round trip to the migration section, and the MCP guide link. Removed an incompatible numbered-heading fragment after browser verification
  • Package CI passes on both canonical README source PRs at their current heads (#806 ed0e772, #807 81297fb; #807's push run failed only in the test-report upload step and passed on rerun)
  • Full SDK rendered-preview browser QA has not been repeated since the plain-language pass. At bd9d10a, all four SDK guides, the React reference, Browser feedback and Next.js rendered exactly one scope line and one legacy footer, Migration was last in the rendered sidebar, and current↔legacy round trips worked

Release boundary / publishing

This remains a draft review preview, not permission to merge or publish. Current v2 sources have version 2.0.0-next.0; coordinate matching published SDK/CLI artifacts and required server changes before publishing these default-install pages. Prerelease availability is documented in the migration guide and source versions in manifests, rather than repeated notices on every page.

Companion JavaScript #804 replaces whole-tree SDK docs deletion/copy with exact-tagged, actually-released-package imports. Land this docs importer before enabling that workflow. No release workflow was dispatched.

No main merge, SDK publication, deployment, snapshot rebuild or live GitBook setting change was performed.

roncohen and others added 14 commits November 15, 2026 20:21
- Regenerate Browser/React/Vue/Node guides from restructured source READMEs:
  shared task-based outline, implementation internals removed, toolbar and
  CSP guidance restored.
- Lead the migration guide with a summary of what changes.
- Rewrite v1-shaped and spec-like prose in handbook pages and guides.
- Keep the v1 footer on SDK and Next.js pages only; surface the upgrade
  guide at the top of the SDK overview.
- Shorten the scope line to "This page covers SDK v2." and fix bootstrap
  and event anchors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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