docs(docs): add v1 to v2 migration guide - #514
Conversation
Document the coordinated package upgrade, configuration and transport changes, direct schema migration, and runtime-specific validation paths. Add verified v1 migration knowledge, a guide blueprint, documentation navigation, and package README links so the guide ships with the v2 release.
Code Review Agent Run #2a3121Actionable Suggestions - 0Additional Suggestions - 1
Review Details
Bito Usage GuideCommands Type the following command in the pull request comment and save the comment.
Refer to the documentation for additional commands. Configuration This repository uses Documentation & Help AI Code Review powered by |
Impact Analysis by BitoCross-Repository Impact Analysis
Code Paths AnalyzedImpact: Flow: Direct Changes (Diff Files): Repository Impact: Cross-Repository Dependencies: Database/Caching Impact: API Contract Violations: Infrastructure Dependencies: Additional Insights: Testing RecommendationsFrontend Impact: Service Integration: Data Serialization: Privacy Compliance: Backward Compatibility: OAuth Functionality: Cross-Service Communication: Reliability Testing: Additional Insights: Analysis based on known dependency patterns and edges. Actual impact may vary. |
✅ Review Settings OverriddenStatus: Guidelines:
Note: Extra guidelines beyond 3 general purpose guidelines and 1 language specific guideline per language are not processed. Guidelines are fetched from the source branch. |
![bito-code-review[bot]](https://avatars.githubusercontent.com/in/1061978?s=60&v=4){kind=small}
…rn lock (#515) * feat(docs): require every published doc slug to be recorded in the Fern lock `documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md` merged in #514 without a `documentation/fern-slugs.lock.json` entry, which was allowed: the exporter reconciles an unrecorded document in memory, so the page publishes either way. What it silently lost was slug protection. The existing check can only compare a slug against one the lock already names, and the sync workflow runs `pnpm docs:fern` without `--update-lock`, so an entry an author never commits never appears. That page's first slug reword would have moved a live URL with no redirect — the exact failure the lock exists to prevent. It was the first new page since the lock landed in #442, so the gap had never been reachable before. `pnpm fern:check` now reports an unrecorded slug the same way it reports a changed one, naming the command that fixes it, and records the missing v1-to-v2 entry so the check passes on `main`. The slug-change path is unchanged. Because a check only catches what reaches CI, the contract is also written down where an author meets it: a new `docs-site-publishing` skill owns the four artifacts that decide whether a page ships (group README `children:`, the `fern:` block, the slug lock, MDX safety), the group-global sidebar ordering rule, and the release-gated sync. `optimization-guide-authoring` now routes to it from a publication step in its workflow, and the self-review checklist gains a mechanical section G. `documentation/AGENTS.md` documented only how to change a slug, never how to record one, and never that `children:` is what publishes a document at all; both are now stated. Validation: `pnpm fern:check`, `pnpm guides:check`, `pnpm knowledge:check`, `pnpm lint`, `pnpm typecheck`, ESLint on both changed scripts, targeted Prettier on every changed file, `git diff --check`. Verified by hand that the new check fires on an unrecorded page and that a changed slug is still reported. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(docs): cut the publishing skill to what is not already written down The first draft restated ADR 0002 and the `documentation/AGENTS.md` publishing section at length. Both already own this material, so the skill was mostly a third copy that could drift from them. It now points at those two as sources of truth and keeps only what neither records: that a document absent from its group README `children:` is silently not published, that `children:` order is global across the group so an index decides position *within* a section, and that a new slug has to be recorded and committed with the page. Same cut in the self-review checklist. `pnpm fern:check` mechanically enforces the `fern:` block shape, slug format, link and anchor resolution, MDX safety, and slug recording, so restating those as human checkboxes added nothing. Section G now asks only what a check cannot judge: intent — whether the `children:` index is the intended position, whether a slug change is deliberate, and whether the lock diff shipped with the guide. Descriptions are matched, not read, so the skill's own description is now a short purpose plus its trigger conditions rather than a summary of its contents. Wire `fern:check` into the documentation-integrity Stop hook, which ran `knowledge:check` and `guides:check` but not the check that decides whether an edit reaches the public site at all. This is the part that actually fires unprompted: the publishing contract breaks silently, so it needs a trigger that does not depend on anyone thinking to look. Watched paths gain `documentation/concepts`, the slug lock, and the fern scripts. Validation: `pnpm fern:check`, `pnpm guides:check`, `pnpm knowledge:check`, `bash -n` on the hook, targeted Prettier, `git diff --check`. Exercised the hook both ways — silent and exit 0 on a clean tree, and reporting the unrecorded-slug problem with its fix command after removing the lock entry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 participant
Summary
clientIdtospaceIdrename, themaintomasterdefault change, Web Component and native initialization updates, API route changes, direct schema changes, and runtime-specific validationRelease coordination
This documentation is intended to ship with release PR #503. Its version matrix matches that release: ten coordinated
2.0.0packages and@contentful/optimization-api-schemas@1.2.1.Generated changelogs in #503 are intentionally not modified by this PR.
Review
Validation
pnpm guides:checkpnpm knowledge:checkpnpm fern:checkpnpm docs:generate— completed with 0 errors; TypeDoc reported its existing warning class for unsupported code-block highlighting and unresolved generated-reference linksgit diff --checkThe repository-wide
pnpm format:checkalso inspected ignored Angular cache output and reported formatting warnings there. No cache files were modified; every file in this PR passes the targeted Prettier check.