Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 175 additions & 0 deletions .github/scripts/test_version_policy.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
"""Unit tests for version_policy.py (run: python -m pytest -q .github/scripts)."""

from __future__ import annotations

import subprocess
import sys
from pathlib import Path

import pytest
from packaging.version import Version

sys.path.insert(0, str(Path(__file__).resolve().parent))

import version_policy as vp # noqa: E402


def descriptor(version: str) -> str:
return f"slug: bifrost-docs\nname: Bifrost Docs\nversion: {version}\n"


@pytest.mark.parametrize(
"path",
[
"README.md",
"SECURITY.md",
"docs/CUTOVER_RUNBOOK.md",
"docs/DESIGN_SYSTEM_PROVENANCE.json",
"tests/test_folders.py",
".github/workflows/ci.yml",
".github/scripts/version_policy.py",
"apps/bifrost-docs/README.md",
"apps/bifrost-docs/src/app.test.tsx",
"apps/bifrost-docs/src/lib/deep/thing.test.ts",
"apps/bifrost-docs/scripts/browser-qa.cjs",
],
)
def test_non_deployable_paths(path: str) -> None:
assert not vp.is_deployable(path)


@pytest.mark.parametrize(
"path",
[
"bifrost.solution.yaml",
"requirements.txt",
".bifrost/tables.yaml",
"functions/docs_search.py",
"modules/indexing.py",
"apps/bifrost-docs/package.json",
"apps/bifrost-docs/package-lock.json",
"apps/bifrost-docs/src/app.tsx",
"apps/bifrost-docs/src/test-utils.ts",
"apps/bifrost-docs/vite.config.ts",
"tests.py",
"docsite/index.html",
"LICENSE",
],
)
def test_deployable_paths(path: str) -> None:
assert vp.is_deployable(path)


@pytest.mark.parametrize(
("base", "expected"),
[
("0.1.3", "0.1.3+mtg.1"),
("0.1.3+mtg.1", "0.1.3+mtg.2"),
("0.1.3+mtg.9", "0.1.3+mtg.10"),
("0.1.4", "0.1.4+mtg.1"),
],
)
def test_suggest_next(base: str, expected: str) -> None:
suggestion = vp.suggest_next(Version(base))
assert suggestion == expected
assert Version(suggestion) > Version(base)


def test_pep440_ordering_matches_release_flow() -> None:
assert Version("0.1.3") < Version("0.1.3+mtg.1") < Version("0.1.3+mtg.2") < Version("0.1.4")


def test_non_deployable_change_needs_no_bump() -> None:
ok, message = vp.evaluate(
["README.md", ".github/workflows/ci.yml", "tests/test_x.py"],
descriptor("0.1.3"),
descriptor("0.1.3"),
)
assert ok, message


def test_deployable_change_without_bump_fails_with_suggestion() -> None:
ok, message = vp.evaluate(
["functions/docs_search.py", "README.md"],
descriptor("0.1.3+mtg.1"),
descriptor("0.1.3+mtg.1"),
)
assert not ok
assert "0.1.3+mtg.2" in message
assert "functions/docs_search.py" in message
assert "README.md" not in message


def test_deployable_change_with_downgrade_fails() -> None:
ok, _ = vp.evaluate(["modules/x.py"], descriptor("0.1.3+mtg.2"), descriptor("0.1.3+mtg.1"))
assert not ok


@pytest.mark.parametrize("head", ["0.1.3+mtg.1", "0.1.4", "0.2.0"])
def test_deployable_change_with_bump_passes(head: str) -> None:
ok, message = vp.evaluate(["modules/x.py"], descriptor("0.1.3"), descriptor(head))
assert ok, message


def test_invalid_head_version_fails() -> None:
ok, message = vp.evaluate(["modules/x.py"], descriptor("0.1.3"), descriptor("next"))
assert not ok
assert "PEP 440" in message
assert "0.1.3+mtg.1" in message


