Skip to content

Commit 6f59682

Browse files
authored
docs(fern): publish ordered version snapshots (ai-openshell#3721)
* docs(fern): publish and order versioned release docs Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> * docs(fern): remove version availability badges Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> * docs(fern): keep version badges optional Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> --------- Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
1 parent d7f9211 commit 6f59682

7 files changed

Lines changed: 112 additions & 52 deletions

File tree

‎.github/workflows/release-dev.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -577,7 +577,6 @@ jobs:
577577
source_ref: ${{ github.sha }}
578578
release_version: ${{ needs.compute-versions.outputs.docs_version }}
579579
display_name: Dev
580-
availability: beta
581580
publish: true
582581
secrets:
583582
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

‎.github/workflows/release-tag.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -758,9 +758,10 @@ jobs:
758758
uses: ./.github/workflows/sync-docs.yml
759759
with:
760760
operation: sync
761-
channel: latest
761+
channel: stable
762762
source_ref: ${{ needs.compute-versions.outputs.source_sha }}
763763
release_version: ${{ needs.compute-versions.outputs.semver }}
764+
version_slug: v${{ needs.compute-versions.outputs.semver }}
764765
display_name: Latest (v${{ needs.compute-versions.outputs.semver }})
765766
publish: true
766767
secrets:

‎architecture/build.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ OpenShell builds these main artifacts:
2323
| VM driver/runtime assets | `crates/openshell-driver-vm` |
2424
| Published docs site | `docs/` rendered by Fern config in `fern/` |
2525

26+
Release Tag publishes the same tagged docs commit as an immutable `vX.Y.Z`
27+
snapshot and the mutable `latest` alias. Release Dev updates `dev`. The Fern
28+
selector pins `latest` and `dev`, then lists versioned snapshots newest first.
29+
The current release workflows do not request availability badges.
30+
2631
Workload images are standard OCI images supplied by operators or users.
2732

2833
## Build Features

‎fern/README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,14 +41,17 @@ The generated `docs-website` branch contains the complete production input for F
4141

4242
The automated site uses these version types:
4343

44-
| Version | Source | Update policy | Fern status |
45-
|---|---|---|---|
46-
| `latest` | The newest stable release. | Mutable. A maintenance release older than the current stable release cannot move it backward unless a maintainer explicitly allows a rollback. | No status before v0.1.0. |
47-
| `dev` | The most recent successful Release Dev run from `main`. | Mutable. Automation rejects an older version or the same version from a different commit unless a maintainer explicitly allows a rollback. | Beta. |
44+
| Version | Source | Update policy |
45+
|---|---|---|
46+
| `latest` | The newest stable release. | Mutable. A maintenance release older than the current stable release cannot move it backward unless a maintainer explicitly allows a rollback. |
47+
| `dev` | The most recent successful Release Dev run from `main`. | Mutable. Automation rejects an older version or the same version from a different commit unless a maintainer explicitly allows a rollback. |
48+
| `vX.Y.Z` | The tagged release commit. | Immutable. A later sync cannot replace its source commit. |
4849

4950
Release Dev waits for the development artifacts and Helm chart, then calls `.github/workflows/sync-docs.yml` once. The reusable workflow updates `dev`, validates the generated site, commits and pushes the branch when needed, and publishes the production site once.
5051

51-
Release Tag follows the same sequence for a non-prerelease tag after the release artifacts, SDK package, Helm chart, and wheel publication complete. It updates `latest` when the release is not older than the current version, then publishes the production site once.
52+
Release Tag follows the same sequence for a non-prerelease tag after the release artifacts, SDK package, Helm chart, and wheel publication complete. One sync copies the tagged source into both the immutable `vX.Y.Z` snapshot and `latest` when the release is not older than the current version, then publishes the production site once. The version selector pins `latest` and `dev` first, followed by versioned snapshots in descending version order. Other historical entries follow in their existing order.
53+
54+
The sync workflow still accepts an optional Fern availability badge, but the current Release Dev and Release Tag jobs do not request one. The next `dev` sync replaces the existing `dev` Beta badge with an unbadged entry. Other entries retain their badge setting until that entry is synced or removed.
5255

5356
The sync and publish workflows share the `docs-website` concurrency group. This serializes writes and publication. Queued runs remain pending instead of replacing one another.
5457

‎fern/docs.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,6 @@ versions:
5959
- display-name: Dev
6060
path: ../docs/index.yml
6161
slug: dev
62-
availability: beta
6362
announcement:
6463
message: '<span style="display: block; padding: 0.375rem 0; text-align: left;"><strong>New in OpenShell 0.1.0:</strong> a stable release cadence, new isolation primitives, an expanded extension surface, and new APIs. <a href="https://docs.nvidia.com/openshell/dev/upgrade/0-1-0" target="_blank" rel="noreferrer">Read the 0.1.0 upgrade guide</a>.</span>'
6564

‎tasks/scripts/sync_docs_website.py‎

Lines changed: 18 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,8 @@ def resolve_display_name(
9191
return slug
9292

9393

94-
def resolve_availability(channel: str, override: str) -> str | None:
95-
availability = override or ("beta" if channel == "dev" else "")
94+
def resolve_availability(override: str) -> str | None:
95+
availability = override
9696
if not availability:
9797
return None
9898
if availability not in VERSION_AVAILABILITIES:
@@ -110,12 +110,6 @@ def parse_release_version(value: str) -> Version:
110110
raise ValueError(f"invalid release version: {value}") from exc
111111

112112

113-
def default_stable_availability(release_version: str) -> str | None:
114-
if parse_release_version(release_version) >= Version("0.1.0"):
115-
return "stable"
116-
return None
117-
118-
119113
def ensure_existing(path: Path, label: str) -> None:
120114
if not path.exists():
121115
raise FileNotFoundError(f"{label} does not exist: {path}")
@@ -340,18 +334,20 @@ def ordered_entries(
340334
) -> list[VersionEntry]:
341335
by_slug = {entry.slug: entry for entry in existing}
342336
by_slug[updated.slug] = updated
343-
existing_order = [entry.slug for entry in existing if entry.slug != updated.slug]
337+
pinned = [by_slug[slug] for slug in ("latest", "dev") if slug in by_slug]
344338

345-
order: list[str] = []
346-
for slug in ("latest", "dev"):
347-
if slug in by_slug:
348-
order.append(slug)
349-
for slug in existing_order:
350-
if slug not in order and slug in by_slug:
351-
order.append(slug)
352-
if updated.slug not in order:
353-
order.append(updated.slug)
354-
return [by_slug[slug] for slug in order]
339+
versioned: list[tuple[Version, VersionEntry]] = []
340+
other: list[VersionEntry] = []
341+
for entry in by_slug.values():
342+
if entry.slug in {"latest", "dev"}:
343+
continue
344+
try:
345+
versioned.append((parse_release_version(entry.slug), entry))
346+
except ValueError:
347+
other.append(entry)
348+
349+
versioned.sort(key=lambda item: item[0], reverse=True)
350+
return pinned + [entry for _, entry in versioned] + other
355351

356352

357353
def render_versions(entries: list[VersionEntry]) -> list[YamlMapping]:
@@ -492,7 +488,7 @@ def sync_docs(args: argparse.Namespace) -> None:
492488
)
493489
slug = resolve_slug(channel, version_slug)
494490
display_name = resolve_display_name(channel, slug, source_ref, display_override)
495-
availability = resolve_availability(channel, availability_override)
491+
availability = resolve_availability(availability_override)
496492
metadata_path = target_fern / SNAPSHOT_METADATA_FILE
497493
snapshots = read_snapshot_metadata(metadata_path)
498494
docs_yml = target_fern / "docs.yml"
@@ -503,9 +499,6 @@ def sync_docs(args: argparse.Namespace) -> None:
503499
if slug != expected_slug:
504500
raise ValueError(f"stable version slug must be {expected_slug}, got {slug}")
505501
ensure_immutable_snapshot(snapshots, target_fern, slug, source_sha)
506-
stable_availability = availability or default_stable_availability(
507-
release_version
508-
)
509502
write_snapshot(
510503
source_docs,
511504
source_fern,
@@ -514,7 +507,7 @@ def sync_docs(args: argparse.Namespace) -> None:
514507
slug=slug,
515508
display_name=slug,
516509
path=f"./versions/{slug}.yml",
517-
availability=stable_availability,
510+
availability=availability,
518511
announcement=source_version_announcement(
519512
source_fern / "docs.yml", slug
520513
),
@@ -543,7 +536,7 @@ def sync_docs(args: argparse.Namespace) -> None:
543536
slug="latest",
544537
display_name=display_override or f"Latest ({slug})",
545538
path="./versions/latest.yml",
546-
availability=stable_availability,
539+
availability=availability,
547540
announcement=source_version_announcement(
548541
source_fern / "docs.yml", "latest"
549542
),

‎tasks/scripts/sync_docs_website_test.py‎

Lines changed: 79 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ def test_release_workflows_sync_and_publish_docs_once() -> None:
4848
)
4949
assert dev_job["with"]["publish"] == "true"
5050
assert dev_job["with"]["display_name"] == "Dev"
51-
assert dev_job["with"]["availability"] == "beta"
51+
assert "availability" not in dev_job["with"]
5252

5353
assert tag_job["needs"] == [
5454
"compute-versions",
@@ -58,12 +58,15 @@ def test_release_workflows_sync_and_publish_docs_once() -> None:
5858
"trigger-wheel-publish",
5959
]
6060
assert tag_job["uses"] == "./.github/workflows/sync-docs.yml"
61-
assert tag_job["with"]["channel"] == "latest"
61+
assert tag_job["with"]["channel"] == "stable"
6262
assert (
6363
tag_job["with"]["release_version"]
6464
== "${{ needs.compute-versions.outputs.semver }}"
6565
)
66-
assert "version_slug" not in tag_job["with"]
66+
assert (
67+
tag_job["with"]["version_slug"]
68+
== "v${{ needs.compute-versions.outputs.semver }}"
69+
)
6770
assert (
6871
tag_job["with"]["display_name"]
6972
== "Latest (v${{ needs.compute-versions.outputs.semver }})"
@@ -139,12 +142,11 @@ def test_resolve_display_name() -> None:
139142

140143

141144
def test_resolve_availability() -> None:
142-
assert sdw.resolve_availability("dev", "") == "beta"
143-
assert sdw.resolve_availability("latest", "") is None
144-
assert sdw.resolve_availability("version", "") is None
145-
assert sdw.resolve_availability("version", "deprecated") == "deprecated"
145+
assert sdw.resolve_availability("") is None
146+
assert sdw.resolve_availability("beta") == "beta"
147+
assert sdw.resolve_availability("deprecated") == "deprecated"
146148
with pytest.raises(ValueError):
147-
sdw.resolve_availability("dev", "alpha")
149+
sdw.resolve_availability("alpha")
148150

149151

150152
def test_parse_and_render_versions_preserves_version_settings() -> None:
@@ -266,12 +268,35 @@ def test_source_version_announcement_maps_single_source_version_to_channel(
266268

267269
def test_ordered_entries_pins_latest_then_dev() -> None:
268270
existing = [
269-
sdw.VersionEntry("v0.0.36", "v0.0.36", "./versions/v0.0.36.yml"),
271+
sdw.VersionEntry("v0.0.116", "v0.0.116", "./versions/v0.0.116.yml"),
270272
sdw.VersionEntry("dev", "dev", "./versions/dev.yml"),
273+
sdw.VersionEntry("v1.4.0", "v1.4.0", "./versions/v1.4.0.yml"),
274+
sdw.VersionEntry("v1.4.2", "v1.4.2", "./versions/v1.4.2.yml"),
275+
sdw.VersionEntry("v1.4.1", "v1.4.1", "./versions/v1.4.1.yml"),
276+
sdw.VersionEntry("legacy", "legacy", "./versions/legacy.yml"),
271277
]
272278
updated = sdw.VersionEntry("latest", "Latest", "./versions/latest.yml")
273279
ordered = [entry.slug for entry in sdw.ordered_entries(existing, updated)]
274-
assert ordered == ["latest", "dev", "v0.0.36"]
280+
assert ordered == [
281+
"latest",
282+
"dev",
283+
"v1.4.2",
284+
"v1.4.1",
285+
"v1.4.0",
286+
"v0.0.116",
287+
"legacy",
288+
]
289+
290+
refreshed = sdw.VersionEntry("v1.4.1", "v1.4.1", "./versions/v1.4.1.yml")
291+
refreshed_order = [entry.slug for entry in sdw.ordered_entries(existing, refreshed)]
292+
assert refreshed_order == [
293+
"dev",
294+
"v1.4.2",
295+
"v1.4.1",
296+
"v1.4.0",
297+
"v0.0.116",
298+
"legacy",
299+
]
275300

276301

277302
def test_prefix_navigation_paths() -> None:
@@ -398,7 +423,7 @@ def test_sync_docs_scopes_version_announcements_to_updated_channel(
398423
release_version="0.0.117.dev56",
399424
version_slug="",
400425
display_name="Dev",
401-
availability="beta",
426+
availability="",
402427
)
403428
)
404429

@@ -421,7 +446,6 @@ def test_sync_docs_scopes_version_announcements_to_updated_channel(
421446
"display-name": "Dev",
422447
"path": "./versions/dev.yml",
423448
"slug": "dev",
424-
"availability": "beta",
425449
"announcement": {"message": "OpenShell 0.1.0 is coming soon."},
426450
},
427451
]
@@ -463,7 +487,9 @@ def test_sync_docs_scopes_version_announcements_to_updated_channel(
463487
assert versions[1]["announcement"] == {"message": "OpenShell 0.1.0 is coming soon."}
464488

465489

466-
def test_sync_docs_preserves_other_version_availability(tmp_path: Path) -> None:
490+
def test_sync_docs_clears_updated_badge_and_preserves_other_badges(
491+
tmp_path: Path,
492+
) -> None:
467493
source = tmp_path / "source"
468494
website = tmp_path / "docs-website"
469495
_make_source_tree(source)
@@ -473,12 +499,18 @@ def test_sync_docs_preserves_other_version_availability(tmp_path: Path) -> None:
473499
yaml.safe_dump(
474500
{
475501
"versions": [
502+
{
503+
"display-name": "Dev",
504+
"path": "./versions/dev.yml",
505+
"slug": "dev",
506+
"availability": "beta",
507+
},
476508
{
477509
"display-name": "v0.0.36",
478510
"path": "./versions/v0.0.36.yml",
479511
"slug": "v0.0.36",
480512
"availability": "deprecated",
481-
}
513+
},
482514
]
483515
}
484516
),
@@ -496,7 +528,7 @@ def test_sync_docs_preserves_other_version_availability(tmp_path: Path) -> None:
496528
release_version="0.0.117.dev56",
497529
version_slug="",
498530
display_name="Dev (v0.0.117.dev56)",
499-
availability="beta",
531+
availability="",
500532
)
501533
)
502534

