Skip to content

armgit / dspy

Public Imported from GitHub
0

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.yml
deleted file mode 100644
index 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-docs
diff --git a/.github/workflows/docs-push.yml b/.github/workflows/docs-push.yml
index 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-latest
concurrency:
group: dspy-docs-deployment
cancel-in-progress: false
diff --git a/docs/scripts/bootstrap_versioned_docs.py b/docs/scripts/bootstrap_versioned_docs.py
deleted file mode 100644
index 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.md
index 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. Prereleases
do not claim the stable minor alias. Minor aliases are navigation conveniences
and are hidden from the picker. Mike owns `versions.json`, the
default 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 release
snapshots 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 root
redirect pages such as `/api/` → `/current/api/`, and each build scopes
diff --git a/docs/versioning/releases.json b/docs/versioning/releases.json
deleted file mode 100644
index 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.py
index 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_mike
def test_mike_removes_stale_unversioned_redirects(tmp_path):
repository = make_repository(tmp_path)