def _git(repo: Path, *args: str) -> str:
return subprocess.run(
["git", "-C", str(repo), *args], check=True, capture_output=True, text=True
).stdout.strip()


@pytest.fixture
def repo(tmp_path: Path) -> Path:
_git(tmp_path, "init", "-q", "-b", "mtg")
_git(tmp_path, "config", "user.email", "ci@example.invalid")
_git(tmp_path, "config", "user.name", "CI")
_git(tmp_path, "config", "commit.gpgsign", "false")
(tmp_path / "bifrost.solution.yaml").write_text(descriptor("0.1.3"))
(tmp_path / "modules").mkdir()
(tmp_path / "modules/x.py").write_text("x = 1\n")
_git(tmp_path, "add", ".")
_git(tmp_path, "commit", "-q", "-m", "base")
_git(tmp_path, "checkout", "-q", "-b", "feature")
return tmp_path


def _commit(repo: Path, path: str, text: str) -> str:
(repo / path).parent.mkdir(parents=True, exist_ok=True)
(repo / path).write_text(text)
_git(repo, "add", path)
_git(repo, "commit", "-q", "-m", f"change {path}")
return _git(repo, "rev-parse", "HEAD")


def _run(repo: Path, monkeypatch: pytest.MonkeyPatch, base: str, head: str) -> int:
monkeypatch.chdir(repo)
return vp.main(["--base", base, "--head", head])


def test_main_end_to_end(repo: Path, monkeypatch: pytest.MonkeyPatch) -> None:
base = _git(repo, "rev-parse", "mtg")
head = _commit(repo, "docs/NOTES.md", "notes\n")
assert _run(repo, monkeypatch, base, head) == 0

head = _commit(repo, "modules/x.py", "x = 2\n")
assert _run(repo, monkeypatch, base, head) == 1

head = _commit(repo, "bifrost.solution.yaml", descriptor("0.1.3+mtg.1"))
assert _run(repo, monkeypatch, base, head) == 0


