Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

docs: automate Current and release snapshots (#10317)

Isaac Miller208e751f571d
diff --git a/.github/workflows/build_and_release.yml b/.github/workflows/build_and_release.yml
index 52b1e30e3..e8a82f91f 100644
--- a/.github/workflows/build_and_release.yml
+++ b/.github/workflows/build_and_release.yml
@@ -134,6 +134,12 @@ jobs:
(cd "$RUNNER_TEMP" && python -c 'import dspy; assert dspy.PythonInterpreter().execute("6 * 7") == 42')
deactivate
rm -r test_before_pypi
+ - name: Preserve the exact release wheel for documentation
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+ with:
+ name: dspy-release-wheel
+ path: dist/*.whl
+ if-no-files-found: error
- name: Publish distribution 📦 to PyPI (dspy)
uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
with:
@@ -158,6 +164,112 @@ jobs:
with:
attestations: false
packages-dir: .github/.internal_dspyai/dist/
+
+ release-docs:
+ needs: [extract-tag, build-and-publish-pypi]
+ if: github.repository_owner == 'stanfordnlp'
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ persist-credentials: false
+ fetch-depth: 0
+ - name: Check whether this is a documentation release
+ id: publishable
+ env:
+ VERSION: ${{ needs.extract-tag.outputs.version }}
+ run: |
+ if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]] && (( ${VERSION%%.*} >= 3 )); then
+ echo "publish=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "publish=false" >> "$GITHUB_OUTPUT"
+ fi
+ - name: Set up Python 3.11
+ if: steps.publishable.outputs.publish == 'true'
+ uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+ with:
+ python-version: "3.11"
+ - name: Download exact production wheel
+ if: steps.publishable.outputs.publish == 'true'
+ uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+ with:
+ name: dspy-release-wheel
+ path: release-wheel
+ - name: Install documentation dependencies and release wheel
+ if: steps.publishable.outputs.publish == 'true'
+ run: python -m pip install -r docs/requirements.txt release-wheel/*.whl
+ - name: Verify API introspection uses the release wheel
+ if: steps.publishable.outputs.publish == 'true'
+ run: |
+ cd "$RUNNER_TEMP"
+ env -u PYTHONPATH PYTHONSAFEPATH=1 python -P - <<'PY'
+ import site
+ from pathlib import Path
+
+ import dspy
+
+ module = Path(dspy.__file__).resolve()
+ site_packages = [Path(root).resolve() for root in site.getsitepackages()]
+ if not any(module.is_relative_to(root) for root in site_packages):
+ raise SystemExit(f"DSPy resolved outside site-packages: {module}")
+ print(f"DSPy API source: {module}")
+ PY
+ - name: Build immutable release documentation
+ if: steps.publishable.outputs.publish == 'true'
+ env:
+ VERSION: ${{ needs.extract-tag.outputs.version }}
+ run: |
+ cd "$RUNNER_TEMP"
+ env PYTHONPATH="$GITHUB_WORKSPACE/docs/scripts" PYTHONSAFEPATH=1 python -P \
+ "$GITHUB_WORKSPACE/docs/scripts/build_docs.py" release \
+ --config "$GITHUB_WORKSPACE/docs/mkdocs.yml" \
+ --output "$GITHUB_WORKSPACE/release-site" \
+ --version "$VERSION" \
+ --artifact "$GITHUB_WORKSPACE"/release-wheel/*.whl \
+ --package-source workflow-wheel
+ - name: Check out documentation deployment
+ if: steps.publishable.outputs.publish == 'true'
+ 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: Publish immutable release documentation
+ if: steps.publishable.outputs.publish == 'true'
+ env:
+ GH_TOKEN: ${{ secrets.GH_PAT }}
+ VERSION: ${{ needs.extract-tag.outputs.version }}
+ run: |
+ gh auth setup-git
+ git -C docs-deployment config user.name github-actions
+ git -C docs-deployment config user.email [email protected]
+ aliases=()
+ if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ aliases=(--alias "${VERSION%.*}")
+ fi
+ for attempt in 1 2 3; do
+ git -C docs-deployment fetch origin master
+ git -C docs-deployment reset --hard origin/master
+ python docs/scripts/publish_versioned_docs.py \
+ --repository docs-deployment \
+ --site release-site \
+ --identifier "$VERSION" \
+ "${aliases[@]}" \
+ --package-source workflow-wheel \
+ --branch master \
+ --require-current-renderer zensical
+ if git -C docs-deployment push origin master; then
+ exit 0
+ fi
+ sleep $((2 ** attempt + RANDOM % 5))
+ done
+ echo "::error::Documentation deployment changed repeatedly; rerun this release job"
+ exit 1
+
open-main-version-bump-pr:
needs: [extract-tag, build-and-publish-pypi]
if: github.repository_owner == 'stanfordnlp'
diff --git a/.github/workflows/docs-push.yml b/.github/workflows/docs-push.yml
index ff6420ef0..61c239845 100644
--- a/.github/workflows/docs-push.yml
+++ b/.github/workflows/docs-push.yml
@@ -155,10 +155,20 @@ jobs:
gh auth setup-git
git -C docs-deployment config user.name github-actions
git -C docs-deployment config user.email [email protected]
- python docs/scripts/publish_versioned_docs.py \
- --repository docs-deployment \
- --site current-site \
- --identifier current \
- --package-source working-tree \
- --branch master
- git -C docs-deployment push origin master
+ for attempt in 1 2 3; do
+ git -C docs-deployment fetch origin master
+ git -C docs-deployment reset --hard origin/master
+ python docs/scripts/publish_versioned_docs.py \
+ --repository docs-deployment \
+ --site current-site \
+ --identifier current \
+ --package-source working-tree \
+ --branch master \
+ --require-current-renderer zensical
+ if git -C docs-deployment push origin master; then
+ exit 0
+ fi
+ sleep $((2 ** attempt + RANDOM % 5))
+ done
+ echo "::error::Documentation deployment changed repeatedly; rerun this workflow"
+ exit 1
diff --git a/docs/scripts/build_docs.py b/docs/scripts/build_docs.py
index 65434875a..fd527958b 100644
--- a/docs/scripts/build_docs.py
+++ b/docs/scripts/build_docs.py
@@ -15,9 +15,9 @@ import tempfile
from pathlib import Path
if __package__:
- from .zensical_build import build_zensical_site
+ from .zensical_build import HeadParser, build_zensical_site
else: # Direct script execution from the deployed docs repository.
- from zensical_build import build_zensical_site
+ from zensical_build import HeadParser, build_zensical_site
RELEASE_VERSION = re.compile(
@@ -166,8 +166,10 @@ def validate_release_site(site: Path, config: Path, version: str) -> None:
raise RuntimeError(f"release site is missing required output: {', '.join(missing)}")
home = (site / "index.html").read_text()
- canonical = f'<link rel="canonical" href="https://dspy.ai/{version}/">'
- if canonical not in home:
+ metadata = HeadParser()
+ metadata.feed(home)
+ canonical = f"https://dspy.ai/{version}/"
+ if metadata.metadata.get("canonical") != canonical:
raise RuntimeError(f"release home page is missing canonical URL {canonical}")
docs_dir = config.parent / "docs"
@@ -184,7 +186,7 @@ def validate_release_site(site: Path, config: Path, version: str) -> None:
raise RuntimeError(f"notebooks were not rendered: {', '.join(missing_notebooks)}")
cards = site / "assets" / "images" / "social-zensical"
- if not cards.exists() or not any(cards.rglob("*.png")) or 'property="og:image"' not in home:
+ if not cards.exists() or not any(cards.rglob("*.png")) or "og:image" not in metadata.metadata:
raise RuntimeError("social cards or Open Graph metadata were not generated")
try:
diff --git a/docs/scripts/publish_versioned_docs.py b/docs/scripts/publish_versioned_docs.py
index 036bbd7f6..384127b4e 100644
--- a/docs/scripts/publish_versioned_docs.py
+++ b/docs/scripts/publish_versioned_docs.py
@@ -14,6 +14,7 @@ from html import escape
from pathlib import Path
RELEASE_VERSION = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:(a|b|rc)(\d+))?$")
+STABLE_VERSION = re.compile(r"^\d+\.\d+\.\d+$")
DEFAULT_BRANCH = "versioned-docs"
LEGACY_REDIRECTS_MANIFEST = ".dspy-legacy-redirects.json"
HOST_CONFIG = (
@@ -68,7 +69,11 @@ def working_directory(path: Path):
def tree_digest(root: Path) -> str:
digest = hashlib.sha256()
- for path in sorted(item for item in root.rglob("*") if item.is_file()):
+ paths = sorted(
+ (item for item in root.rglob("*") if item.is_file()),
+ key=lambda item: item.relative_to(root).as_posix(),
+ )
+ for path in paths:
digest.update(path.relative_to(root).as_posix().encode())
digest.update(path.read_bytes())
return digest.hexdigest()
@@ -102,6 +107,31 @@ def branch_file(repository: Path, branch: str, path: str) -> str | None:
return result.stdout if result.returncode == 0 else None
+def require_current_renderer(repository: Path, branch: str, renderer: str) -> None:
+ inventory_text = branch_file(repository, branch, "versions.json")
+ inventory = json.loads(inventory_text) if inventory_text else []
+ current = next((entry for entry in inventory if entry.get("version") == "current"), None)
+ actual = current.get("properties", {}).get("renderer") if current else None
+ if actual != renderer:
+ raise RuntimeError(f"production Current renderer is {actual!r}, expected {renderer!r}")
+
+
+def monotonic_aliases(repository: Path, branch: str, identifier: str, aliases: list[str]) -> list[str]:
+ """Do not let a delayed older patch move a minor alias backward."""
+ inventory_text = branch_file(repository, branch, "versions.json")
+ if not inventory_text:
+ return aliases
+ requested = version_tuple(identifier)
+ inventory = json.loads(inventory_text)
+ holders = {
+ alias: version_tuple(entry["version"])
+ for entry in inventory
+ if STABLE_VERSION.fullmatch(entry["version"])
+ for alias in entry.get("aliases", [])
+ }
+ return [alias for alias in aliases if alias not in holders or holders[alias] <= requested]
+
+
def redirect_document(target: str) -> str:
encoded = json.dumps(target)
escaped = escape(target, quote=True)
@@ -159,14 +189,18 @@ def publish_site(
aliases: list[str],
package_source: str,
branch: str = DEFAULT_BRANCH,
+ required_current_renderer: str | None = None,
) -> bool:
from mike import commands, git_utils
+ if required_current_renderer:
+ require_current_renderer(repository, branch, required_current_renderer)
current = identifier == "current"
if not current:
# Automated publication is append-only. Intentional corrections to an
# existing snapshot go through review in the deployment repository.
version_tuple(identifier)
+ aliases = monotonic_aliases(repository, branch, identifier, aliases)
deployed = deployed_tree_digest(repository, branch, identifier)
if deployed:
if deployed != tree_digest(site):
@@ -215,6 +249,7 @@ def main() -> None:
required=True,
)
parser.add_argument("--branch", default=DEFAULT_BRANCH)
+ parser.add_argument("--require-current-renderer")
args = parser.parse_args()
changed = publish_site(
repository=args.repository.resolve(),
@@ -223,6 +258,7 @@ def main() -> None:
aliases=args.alias,
package_source=args.package_source,
branch=args.branch,
+ required_current_renderer=args.require_current_renderer,
)
print("published" if changed else "already published")
diff --git a/docs/versioning/README.md b/docs/versioning/README.md
index 82fa5c1b6..27374d97b 100644
--- a/docs/versioning/README.md
+++ b/docs/versioning/README.md
@@ -5,8 +5,8 @@ DSPy's versioned documentation is one static site managed by
- `/` redirects to `/current/`.
- `/current/` is the mutable documentation built from `main`.
-- `/X.Y.Z/` and `/X.Y.ZbN/` are release snapshots built from their tags while importing the
- exact released DSPy wheel.
+- `/X.Y.Z/` and prerelease paths such as `/X.Y.ZbN/` are snapshots built from
+ their tags while importing the exact released DSPy wheel.
- `/X.Y/` redirects to the newest imported patch in that minor line.
The picker lists Current and every stable or prerelease snapshot. Prereleases
@@ -34,6 +34,26 @@ redirect pages such as `/api/` → `/current/api/`, and each build scopes
hand-authored root-relative links to its own version so an old page cannot
silently jump into Current. Query strings and fragments survive redirects.
+## Production publication
+
+Current publication follows the renderer state described above. Release
+publication fails closed unless production's Mike metadata identifies Zensical
+as the reviewed Current renderer.
+
+After a stable or prerelease `dspy` wheel reaches PyPI, the release workflow
+preserves that exact wheel, builds its versioned path from the tag, and
+publishes it through Mike after the existing package release job succeeds.
+Only stable releases advance `/X.Y/`. Release-tag jobs never use GitHub's lossy
+pending-concurrency slot. Mutable Current keeps latest-wins serialization
+because a newer `main` build includes the superseded commit. Deployment writes
+retry optimistic Git pushes; every release rechecks the Zensical promotion
+marker after refetching, and a delayed older patch cannot move an `/X.Y/` alias
+backward.
+
+Corrections and rollbacks use reviewed pull requests in the deployment
+repository. Restore a known-good tree with a new commit rather than rewriting
+production history.
+
## Historical fidelity
Versions 3.0 through 3.3 use the documentation source and Material
diff --git a/tests/docs/test_versioned_docs.py b/tests/docs/test_versioned_docs.py
index 4fabd151f..3c73c42db 100644
--- a/tests/docs/test_versioned_docs.py
+++ b/tests/docs/test_versioned_docs.py
@@ -13,8 +13,9 @@ from docs.scripts.build_docs import (
remove_source_maps,
scope_root_relative_urls,
set_release_badge_version,
+ validate_release_site,
)
-from docs.scripts.publish_versioned_docs import publish_site, version_tuple
+from docs.scripts.publish_versioned_docs import publish_site, require_current_renderer, version_tuple
requires_mike = pytest.mark.skipif(importlib.util.find_spec("mike") is None, reason="Mike is a docs-only dependency")
@@ -85,6 +86,27 @@ def test_release_config_enables_mike_and_scopes_urls(tmp_path):
result.unlink()
+def test_release_validation_accepts_zensical_minified_metadata(tmp_path, monkeypatch):
+ site = tmp_path / "site"
+ (site / "api").mkdir(parents=True)
+ (site / "assets" / "images" / "social-zensical").mkdir(parents=True)
+ (site / "index.html").write_text(
+ "<html><head>"
+ "<link rel=canonical href=https://dspy.ai/3.4.0b1/>"
+ "<meta property=og:image content=https://dspy.ai/card.png>"
+ "</head></html>"
+ )
+ (site / "api" / "index.html").write_text("API")
+ (site / "search.json").write_text("{}")
+ (site / "llms.txt").write_text("DSPy")
+ (site / "assets" / "images" / "social-zensical" / "card.png").write_bytes(b"png")
+ config = tmp_path / "mkdocs.yml"
+ config.write_text("site_name: DSPy\n")
+ monkeypatch.setattr("docs.scripts.build_docs.importlib.metadata.version", lambda package: "3.4.0b1")
+
+ validate_release_site(site, config, "3.4.0b1")
+
+
def test_production_build_removes_source_maps(tmp_path):
site = tmp_path / "site"
assets = site / "assets"
@@ -184,10 +206,36 @@ def test_mike_preserves_patches_and_moves_minor_redirect(tmp_path):
assert inventory[1]["aliases"] == []
+@requires_mike
+def test_delayed_older_patch_does_not_move_minor_redirect_backward(tmp_path):
+ repository = make_repository(tmp_path)
+ newest = make_site(tmp_path / "newest", "3.0.1")
+ delayed = make_site(tmp_path / "delayed", "3.0.0")
+
+ for version, site in (("3.0.1", newest), ("3.0.0", delayed)):
+ publish_site(
+ repository=repository,
+ site=site,
+ identifier=version,
+ aliases=["3.0"],
+ package_source="workflow-wheel",
+ )
+
+ alias = branch_file(repository, "versioned-docs", "3.0/guide/index.html")
+ assert "../../3.0.1/guide/" in alias
+ inventory = json.loads(branch_file(repository, "versioned-docs", "versions.json"))
+ aliases = {entry["version"]: entry["aliases"] for entry in inventory}
+ assert aliases == {"3.0.0": [], "3.0.1": ["3.0"]}
+
+
@requires_mike
def test_mike_refuses_to_replace_an_immutable_snapshot(tmp_path):
repository = make_repository(tmp_path)
site = make_site(tmp_path / "first", "original")
+ for path in ("diving-deeper/tools", "diving-deeper/tools-react-and-mcp"):
+ page = site / path
+ page.mkdir(parents=True)
+ (page / "index.html").write_text(path)
arguments = {
"repository": repository,
"site": site,
@@ -243,6 +291,9 @@ def test_mike_current_is_mutable_and_default(tmp_path):
["git", "cat-file", "-e", "master:versions.json"], cwd=repository, capture_output=True
)
assert production_inventory.returncode != 0
+ require_current_renderer(repository, "versioned-docs", "zensical")
+ with pytest.raises(RuntimeError, match="expected 'material'"):
+ require_current_renderer(repository, "versioned-docs", "material")
@requires_mike