mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-02 21:58:11 +00:00
feat: adopt directory-based docs versioning with Edge channel (#6202)
* feat: adopt directory-based docs versioning with Edge channel Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com> * style: resolve linter issues --------- Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
@@ -22,6 +22,11 @@ from rich.prompt import Confirm
|
||||
import tomlkit
|
||||
|
||||
from crewai_devtools.docs_check import docs_check
|
||||
from crewai_devtools.docs_versioning import (
|
||||
InvalidVersionError,
|
||||
MissingEdgeSourcesError,
|
||||
freeze as freeze_docs,
|
||||
)
|
||||
from crewai_devtools.prompts import RELEASE_NOTES_PROMPT, TRANSLATE_RELEASE_NOTES_PROMPT
|
||||
|
||||
|
||||
@@ -390,56 +395,39 @@ def update_pyproject_dependencies(
|
||||
|
||||
|
||||
def add_docs_version(docs_json_path: Path, version: str) -> bool:
|
||||
"""Add a new version to the Mintlify docs.json versioning config.
|
||||
"""Freeze Edge into a new snapshot and register the version in docs.json.
|
||||
|
||||
Copies the current default version's tabs into a new version entry,
|
||||
sets the new version as default, and marks the previous default as
|
||||
non-default. Operates on all languages.
|
||||
Thin compatibility wrapper around :func:`crewai_devtools.docs_versioning.freeze`.
|
||||
Materialises ``docs/v<version>/`` from ``docs/edge/`` (copies files, rewrites
|
||||
``openapi:`` refs inside the snapshot), inserts a new ``vX.Y.Z`` entry into
|
||||
every language's ``versions[]`` block just after Edge, marks it
|
||||
default + ``Latest`` (demoting the prior default), and updates the wildcard
|
||||
``/<lang>/:slug*`` redirects to point at the new version.
|
||||
|
||||
Skipped (returns False) for pre-release versions like ``1.10.1b1`` since
|
||||
those don't get their own snapshot — pre-release docs stay on Edge.
|
||||
|
||||
Args:
|
||||
docs_json_path: Path to docs/docs.json.
|
||||
version: Version string (e.g., "1.10.1b1").
|
||||
version: Version string (e.g., ``"1.10.1"``). Pre-releases are skipped.
|
||||
|
||||
Returns:
|
||||
True if docs.json was updated, False otherwise.
|
||||
True if docs.json was updated, False otherwise (missing file, missing
|
||||
Edge sources, pre-release, or snapshot already up to date).
|
||||
"""
|
||||
import json
|
||||
|
||||
if not docs_json_path.exists():
|
||||
return False
|
||||
|
||||
data = json.loads(docs_json_path.read_text())
|
||||
version_label = f"v{version}"
|
||||
updated = False
|
||||
|
||||
for lang in data.get("navigation", {}).get("languages", []):
|
||||
versions = lang.get("versions", [])
|
||||
if not versions:
|
||||
continue
|
||||
|
||||
if any(v.get("version") == version_label for v in versions):
|
||||
continue
|
||||
|
||||
default_version = next(
|
||||
(v for v in versions if v.get("default")),
|
||||
versions[0],
|
||||
)
|
||||
|
||||
new_version = {
|
||||
"version": version_label,
|
||||
"default": True,
|
||||
"tabs": default_version.get("tabs", []),
|
||||
}
|
||||
|
||||
default_version.pop("default", None)
|
||||
versions.insert(0, new_version)
|
||||
updated = True
|
||||
|
||||
if not updated:
|
||||
if _is_prerelease(version):
|
||||
return False
|
||||
|
||||
docs_json_path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
|
||||
return True
|
||||
docs_root = docs_json_path.parent
|
||||
try:
|
||||
result = freeze_docs(version, docs_root)
|
||||
except (InvalidVersionError, MissingEdgeSourcesError) as e:
|
||||
console.print(f"[yellow]Warning:[/yellow] {e}")
|
||||
return False
|
||||
|
||||
return result.docsjson_entries_inserted > 0 or result.redirects_upserted > 0
|
||||
|
||||
|
||||
ChangelogLang = Literal["en", "pt-BR", "ko", "ar"]
|
||||
@@ -1104,97 +1092,127 @@ def _update_docs_and_create_pr(
|
||||
is_prerelease: bool,
|
||||
dry_run: bool,
|
||||
) -> str | None:
|
||||
"""Update changelogs and docs version switcher, create PR if needed.
|
||||
"""Update Edge changelogs, freeze a snapshot, and open the docs PR.
|
||||
|
||||
For a stable release this freezes ``docs/edge/`` into ``docs/v<version>/``
|
||||
(after the Edge changelogs have been updated so the snapshot contains the
|
||||
new entry), updates ``docs/docs.json`` to register the new version and
|
||||
canonical-URL redirects, and opens a ``[docs-freeze]`` PR. The
|
||||
``docs-snapshots`` CI guard recognises that title prefix and allows the
|
||||
snapshot directory to land.
|
||||
|
||||
For a pre-release, only the Edge changelogs are touched (pre-releases don't
|
||||
get a frozen snapshot — they ride Edge), and the PR title omits the
|
||||
``[docs-freeze]`` prefix.
|
||||
|
||||
Returns:
|
||||
The docs branch name if a PR was created, None otherwise.
|
||||
"""
|
||||
docs_json_path = cwd / "docs" / "docs.json"
|
||||
edge_root = cwd / "docs" / "edge"
|
||||
snapshot_path = cwd / "docs" / f"v{version}"
|
||||
changelog_langs: list[ChangelogLang] = ["en", "pt-BR", "ko", "ar"]
|
||||
|
||||
if not dry_run:
|
||||
docs_files_staged: list[str] = []
|
||||
|
||||
if dry_run:
|
||||
for lang in changelog_langs:
|
||||
cl_path = cwd / "docs" / lang / "changelog.mdx"
|
||||
if lang == "en":
|
||||
notes_for_lang = release_notes
|
||||
else:
|
||||
console.print(f"[dim]Translating release notes to {lang}...[/dim]")
|
||||
notes_for_lang = translate_release_notes(
|
||||
release_notes, lang, openai_client
|
||||
)
|
||||
if update_changelog(cl_path, version, notes_for_lang, lang=lang):
|
||||
console.print(f"[green]✓[/green] Updated {cl_path.relative_to(cwd)}")
|
||||
docs_files_staged.append(str(cl_path))
|
||||
else:
|
||||
console.print(
|
||||
f"[yellow]Warning:[/yellow] Changelog not found at {cl_path.relative_to(cwd)}"
|
||||
)
|
||||
|
||||
cl_path = edge_root / lang / "changelog.mdx"
|
||||
translated = " (translated)" if lang != "en" else ""
|
||||
console.print(
|
||||
f"[dim][DRY RUN][/dim] Would update "
|
||||
f"{cl_path.relative_to(cwd)}{translated}"
|
||||
)
|
||||
if not is_prerelease:
|
||||
if add_docs_version(docs_json_path, version):
|
||||
console.print(
|
||||
f"[green]✓[/green] Added v{version} to docs version switcher"
|
||||
)
|
||||
docs_files_staged.append(str(docs_json_path))
|
||||
else:
|
||||
console.print(
|
||||
f"[yellow]Warning:[/yellow] docs.json not found at {docs_json_path.relative_to(cwd)}"
|
||||
)
|
||||
|
||||
if docs_files_staged:
|
||||
docs_branch = f"docs/changelog-v{version}"
|
||||
create_or_reset_branch(docs_branch)
|
||||
for f in docs_files_staged:
|
||||
run_command(["git", "add", f])
|
||||
run_command(
|
||||
[
|
||||
"git",
|
||||
"commit",
|
||||
"-m",
|
||||
f"docs: update changelog and version for v{version}",
|
||||
]
|
||||
console.print(
|
||||
f"[dim][DRY RUN][/dim] Would freeze docs/edge -> "
|
||||
f"{snapshot_path.relative_to(cwd)} and update docs.json + redirects"
|
||||
)
|
||||
console.print("[green]✓[/green] Committed docs updates")
|
||||
|
||||
run_command(["git", "push", "-u", "origin", docs_branch])
|
||||
console.print(f"[green]✓[/green] Pushed branch {docs_branch}")
|
||||
|
||||
pr_url = run_command(
|
||||
[
|
||||
"gh",
|
||||
"pr",
|
||||
"create",
|
||||
"--base",
|
||||
"main",
|
||||
"--title",
|
||||
f"docs: update changelog and version for v{version}",
|
||||
"--body",
|
||||
"",
|
||||
]
|
||||
else:
|
||||
console.print(
|
||||
"[dim][DRY RUN][/dim] Skipping snapshot freeze (pre-release stays on Edge)"
|
||||
)
|
||||
console.print("[green]✓[/green] Created docs PR")
|
||||
console.print(f"[cyan]PR URL:[/cyan] {pr_url}")
|
||||
return docs_branch
|
||||
|
||||
prefix = "" if is_prerelease else "[docs-freeze] "
|
||||
console.print(
|
||||
f"[dim][DRY RUN][/dim] Would create branch docs/freeze-v{version}, "
|
||||
f"open PR titled '{prefix}docs: snapshot and changelog for v{version}', "
|
||||
"and wait for merge"
|
||||
)
|
||||
return None
|
||||
|
||||
docs_paths_staged: list[str] = []
|
||||
|
||||
# Step 1: update Edge changelogs first so the snapshot we freeze afterwards
|
||||
# contains the new release's entry.
|
||||
for lang in changelog_langs:
|
||||
cl_path = cwd / "docs" / lang / "changelog.mdx"
|
||||
translated = " (translated)" if lang != "en" else ""
|
||||
console.print(
|
||||
f"[dim][DRY RUN][/dim] Would update {cl_path.relative_to(cwd)}{translated}"
|
||||
)
|
||||
cl_path = edge_root / lang / "changelog.mdx"
|
||||
if lang == "en":
|
||||
notes_for_lang = release_notes
|
||||
else:
|
||||
console.print(f"[dim]Translating release notes to {lang}...[/dim]")
|
||||
notes_for_lang = translate_release_notes(release_notes, lang, openai_client)
|
||||
if update_changelog(cl_path, version, notes_for_lang, lang=lang):
|
||||
console.print(f"[green]✓[/green] Updated {cl_path.relative_to(cwd)}")
|
||||
docs_paths_staged.append(str(cl_path))
|
||||
else:
|
||||
console.print(
|
||||
f"[yellow]Warning:[/yellow] Changelog not found at "
|
||||
f"{cl_path.relative_to(cwd)}"
|
||||
)
|
||||
|
||||
# Step 2: stable releases get a frozen snapshot + docs.json updates;
|
||||
# pre-releases ride Edge so we only need the changelog edits.
|
||||
is_freeze = False
|
||||
if not is_prerelease:
|
||||
console.print(
|
||||
f"[dim][DRY RUN][/dim] Would add v{version} to docs version switcher"
|
||||
)
|
||||
else:
|
||||
console.print("[dim][DRY RUN][/dim] Skipping docs version (pre-release)")
|
||||
console.print(
|
||||
f"[dim][DRY RUN][/dim] Would create branch docs/changelog-v{version}, PR, and wait for merge"
|
||||
if add_docs_version(docs_json_path, version):
|
||||
console.print(
|
||||
f"[green]✓[/green] Froze docs/edge -> "
|
||||
f"{snapshot_path.relative_to(cwd)} and updated docs.json + redirects"
|
||||
)
|
||||
docs_paths_staged.append(str(docs_json_path))
|
||||
docs_paths_staged.append(str(snapshot_path))
|
||||
is_freeze = True
|
||||
else:
|
||||
console.print(
|
||||
f"[yellow]Warning:[/yellow] docs freeze did not modify "
|
||||
f"{docs_json_path.relative_to(cwd)} "
|
||||
"(missing file, missing Edge sources, or snapshot already current)"
|
||||
)
|
||||
|
||||
if not docs_paths_staged:
|
||||
return None
|
||||
|
||||
docs_branch = f"docs/freeze-v{version}"
|
||||
create_or_reset_branch(docs_branch)
|
||||
for path in docs_paths_staged:
|
||||
run_command(["git", "add", path])
|
||||
|
||||
# The [docs-freeze] title prefix is what the docs-snapshots CI guard reads
|
||||
# to allow writes under docs/v*/ and image deletions. Omit it for
|
||||
# pre-releases since they don't touch frozen snapshots.
|
||||
title_prefix = "[docs-freeze] " if is_freeze else ""
|
||||
pr_title = f"{title_prefix}docs: snapshot and changelog for v{version}"
|
||||
|
||||
run_command(["git", "commit", "-m", pr_title])
|
||||
console.print("[green]✓[/green] Committed docs updates")
|
||||
|
||||
run_command(["git", "push", "-u", "origin", docs_branch])
|
||||
console.print(f"[green]✓[/green] Pushed branch {docs_branch}")
|
||||
|
||||
pr_url = run_command(
|
||||
[
|
||||
"gh",
|
||||
"pr",
|
||||
"create",
|
||||
"--base",
|
||||
"main",
|
||||
"--title",
|
||||
pr_title,
|
||||
"--body",
|
||||
"",
|
||||
]
|
||||
)
|
||||
return None
|
||||
console.print("[green]✓[/green] Created docs PR")
|
||||
console.print(f"[cyan]PR URL:[/cyan] {pr_url}")
|
||||
return docs_branch
|
||||
|
||||
|
||||
def _create_tag_and_release(
|
||||
|
||||
Reference in New Issue
Block a user