def test_main_ignores_changes_that_landed_on_base(
repo: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
head = _commit(repo, "tests/test_y.py", "def test_y(): pass\n")
_git(repo, "checkout", "-q", "mtg")
base = _commit(repo, "modules/x.py", "x = 3\n")
_git(repo, "checkout", "-q", "feature")
# The base moved on with a deployable change; the PR itself only touches tests.
assert _run(repo, monkeypatch, base, head) == 0
159 changes: 159 additions & 0 deletions .github/scripts/version_policy.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
#!/usr/bin/env python3
"""Require a Solution version bump for deployable changes merged into ``mtg``.

Bifrost polls ``version:`` in ``bifrost.solution.yaml`` on the followed branch
and only offers an update when it increases (compared with ``packaging``). A
deployable change merged without a bump would never reach installs.

Usage (from a full-history checkout)::

python .github/scripts/version_policy.py --base <base-sha> --head <head-sha>

Exit codes: 0 = policy satisfied, 1 = version bump missing or invalid.
"""

from __future__ import annotations

import argparse
import re
import subprocess
import sys
from collections.abc import Iterable, Sequence

import yaml
from packaging.version import InvalidVersion, Version

DESCRIPTOR = "bifrost.solution.yaml"
LOCAL_LABEL = "mtg"

# Paths that never change what an install runs. Everything else is deployable.
NON_DEPLOYABLE_PATTERNS: tuple[str, ...] = (
"docs/**",
"**/*.md",
"tests/**",
".github/**",
"apps/*/src/**/*.test.*",
"apps/*/scripts/**",
)


def _glob_to_regex(pattern: str) -> re.Pattern[str]:
"""Translate a path glob: ``*`` stays within a segment, ``**/`` spans any depth."""
out: list[str] = []
i = 0
while i < len(pattern):
if pattern.startswith("**/", i):
out.append("(?:.*/)?")
i += 3
elif pattern.startswith("**", i):
out.append(".*")
i += 2
elif pattern[i] == "*":
out.append("[^/]*")
i += 1
elif pattern[i] == "?":
out.append("[^/]")
i += 1
else:
out.append(re.escape(pattern[i]))
i += 1
return re.compile("".join(out) + r"\Z")


_NON_DEPLOYABLE = tuple(_glob_to_regex(p) for p in NON_DEPLOYABLE_PATTERNS)


def is_deployable(path: str) -> bool:
return not any(rx.match(path) for rx in _NON_DEPLOYABLE)


def deployable_paths(paths: Iterable[str]) -> list[str]:
return sorted({p for p in paths if p and is_deployable(p)})


def parse_descriptor_version(text: str | None) -> Version | None:
"""Return the descriptor's version, or None when the file is absent."""
if text is None:
return None
data = yaml.safe_load(text) or {}
raw = data.get("version")
if raw is None:
raise ValueError(f"{DESCRIPTOR} has no `version:` field")
try:
return Version(str(raw))
except InvalidVersion as exc:
raise ValueError(f"{DESCRIPTOR} version {raw!r} is not a valid PEP 440 version") from exc


def suggest_next(base: Version | None, label: str = LOCAL_LABEL) -> str:
"""Next ``<public>+<label>.N`` version after ``base``."""
if base is None:
return f"0.1.0+{label}.1"
match = re.fullmatch(rf"{re.escape(label)}\.(\d+)", base.local or "")
n = int(match.group(1)) + 1 if match else 1
return f"{base.public}+{label}.{n}"


def evaluate(
changed: Iterable[str], base_text: str | None, head_text: str | None
) -> tuple[bool, str]:
"""Return (ok, message) for a PR's changed paths and descriptor contents."""
deployable = deployable_paths(changed)
if not deployable:
return True, "No deployable paths changed; no version bump required."

listing = "\n".join(f" - {p}" for p in deployable)
try:
base = parse_descriptor_version(base_text)
except ValueError as exc:
base = None
print(f"warning: ignoring unreadable base descriptor: {exc}", file=sys.stderr)
suggestion = suggest_next(base)
try:
head = parse_descriptor_version(head_text)
except ValueError as exc:
return False, f"{exc}.\nSuggested version: {suggestion}\nDeployable changes:\n{listing}"
if head is None:
return False, f"{DESCRIPTOR} is missing on the head branch.\nDeployable changes:\n{listing}"

if base is None or head > base:
return True, f"Version bumped: {base} -> {head}. Deployable changes:\n{listing}"
return False, (
f"This PR changes deployable paths but {DESCRIPTOR} version is {head}, which is "
f"not greater than the base version {base}.\n"
f"Bump `version:` in {DESCRIPTOR} to {suggestion} "
f"(or a newer upstream release) so Bifrost installs following this branch see the update.\n"
f"Deployable changes:\n{listing}"
)


def _git(*args: str) -> str:
return subprocess.run(["git", *args], check=True, capture_output=True, text=True).stdout


def _show(rev: str, path: str) -> str | None:
result = subprocess.run(
["git", "show", f"{rev}:{path}"], capture_output=True, text=True
)
return result.stdout if result.returncode == 0 else None


def main(argv: Sequence[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--base", required=True, help="PR base commit (the target branch tip)")
parser.add_argument("--head", required=True, help="PR head commit")
args = parser.parse_args(argv)

# Three-dot diff: only what the PR introduces since it forked from the base.
changed = _git("diff", "--name-only", "--no-renames", f"{args.base}...{args.head}").splitlines()
ok, message = evaluate(changed, _show(args.base, DESCRIPTOR), _show(args.head, DESCRIPTOR))
if ok:
print(message)
return 0
print(f"::error file={DESCRIPTOR},title=Version bump required::{message.splitlines()[0]}")
print(message)
return 1


if __name__ == "__main__":
sys.exit(main())
Loading
Loading