DSPy: The framework for programming—not prompting—language models
Python
docs: remove migration scaffolding (#10332)
Isaac Millerfe51a8a4ebb7
diff --git a/.github/workflows/bootstrap-versioned-docs.yml b/.github/workflows/bootstrap-versioned-docs.ymldeleted file mode 100644index 63a14ed1d..000000000--- a/.github/workflows/bootstrap-versioned-docs.yml+++ /dev/null@@ -1,82 +0,0 @@-----name: Bootstrap versioned documentation--on:- workflow_dispatch:--permissions: {}--jobs:- bootstrap:- if: github.repository == 'stanfordnlp/dspy'- runs-on: ubuntu-latest- timeout-minutes: 180- concurrency:- group: dspy-docs-bootstrap- cancel-in-progress: false- permissions:- contents: read- steps:- - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0- with:- persist-credentials: false- fetch-depth: 0- - name: Set up Python 3.11- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0- with:- python-version: "3.11"- - name: Set up uv- uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1- - name: Install bootstrap dependencies- run: |- grep -v 'github.com/stanfordnlp/dspy' docs/requirements.txt > "$RUNNER_TEMP/docs-requirements.txt"- python -m pip install -r "$RUNNER_TEMP/docs-requirements.txt" -e .- - name: Build Material Current- run: |- python docs/scripts/build_docs.py current \- --config docs/mkdocs.yml \- --output current-site- - name: Check out documentation deployment- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0- with:- repository: krypticmouse/dspy-docs- ref: master- path: docs-deployment- persist-credentials: false- token: ${{ secrets.GH_PAT }} # zizmor: ignore[secrets-outside-env]- - name: Prepare Mike deployment branch- run: |- git -C docs-deployment config user.name github-actions- git -C docs-deployment config user.email [email protected]- set +e- git -C docs-deployment ls-remote --exit-code --heads origin versioned-docs >/dev/null- branch_status=$?- set -e- if [[ "$branch_status" == 0 ]]; then- git -C docs-deployment fetch origin versioned-docs:refs/remotes/origin/versioned-docs- elif [[ "$branch_status" != 2 ]]; then- exit "$branch_status"- fi- # Anchor the complete candidate to production so GitHub can review it as a PR.- git -C docs-deployment branch --force versioned-docs master- - name: Reconstruct all historical snapshots- run: |- python docs/scripts/bootstrap_versioned_docs.py \- --deployment docs-deployment \- --branch versioned-docs- - name: Add Material Current to the candidate deployment- run: |- python docs/scripts/publish_versioned_docs.py \- --repository docs-deployment \- --site current-site \- --identifier current \- --package-source working-tree \- --branch versioned-docs- - name: Push the complete candidate for deployment review- env:- GH_TOKEN: ${{ secrets.GH_PAT }}- run: |- gh auth setup-git- # This staging push does not change production or activate Mike.- # A reviewed dspy-docs PR promotes the candidate to master atomically.- git -C docs-deployment push --force-with-lease origin versioned-docsdiff --git a/.github/workflows/docs-push.yml b/.github/workflows/docs-push.ymlindex 61c239845..647cdbf89 100644--- a/.github/workflows/docs-push.yml+++ b/.github/workflows/docs-push.yml@@ -36,87 +36,9 @@ jobs:--config docs/mkdocs.yml \--output docs/site- detect-versioned-deployment:+ publish-current:if: github.event_name == 'push' && github.repository == 'stanfordnlp/dspy'runs-on: ubuntu-latest- permissions:- contents: read- outputs:- enabled: ${{ steps.deployment.outputs.enabled }}- steps:- - name: Check out deployment tooling- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0- with:- persist-credentials: false- - name: Check the production deployment format- id: deployment- run: |- git clone --depth 1 --branch master https://github.com/krypticmouse/dspy-docs.git docs-deployment- # The staging branch deliberately does not activate Mike. Only the- # reviewed promotion of versions.json to production master does.- if [[ ! -f docs-deployment/versions.json ]]; then- echo "enabled=false" >> "$GITHUB_OUTPUT"- elif jq -e 'type == "array" and any(.[]; .version == "current")' docs-deployment/versions.json >/dev/null; then- echo "enabled=true" >> "$GITHUB_OUTPUT"- else- echo "::error::Production versions.json does not contain Current"- exit 1- fi-- update-legacy-deployment:- needs: detect-versioned-deployment- if: needs.detect-versioned-deployment.outputs.enabled == 'false'- runs-on: ubuntu-latest- concurrency:- group: dspy-docs-deployment- cancel-in-progress: false- permissions:- contents: read- steps:- - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0- with:- persist-credentials: false- fetch-depth: 0- - name: Check out the legacy deployment- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0- with:- repository: krypticmouse/dspy-docs- ref: master- path: docs-deployment- persist-credentials: false- token: ${{ secrets.GH_PAT }} # zizmor: ignore[secrets-outside-env]- - name: Update the legacy deployment without crossing the cutover- env:- GH_TOKEN: ${{ secrets.GH_PAT }}- run: |- gh auth setup-git- if [[ -f docs-deployment/versions.json ]]; then- echo "The versioned deployment is already live; leaving it unchanged."- exit 0- fi- rsync --archive --delete --exclude=.git docs/ docs-deployment/- git -C docs-deployment config user.name github-actions- git -C docs-deployment config user.email [email protected]- git -C docs-deployment add --all- if git -C docs-deployment diff --cached --quiet; then- exit 0- fi- git -C docs-deployment commit -m "Update documentation"- if git -C docs-deployment push origin HEAD:master; then- exit 0- fi- git -C docs-deployment fetch origin master- if git -C docs-deployment show origin/master:versions.json >/dev/null 2>&1; then- echo "The versioned deployment won the race; leaving it unchanged."- exit 0- fi- echo "::error::The deployment changed concurrently; rerun this workflow"- exit 1-- update-versioned-deployment:- needs: detect-versioned-deployment- if: needs.detect-versioned-deployment.outputs.enabled == 'true'- runs-on: ubuntu-latestconcurrency:group: dspy-docs-deploymentcancel-in-progress: falsediff --git a/docs/scripts/bootstrap_versioned_docs.py b/docs/scripts/bootstrap_versioned_docs.pydeleted file mode 100644index 3bfb70111..000000000--- a/docs/scripts/bootstrap_versioned_docs.py+++ /dev/null@@ -1,212 +0,0 @@-#!/usr/bin/env python3-"""Reconstruct all configured historical documentation snapshots atomically."""--from __future__ import annotations--import argparse-import json-import re-import subprocess-import sys-import tempfile-from pathlib import Path--from publish_versioned_docs import DEFAULT_BRANCH---def run(*command: object, cwd: Path | None = None) -> None:- subprocess.run([str(part) for part in command], cwd=cwd, check=True)---def output(*command: object, cwd: Path | None = None) -> str:- return subprocess.check_output([str(part) for part in command], cwd=cwd, text=True).strip()---def download_pypi_wheel(version: str, destination: Path) -> Path:- run(- sys.executable,- "-m",- "pip",- "download",- "--no-deps",- "--only-binary=:all:",- "--dest",- destination,- f"dspy=={version}",- )- wheels = list(destination.glob("*.whl"))- if len(wheels) != 1:- raise RuntimeError(f"expected one wheel for dspy=={version}, found {len(wheels)}")- return wheels[0]---def set_release_metadata(worktree: Path, version: str) -> None:- replacements = (- (worktree / "pyproject.toml", r'(?m)^(version\s*=\s*)"[^"]+"', rf'\g<1>"{version}"'),- (worktree / "dspy" / "__metadata__.py", r'(?m)^(__version__\s*=\s*)"[^"]+"', rf'\g<1>"{version}"'),- (worktree / "pyproject.toml", r'(?m)^(name\s*=\s*)"[^"]+"', r'\g<1>"dspy"'),- (worktree / "dspy" / "__metadata__.py", r'(?m)^(__name__\s*=\s*)"[^"]+"', r'\g<1>"dspy"'),- )- for path, pattern, replacement in replacements:- text, count = re.subn(pattern, replacement, path.read_text(), count=1)- if count != 1:- raise RuntimeError(f"release metadata marker not found in {path}")- path.write_text(text)---def build_tag_wheel(worktree: Path, python: Path, version: str, destination: Path, tag_date: str) -> Path:- set_release_metadata(worktree, version)- run(- "uv",- "pip",- "install",- "--python",- python,- "--exclude-newer",- tag_date,- "build",- "setuptools",- "wheel",- cwd=worktree,- )- run(- python,- "-m",- "build",- "--wheel",- "--no-isolation",- "--outdir",- destination,- cwd=worktree,- )- wheels = list(destination.glob("*.whl"))- if len(wheels) != 1:- raise RuntimeError(f"expected one tag-built wheel for {version}, found {len(wheels)}")- return wheels[0]---def filtered_requirements(source: Path, destination: Path) -> None:- lines = [line for line in source.read_text().splitlines() if "github.com/stanfordnlp/dspy" not in line]- destination.write_text("\n".join(lines) + "\n")---def bootstrap_release(- *,- repository: Path,- deployment: Path,- scripts: Path,- version: str,- branch: str,- temporary: Path,-) -> None:- worktree = temporary / f"source-{version}"- environment = temporary / f"venv-{version}"- artifact_dir = temporary / f"artifacts-{version}"- site = temporary / f"site-{version}"- artifact_dir.mkdir()- run("git", "worktree", "add", "--detach", worktree, version, cwd=repository)- try:- run("uv", "venv", "--python", sys.executable, environment)- python = environment / "bin" / "python"- requirements = temporary / f"requirements-{version}.txt"- filtered_requirements(worktree / "docs" / "requirements.txt", requirements)- tag_date = output("git", "show", "-s", "--format=%cI", f"{version}^{{commit}}", cwd=repository)- run(- "uv",- "pip",- "install",- "--python",- python,- "--exclude-newer",- tag_date,- "-r",- requirements,- )-- package_source = "tag-built-wheel" if version == "3.1.1" else "pypi-wheel"- if package_source == "pypi-wheel":- artifact = download_pypi_wheel(version, artifact_dir)- else:- artifact = build_tag_wheel(worktree, python, version, artifact_dir, tag_date)- run(- "uv",- "pip",- "install",- "--python",- python,- "--exclude-newer",- tag_date,- artifact,- )- run(- python,- scripts / "build_docs.py",- "release",- "--config",- worktree / "docs" / "mkdocs.yml",- "--output",- site,- "--version",- version,- "--artifact",- artifact,- "--package-source",- package_source,- )- alias = (- ["--alias", ".".join(version.split(".")[:2])]- if re.fullmatch(r"\d+\.\d+\.\d+", version)- else []- )- run(- sys.executable,- scripts / "publish_versioned_docs.py",- "--repository",- deployment,- "--site",- site,- "--identifier",- version,- *alias,- "--package-source",- package_source,- "--branch",- branch,- )- finally:- run("git", "worktree", "remove", "--force", worktree, cwd=repository)---def main() -> None:- parser = argparse.ArgumentParser()- parser.add_argument("--repository", type=Path, default=Path.cwd())- parser.add_argument("--deployment", type=Path, required=True)- parser.add_argument("--manifest", type=Path, default=Path("docs/versioning/releases.json"))- parser.add_argument("--branch", default=DEFAULT_BRANCH)- parser.add_argument("--only", action="append", default=[])- args = parser.parse_args()-- repository = args.repository.resolve()- deployment = args.deployment.resolve()- manifest = json.loads(args.manifest.resolve().read_text())- releases = [version for version in manifest["releases"] if not args.only or version in args.only]- unknown = set(args.only) - set(releases)- if unknown:- parser.error(f"versions absent from manifest: {', '.join(sorted(unknown))}")-- scripts = Path(__file__).resolve().parent- with tempfile.TemporaryDirectory(prefix="dspy-docs-bootstrap-") as directory:- temporary = Path(directory)- for version in releases:- bootstrap_release(- repository=repository,- deployment=deployment,- scripts=scripts,- version=version,- branch=args.branch,- temporary=temporary,- )---if __name__ == "__main__":- main()diff --git a/docs/versioning/README.md b/docs/versioning/README.mdindex 27374d97b..230133c8b 100644--- a/docs/versioning/README.md+++ b/docs/versioning/README.md@@ -13,21 +13,17 @@ The picker lists Current and every stable or prerelease snapshot. Prereleasesdo not claim the stable minor alias. Minor aliases are navigation conveniencesand are hidden from the picker. Mike owns `versions.json`, thedefault redirect, aliases, and version directories on the generated-`versioned-docs` branch in `krypticmouse/dspy-docs`.+`master` branch in `krypticmouse/dspy-docs`.Historical snapshots use Material for MkDocs, while Current and future releasesnapshots use Zensical. Stored static versions do not need to share a renderer.-## Deployment and promotion+## Deployment-Generated candidates are written to the `versioned-docs` branch and promoted-to production `master` through reviewed pull requests in-`krypticmouse/dspy-docs`. Production's `versions.json` is the activation marker-for Mike publication; a candidate branch alone never changes production.--Renderer migrations are built on `versioned-docs` first. After that branch is-reviewed and promoted, the Current workflow's explicit publication target is-changed to `master`. There is no implicit promotion based on site metadata.+Current and release publication update production `master` in+`krypticmouse/dspy-docs`. Both paths require Mike metadata identifying Current+as Zensical before they write, so an unversioned or unexpected deployment fails+closed. Corrections use reviewed pull requests in that repository.Existing unversioned page URLs remain valid. Publishing Current generates rootredirect pages such as `/api/` → `/current/api/`, and each build scopesdiff --git a/docs/versioning/releases.json b/docs/versioning/releases.jsondeleted file mode 100644index 74d8df9dd..000000000--- a/docs/versioning/releases.json+++ /dev/null@@ -1,18 +0,0 @@-{- "releases": [- "3.0.0",- "3.0.1",- "3.0.2",- "3.0.3",- "3.0.4",- "3.1.0",- "3.1.1",- "3.1.2",- "3.1.3",- "3.2.0",- "3.2.1",- "3.3.0",- "3.3.1",- "3.4.0b1"- ]-}diff --git a/tests/docs/test_versioned_docs.py b/tests/docs/test_versioned_docs.pyindex 3c73c42db..e97d2e508 100644--- a/tests/docs/test_versioned_docs.py+++ b/tests/docs/test_versioned_docs.py@@ -56,6 +56,17 @@ def branch_file(repository, branch: str, path: str) -> str:return subprocess.check_output(["git", "show", f"{branch}:{path}"], cwd=repository, text=True)+def set_current_renderer(repository, renderer: str):+ inventory = json.loads(branch_file(repository, "versioned-docs", "versions.json"))+ current = next(entry for entry in inventory if entry["version"] == "current")+ current["properties"]["renderer"] = renderer+ subprocess.run(["git", "checkout", "-q", "versioned-docs"], cwd=repository, check=True)+ (repository / "versions.json").write_text(json.dumps(inventory, indent=2) + "\n")+ subprocess.run(["git", "add", "versions.json"], cwd=repository, check=True)+ subprocess.run(["git", "commit", "-qm", f"Set Current renderer to {renderer}"], cwd=repository, check=True)+ subprocess.run(["git", "checkout", "-q", "master"], cwd=repository, check=True)++def test_release_versions_accept_prereleases_and_reject_old_major_versions():assert release_version("3.1.2") == "3.1.2"assert release_version("3.4.0b1") == "3.4.0b1"@@ -296,6 +307,37 @@ def test_mike_current_is_mutable_and_default(tmp_path):require_current_renderer(repository, "versioned-docs", "material")+@requires_mike+def test_publication_requires_reviewed_zensical_current(tmp_path):+ repository = make_repository(tmp_path)+ deployed = make_site(tmp_path / "deployed", "deployed")+ publish_site(+ repository=repository,+ site=deployed,+ identifier="current",+ aliases=[],+ package_source="working-tree",+ )+ set_current_renderer(repository, "material")++ update = make_site(tmp_path / "update", "update")+ arguments = {+ "repository": repository,+ "site": update,+ "identifier": "current",+ "aliases": [],+ "package_source": "working-tree",+ "required_current_renderer": "zensical",+ }+ with pytest.raises(RuntimeError, match="expected 'zensical'"):+ publish_site(**arguments)+ assert "deployed" in branch_file(repository, "versioned-docs", "current/index.html")++ set_current_renderer(repository, "zensical")+ assert publish_site(**arguments)+ assert "update" in branch_file(repository, "versioned-docs", "current/index.html")++@requires_mikedef test_mike_removes_stale_unversioned_redirects(tmp_path):repository = make_repository(tmp_path)