From 30cc00c46ffd2d5e0a436ef32669751312c488b4 Mon Sep 17 00:00:00 2001 From: Matt Metcalf Date: Mon, 9 Nov 2026 15:30:42 -0800 Subject: [PATCH] Updating Documentation release stratagy --- .github/workflows/docs.yml | 74 +++++++++++ .gitignore | 1 + README.md | 39 ++++++ docs/_sphinx/conf.py | 39 ++++++ docs/requirements.txt | 5 + project-words.txt | 14 +++ scripts/build_release_docs.py | 227 ++++++++++++++++++++++++++++++++++ tests/test_release_docs.py | 144 +++++++++++++++++++++ 8 files changed, 543 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/_sphinx/conf.py create mode 100644 docs/requirements.txt create mode 100644 scripts/build_release_docs.py create mode 100644 tests/test_release_docs.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e71fba5 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,74 @@ +name: Release documentation + +on: + pull_request: + paths: + - ".github/workflows/docs.yml" + - "docs/**" + - "scripts/build_release_docs.py" + - "tests/test_release_docs.py" + push: + branches: [main] + paths: + - ".github/workflows/docs.yml" + - "docs/**" + - "scripts/build_release_docs.py" + - "tests/test_release_docs.py" + workflow_dispatch: + inputs: + deploy: + description: "Deploy the validated release site after Pages settings are ready" + type: boolean + default: false + +permissions: + contents: read + +env: + RELEASE_TAG: v2.2.0 + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Check out documentation tooling + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Check out the released source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: refs/tags/${{ env.RELEASE_TAG }} + path: .docs-release + persist-credentials: false + - name: Set up Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Install documentation dependencies and the released package + run: python -m pip install -r docs/requirements.txt ./.docs-release + - name: Build and validate the versioned site + run: python scripts/build_release_docs.py --source .docs-release --tag "$RELEASE_TAG" + - name: Upload the preview and deployment artifact + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: docs/_build/site + retention-days: 7 + + deploy: + if: github.event_name == 'workflow_dispatch' && inputs.deploy && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + concurrency: + group: release-documentation-pages + cancel-in-progress: false + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy the versioned site + id: deployment + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 diff --git a/.gitignore b/.gitignore index 190177c..4bd08f8 100644 --- a/.gitignore +++ b/.gitignore @@ -406,6 +406,7 @@ build/ dist/* # Sphinx +.docs-release/ docs/_build/ docs/_static docs/_templates diff --git a/README.md b/README.md index 48cdaba..1797b10 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,45 @@ Feature management provides a way to develop and expose application functionalit ## Contributing +### Release documentation + +The [release documentation workflow](https://github.com/microsoft/FeatureManagement-Python/actions/workflows/docs.yml) +builds the verified `v2.2.0` source, not the current `main` API. +The initial release is selected once through the workflow's `RELEASE_TAG` setting. +The builder resolves that tag's commit, derives its version, and checks that the imported package version agrees; +it contains no release-specific version or commit constants. +Pull requests and relevant changes merged into `main` build and validate the site without deploying it. +The downloadable `github-pages` artifact contains the complete site, including `/2.2.0/`, `/latest/`, +and redirects for existing `/html/` links. + +To build locally on Windows, use a separate release checkout and virtual environment: + +```powershell +git worktree add --detach ..\FeatureManagement-Python-2.2.0 v2.2.0 +py -3.14 -m venv ..\FeatureManagement-Python-2.2.0\.venv +& ..\FeatureManagement-Python-2.2.0\.venv\Scripts\Activate.ps1 +python -m pip install -r docs\requirements.txt ..\FeatureManagement-Python-2.2.0 +python scripts\build_release_docs.py --source ..\FeatureManagement-Python-2.2.0 --tag v2.2.0 +Start-Process docs\_build\site\index.html +``` + +Reuse an existing clean release checkout instead of adding it again. +The builder rejects the wrong commit or tracked release edits, validates local links and API anchors, +and replaces the local site only after a successful build. Generated pages are not committed. +Required API anchors come from methods declared by the tagged feature managers, not a version-independent API list. +Only stable release tags can become `/latest/`; prerelease and development tags are rejected. +Rendering fixes apply only during the build; the historical library source remains unchanged. +SDK documentation follows the [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html). + +Deployment is opt-in. After merging this workflow and configuring Pages to use **GitHub Actions**, allow `main` +in the `github-pages` environment. Run **Release documentation** manually from `main` and enable its `deploy` input. +No new secret is required, and PR builds never receive Pages deployment permissions. +Keep `gh-pages` unchanged as a fallback; rollback consists of restoring its `/docs` folder as the Pages source +and allowing `gh-pages` in the deployment environment. + +The bootstrap site contains one configured release. Retaining multiple versions, validating older documentation +builds, and registration of future releases are separate follow-up work. + This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. diff --git a/docs/_sphinx/conf.py b/docs/_sphinx/conf.py new file mode 100644 index 0000000..88ced85 --- /dev/null +++ b/docs/_sphinx/conf.py @@ -0,0 +1,39 @@ +# ------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# ------------------------------------------------------------------------- +"""Shared rendering configuration for tagged release documentation.""" + +from typing import Any + +from sphinx.application import Sphinx + +project = "FeatureManagement" +copyright = "2024, Microsoft" +author = "Microsoft" +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx_toolbox.more_autodoc.autonamedtuple", + "sphinxcontrib.jquery", +] +html_theme = "sphinx_rtd_theme" +html_static_path: list[str] = [] +html_theme_path: list[str] = [] + + +def format_release_docstrings(_app: Sphinx, _what: str, name: str, _obj: Any, _options: Any, lines: list[str]) -> None: + """Indent historical keyword-field continuations without modifying release source.""" + if name not in ("featuremanagement.FeatureManager", "featuremanagement.aio.FeatureManager"): + return + for index, line in enumerate(lines): + if line in ("evaluated.", "context if one isn't provided."): + lines[index] = " " + line + + +def setup(app: Sphinx) -> dict[str, bool]: + """Register documentation-only rendering corrections.""" + app.connect("autodoc-process-docstring", format_release_docstrings) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..31c5210 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx==9.2.0 +sphinx_rtd_theme==3.1.0 +sphinx-toolbox==4.3.1 +myst_parser==5.1.0 +packaging==26.3 diff --git a/project-words.txt b/project-words.txt index c8285cc..e1c1da0 100644 --- a/project-words.txt +++ b/project-words.txt @@ -2,15 +2,29 @@ Aiden APPCONFIGURATION appinsights azuremonitor +buildername caplog Cass +confdir +confoverrides +devrelease +doctreedir +doctrees Entra featurefilters featureflag featuremanagement featuremanager featuremanagerbase +freshenv +gpgsign +outdir quickstart rtype +srcdir +statuscode usefixtures urandom +venv +warningiserror +worktree diff --git a/scripts/build_release_docs.py b/scripts/build_release_docs.py new file mode 100644 index 0000000..2372f31 --- /dev/null +++ b/scripts/build_release_docs.py @@ -0,0 +1,227 @@ +# ------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# ------------------------------------------------------------------------- +"""Build a versioned documentation site from a verified stable release tag.""" + +import argparse +from collections.abc import Sequence +from html import escape +from html.parser import HTMLParser +from importlib import import_module +import json +from pathlib import Path +import shutil +import subprocess +import sys +from tempfile import TemporaryDirectory +from urllib.parse import unquote, urlsplit + +from packaging.version import Version +from sphinx.application import Sphinx + +ROOT = Path(__file__).resolve().parents[1] +SITE = ROOT / "docs" / "_build" / "site" + + +class HTMLPage(HTMLParser): + """Collect the local references and anchors needed to validate a generated page.""" + + def __init__(self) -> None: + super().__init__() + self.references: list[str] = [] + self.anchors: set[str] = set() + self.title = "" + self._in_title = False + + def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: + attributes = dict(attrs) + anchor = attributes.get("id") + if anchor: + self.anchors.add(anchor) + for attribute in ("href", "src"): + reference = attributes.get(attribute) + if reference: + self.references.append(reference) + if tag == "title": + self._in_title = True + + def handle_endtag(self, tag: str) -> None: + if tag == "title": + self._in_title = False + + def handle_data(self, data: str) -> None: + if self._in_title: + self.title += data + + +def release_version(tag: str) -> str: + """Derive a stable package version from the selected release tag.""" + if not tag.startswith("v"): + raise ValueError(f"Expected a release tag named v, found {tag!r}") + version = Version(tag[1:]) + if version.is_prerelease or version.is_devrelease: + raise ValueError(f"Only stable releases can be published as latest: {tag}") + return str(version) + + +def verify_source(source: Path, tag: str) -> str: + """Resolve the selected tag and reject a different or modified checkout.""" + commit = subprocess.run( + ["git", "-C", str(source), "rev-parse", "HEAD"], capture_output=True, text=True, check=True + ).stdout.strip() + tagged = subprocess.run( + ["git", "-C", str(source), "rev-parse", "--verify", f"refs/tags/{tag}^{{commit}}"], + capture_output=True, + text=True, + check=False, + ) + if tagged.returncode: + raise ValueError(f"Cannot resolve release tag {tag!r}: {tagged.stderr.strip()}") + if commit != tagged.stdout.strip(): + raise ValueError(f"Checkout {commit} does not match release tag {tag} at {tagged.stdout.strip()}") + changes = subprocess.run( + ["git", "-C", str(source), "status", "--porcelain", "--untracked-files=no"], + capture_output=True, + text=True, + check=True, + ).stdout + if changes: + raise ValueError(f"The release checkout has tracked changes:\n{changes}") + return commit + + +def write_redirect(destination: Path, target: str) -> None: + """Generate a relative redirect that retains search queries and API anchors.""" + destination.parent.mkdir(parents=True, exist_ok=True) + attribute = escape(target, quote=True) + destination.write_text( + '\n\n' + "Redirecting to FeatureManagement documentation\n" + f'\n' + f'\n' + f"\n" + f'View the documentation.\n', + encoding="utf-8", + ) + + +def assemble_redirects(site: Path, version: str) -> None: + """Provide latest aliases and retain the previously published HTML page URLs.""" + pages = {page.name: page.name for page in (site / version).glob("*.html")} + # Some releases document the synchronous API on their index page. + pages.setdefault("featuremanagement.html", "index.html") + write_redirect(site / "index.html", f"./{version}/index.html") + for alias in ("latest", "html"): + for name, target in pages.items(): + write_redirect(site / alias / name, f"../{version}/{target}") + + +def validate_site(site: Path, version: str, required_anchors: Sequence[str]) -> None: + """Fail publication when generated pages have broken local links or anchors.""" + pages: dict[Path, HTMLPage] = {} + for path in site.rglob("*.html"): + page = HTMLPage() + page.feed(path.read_text(encoding="utf-8")) + pages[path.resolve()] = page + for path, page in pages.items(): + for reference in page.references: + url = urlsplit(reference) + if url.scheme or url.netloc: + continue + target = (path.parent / unquote(url.path)).resolve() if url.path else path + if target.is_dir(): + target /= "index.html" + if not target.is_relative_to(site.resolve()) or not target.is_file(): + raise ValueError(f"Broken local reference in {path}: {reference}") + if url.fragment and target in pages and unquote(url.fragment) not in pages[target].anchors: + raise ValueError(f"Broken anchor in {path}: {reference}") + release = (site / version).resolve() + if release / "index.html" not in pages: + raise ValueError(f"Missing documentation index for {version}") + anchors: set[str] = set() + for path, page in pages.items(): + if path.is_relative_to(release): + if version not in page.title: + raise ValueError(f"Wrong documentation version in {path.name}: {page.title}") + anchors.update(page.anchors) + for anchor in required_anchors: + if anchor not in anchors: + raise ValueError(f"Missing released API: {anchor}") + for alias in ("index.html", "latest/index.html", "html/index.html", "html/featuremanagement.html"): + if not (site / alias).is_file(): + raise ValueError(f"Missing compatibility redirect: {alias}") + + +def release_api_anchors() -> list[str]: + """Collect public API anchors from the imported release's feature managers.""" + anchors = [] + for module_name in ("featuremanagement", "featuremanagement.aio"): + manager = import_module(module_name).FeatureManager + anchors.append(f"{module_name}.FeatureManager") + for name, member in vars(manager).items(): + if not name.startswith("_") and callable(member): + anchors.append(f"{module_name}.FeatureManager.{name}") + return anchors + + +def build_site(source: Path, tag: str) -> Path: + """Render the tagged API and publish validated output to the ignored local build directory.""" + source = source.resolve() + version = release_version(tag) + commit = verify_source(source, tag) + sys.path.insert(0, str(source)) + package = import_module("featuremanagement") + package_file = package.__file__ + if package_file is None or not Path(package_file).resolve().is_relative_to(source): + raise ValueError("The documentation process did not import the verified release checkout") + if package.__version__ != version: + raise ValueError(f"Release tag {tag} does not match package version {package.__version__}") + required_anchors = release_api_anchors() + + with TemporaryDirectory(prefix="featuremanagement-docs-") as directory: + temporary = Path(directory) + documentation = temporary / "source" / "docs" + documentation.mkdir(parents=True) + shutil.copy2(source / "README.md", documentation.parent / "README.md") + for path in (source / "docs").glob("*.rst"): + shutil.copy2(path, documentation / path.name) + site = temporary / "site" + app = Sphinx( + srcdir=str(documentation), + confdir=str(ROOT / "docs" / "_sphinx"), + outdir=str(site / version), + doctreedir=str(temporary / "doctrees"), + buildername="html", + confoverrides={"release": version, "version": version}, + freshenv=True, + warningiserror=True, + ) + app.build(force_all=True) + if app.statuscode: + raise RuntimeError("The release documentation build failed; existing output was not replaced") + assemble_redirects(site, version) + (site / "release.json").write_text( + json.dumps({"version": version, "tag": tag, "commit": commit}, indent=2) + "\n", + encoding="utf-8", + ) + validate_site(site, version, required_anchors) + if SITE.exists(): + shutil.rmtree(SITE) + shutil.copytree(site, SITE) + print(f"Validated {tag} documentation: {SITE}") + return SITE + + +def main() -> None: + """Build the release checkout supplied by the workflow or a local Git worktree.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--source", type=Path, required=True, help="Clean checkout of the selected release tag") + parser.add_argument("--tag", required=True, help="Stable release tag to verify and document (v)") + arguments = parser.parse_args() + build_site(arguments.source, arguments.tag) + + +if __name__ == "__main__": + main() diff --git a/tests/test_release_docs.py b/tests/test_release_docs.py new file mode 100644 index 0000000..7f70781 --- /dev/null +++ b/tests/test_release_docs.py @@ -0,0 +1,144 @@ +# ------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# ------------------------------------------------------------------------- +"""Regression tests for tagged documentation identity, redirects, and link validation.""" + +from pathlib import Path +import subprocess + +import pytest + +from scripts.build_release_docs import assemble_redirects, release_version, validate_site, verify_source + + +def make_site(site: Path, version: str = "2.2.0", variants: bool = True) -> list[str]: + """Create a release site with only the API capabilities supplied by that release.""" + release = site / version + release.mkdir() + anchors = [] + for filename, module in ( + ("index.html", "featuremanagement"), + ("featuremanagement.aio.html", "featuremanagement.aio"), + ): + methods = ["is_enabled", "get_variant"] if variants else ["is_enabled"] + module_anchors = [f"{module}.FeatureManager"] + [f"{module}.FeatureManager.{method}" for method in methods] + anchors.extend(module_anchors) + (release / filename).write_text( + f"FeatureManagement {version}" + + "".join(f'' for anchor in module_anchors), + encoding="utf-8", + ) + assemble_redirects(site, version) + return anchors + + +def test_redirects_preserve_old_api_destinations(tmp_path: Path) -> None: + """Route legacy synchronous API URLs to their actual location in the tagged documentation.""" + anchors = make_site(tmp_path) + validate_site(tmp_path, "2.2.0", anchors) + redirect = (tmp_path / "html" / "featuremanagement.html").read_text(encoding="utf-8") + assert "../2.2.0/index.html" in redirect + assert "+ location.search + location.hash" in redirect + assert (tmp_path / "latest" / "featuremanagement.aio.html").is_file() + + +@pytest.mark.parametrize("reference", ["missing.js", "index.html#missing-anchor", "../../outside.html"]) +def test_validation_rejects_broken_references(tmp_path: Path, reference: str) -> None: + """Reject missing assets, broken API anchors, and references escaping the deployed site.""" + anchors = make_site(tmp_path) + page = tmp_path / "2.2.0" / "index.html" + page.write_text(page.read_text(encoding="utf-8") + f'broken', encoding="utf-8") + with pytest.raises(ValueError, match="Broken"): + validate_site(tmp_path, "2.2.0", anchors) + + +@pytest.fixture(name="tagged_source") +def tagged_source_fixture(tmp_path: Path) -> Path: + """Create a repository with an arbitrary release commit rather than a production-specific SHA.""" + subprocess.run(["git", "init", "--quiet", str(tmp_path)], check=True) + (tmp_path / "release.txt").write_text("released", encoding="utf-8") + subprocess.run(["git", "-C", str(tmp_path), "add", "release.txt"], check=True) + commit_source(tmp_path) + subprocess.run(["git", "-C", str(tmp_path), "tag", "v2.2.0"], check=True) + return tmp_path + + +def commit_source(source: Path) -> None: + """Create an isolated test commit without relying on the user's Git identity or signing setup.""" + subprocess.run( + [ + "git", + "-C", + str(source), + "-c", + "user.name=Documentation Test", + "-c", + "user.email=docs@example.invalid", + "-c", + "commit.gpgsign=false", + "commit", + "--quiet", + "--allow-empty", + "-m", + "Documentation test commit", + ], + check=True, + ) + + +def test_source_rejects_non_release_checkout(tagged_source: Path) -> None: + """Reject a newer checkout even when the requested release tag exists.""" + commit_source(tagged_source) + with pytest.raises(ValueError, match="does not match release tag"): + verify_source(tagged_source, "v2.2.0") + + +def test_source_resolves_selected_tag(tagged_source: Path) -> None: + """Accept another release tag without a builder-specific version or commit constant.""" + subprocess.run(["git", "-C", str(tagged_source), "tag", "v3.1.0"], check=True) + commit = subprocess.run( + ["git", "-C", str(tagged_source), "rev-parse", "HEAD"], capture_output=True, text=True, check=True + ).stdout.strip() + assert verify_source(tagged_source, "v3.1.0") == commit + + +def test_source_rejects_tracked_release_edits(tagged_source: Path) -> None: + """Do not document local modifications as though they belonged to an immutable tag.""" + (tagged_source / "release.txt").write_text("modified", encoding="utf-8") + with pytest.raises(ValueError, match="tracked changes"): + verify_source(tagged_source, "v2.2.0") + + +def test_source_rejects_missing_tag(tagged_source: Path) -> None: + """Report a missing release tag instead of accepting an otherwise clean checkout.""" + with pytest.raises(ValueError, match="Cannot resolve release tag"): + verify_source(tagged_source, "v9.0.0") + + +def test_legacy_redirect_preserves_existing_api_page(tmp_path: Path) -> None: + """Prefer a release's standalone synchronous API page when it exists.""" + make_site(tmp_path) + (tmp_path / "2.2.0" / "featuremanagement.html").write_text( + "FeatureManagement 2.2.0", encoding="utf-8" + ) + assemble_redirects(tmp_path, "2.2.0") + assert "../2.2.0/featuremanagement.html" in (tmp_path / "html" / "featuremanagement.html").read_text( + encoding="utf-8" + ) + + +def test_older_api_does_not_require_variants(tmp_path: Path) -> None: + """Validate older API capabilities without requiring methods introduced in later releases.""" + anchors = make_site(tmp_path, "1.0.0", variants=False) + validate_site(tmp_path, "1.0.0", anchors) + with pytest.raises(ValueError, match="Missing released API"): + validate_site(tmp_path, "1.0.0", anchors + ["featuremanagement.FeatureManager.get_variant"]) + + +@pytest.mark.parametrize("tag", ["main", "v2.0.0b1", "v2.3.0.dev1"]) +def test_latest_rejects_non_stable_release_tags(tag: str) -> None: + """Do not use a branch, prerelease, or development release as latest stable documentation.""" + with pytest.raises(ValueError): + release_version(tag)