@@ -506,7 +538,6 @@ def test_sync_docs_preserves_other_version_availability(tmp_path: Path) -> None:
506538
"display-name": "Dev (v0.0.117.dev56)",
507539
"path": "./versions/dev.yml",
508540
"slug": "dev",
509-
"availability": "beta",
510541
},
511542
{
512543
"display-name": "v0.0.36",
@@ -589,6 +620,30 @@ def test_stable_sync_creates_immutable_version_and_promotes_latest(
589620
website = tmp_path / "docs-website"
590621
_make_source_tree(source)
591622
_make_docs_website_tree(website)
623+
(website / "fern" / "docs.yml").write_text(
624+
yaml.safe_dump(
625+
{
626+
"versions": [
627+
{
628+
"display-name": "Latest (v0.0.116)",
629+
"path": "./versions/latest.yml",
630+
"slug": "latest",
631+
},
632+
{
633+
"display-name": "Dev",
634+
"path": "./versions/dev.yml",
635+
"slug": "dev",
636+
},
637+
{
638+
"display-name": "v0.0.116",
639+
"path": "./versions/v0.0.116.yml",
640+
"slug": "v0.0.116",
641+
},
642+
]
643+
}
644+
),
645+
encoding="utf-8",
646+
)
592647

593648
sdw.sync_docs(
594649
Namespace(
@@ -609,10 +664,14 @@ def test_stable_sync_creates_immutable_version_and_promotes_latest(
609664
assert (fern / "pages-v0.2.0" / "intro.mdx").is_file()
610665
assert (fern / "pages-latest" / "intro.mdx").is_file()
611666
versions = read_yaml(fern / "docs.yml")["versions"]
612-
assert [entry["slug"] for entry in versions] == ["latest", "v0.2.0"]
667+
assert [entry["slug"] for entry in versions] == [
668+
"latest",
669+
"dev",
670+
"v0.2.0",
671+
"v0.0.116",
672+
]
613673
assert versions[0]["display-name"] == "Latest (v0.2.0)"
614-
assert versions[0]["availability"] == "stable"
615-
assert versions[1]["availability"] == "stable"
674+
assert all("availability" not in entry for entry in versions)
616675
snapshots = read_yaml(fern / sdw.SNAPSHOT_METADATA_FILE)["snapshots"]
617676
assert snapshots["latest"] == {
618677
"source-ref": "v0.2.0",
@@ -892,6 +951,7 @@ def test_remove_docs_drops_snapshot(tmp_path: Path) -> None:
892951
fern = website / "fern"
893952
assert (fern / "pages-v0.0.36").is_dir()
894953
assert (fern / "versions" / "v0.0.36.yml").is_file()
954+
assert read_yaml(fern / "docs.yml")["versions"][0]["availability"] == "deprecated"
895955

896956
sdw.remove_docs(
897957
Namespace(

0 commit comments

Comments
 (0)