Skip to content

docs-editions.md

Latest commit

 

History

History
152 lines (118 loc) · 6.76 KB

docs-editions.md

File metadata and controls

152 lines (118 loc) · 6.76 KB
Raw

Release and maintain documentation

A docs edition versions one documented combination of Self-Managed, Compute Plane, and Observability. Stack artifacts keep their own release versions. The site has one edition selector and six tabs. Development reads current sources; legacy stable editions read protected docs/releases/X.Y.Z branches.

Choose the docs model

Existing docs/releases/X.Y.Z editions use the immutable workflow below. For an umbrella product release, use the umbrella release and maintained docs workflow. Its docs/versions/X.Y.Z branch accepts reviewed prose corrections without allocating a new product or docs patch. The canonical registry selects the approved docs commit independently from the immutable product manifest. Check the supported manifest schema before activation. Schema 2 product bundles do not yet enable the maintained-docs flow; follow the limitations in the umbrella guide. Do not convert a published legacy URL to a different stack combination.

Choose the version and combination

Record the exact three stack versions and approval of the complete combination in a public release review. A compatible range or a published artifact alone does not qualify an edition. Review current guides against the selected stack inventories before freezing them.

Use SemVer for the documented deployment contract:

  • Major: a breaking change in any selected stack or the documented contract.
  • Minor: a compatible feature addition in the documented combination.
  • Patch: a compatible fix or documentation-only correction.

Apply the highest required bump once. Two stack majors in one edition produce one edition major bump. A docs-only patch can keep all three stack versions.

main carries development metadata for the next candidate. Update its proposed version and change kind when the release scope changes. Never mark the main catalog qualified; qualification belongs to the prepared release branch.

Prepare from reviewed sources

Sync the exact inventory versions with docs-version-sync, review the generated content, and commit it. Fetch the predecessor and run the edition preflight:

git fetch origin --tags
./tools/ci/check-doc-editions

Prepare a new directory outside the checkout. The example is a docs-only patch after the initial 1.0.1; substitute the reviewed source commit and approval URL:

go run -C tools/docs-version-sync . edition prepare \
  --source <full-reviewed-source-commit> \
  --version 1.0.2 --previous-version 1.0.1 --change patch \
  --self-managed 1.0.1 --compute-plane 1.0.0 --observability 1.0.0 \
  --qualification https://github.com/NVIDIA/nvcf/pull/<release-review> \
  --out /tmp/nvcf-docs-1.0.2

The initial consolidated release is 1.0.1. For the first edition, use --version 1.0.1 --change initial and omit --previous-version. Omit --qualification while evaluating an unqualified candidate. The Prepare Docs Edition workflow performs the same preparation and uploads the files and review patch; it does not create a release branch or publish the site.

Review the prepared catalog, manifest, changelog, navigation, links, and source diff. Preserve the preparation receipt. Repeating the command with identical inputs verifies it without overwriting modified output.

Freeze and register the branch

Commit the prepared content on the full-version docs branch. Do not create a docs tag or copy a new version folder. Before pushing, verify the repository's docs-release ruleset applies to that branch. It must prohibit updates, force pushes, and deletion, with no ordinary bypass actors. Creation remains allowed.

git -C /tmp/nvcf-docs-1.0.2 switch -c docs/releases/1.0.2
git -C /tmp/nvcf-docs-1.0.2 add docs fern .docs-edition-preparation.json
git -C /tmp/nvcf-docs-1.0.2 commit -s
git -C /tmp/nvcf-docs-1.0.2 push origin HEAD:refs/heads/docs/releases/1.0.2
git -C /tmp/nvcf-docs-1.0.2 rev-parse HEAD

The release branch retains its local path default. It must not reference itself through ref. Historical archives remain hidden path entries. Verify the remote branch head and effective protection rules after creation.

From the canonical checkout, register the exact resulting commit:

go run -C tools/docs-version-sync . edition register \
  --version 1.0.2 --commit <full-docs-branch-commit>

Add the matching entry first under versions in fern/docs.yml:

- display-name: "1.0.2"
  slug: "1.0.2"
  ref: docs/releases/1.0.2

Keep Development and all historical entries. Advance the development candidate metadata separately and regenerate its manifest and summaries. The registry pins the released commit; a moved or missing branch must fail publication.

Validate and publish

Run both configurations and the tooling tests:

go test -C tools/docs-version-sync ./...
./tools/ci/check-docs
tools/ci/preview-docs --check

The default preview derives Development-first ordering from fern/docs.yml in a temporary clone. Generate a hosted preview of the canonical configuration as well by setting DOCS_PREVIEW_CONFIG=fern/docs.yml. Overrides are used as supplied, without reordering or link normalization. Local Fern previews cannot prove remote-ref composition. Verify edition switching, all six tabs, manifest versions, changelog links, archives, anchors, downloads, and mobile/light/dark rendering. Use an isolated staging instance for indexed search. Record source commits, resolved refs, preview URLs, CI results, and the last validated production commit in the release PR.

Merge the registration and activation PR only after review and the required checks. The publisher on main validates the same checkout before publishing. Release-branch pushes validate their content; they do not publish the canonical registry. Smoke-test production immediately after the publisher completes.

Correct or roll back an edition

Fix content in Development, then prepare a new patch edition. Keep the old branch and its recorded commit intact. The per-stack folder-cut commands have been removed. Existing archive folders remain available for historical URLs.

Before a cutover, retain the previous production commit and toolchain pins. Rehearse restoring it on an isolated preview. If production regresses, prepare a rollback PR from current main that reverts the activation or registration commit. Include the prior source/configuration and toolchain changes required to reproduce the validated site. Resolve intervening changes explicitly.

Validate and preview that rollback, then merge it through the normal review process. The main publisher republishes the restored configuration. Do not move or delete release branches, remove archive sources, or publish a release branch's reduced registry as the entire site. Record the failure and fix it in a new reviewed edition before retrying activation.