Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(ci): require release selection for breaking changes (#6903)

LearningCircuit952a485843d0
diff --git a/.github/workflows/check-config-docs.yml b/.github/workflows/check-config-docs.yml
index b2dac01aac..50ceaf5d73 100644
--- a/.github/workflows/check-config-docs.yml
+++ b/.github/workflows/check-config-docs.yml
@@ -1,8 +1,8 @@
name: Check Configuration Docs
-# Manual-only check. Config docs are auto-regenerated by the version bump
-# workflow (version_check.yml) on every push to main, so a blocking PR
-# check is unnecessary and creates manual work for contributors.
+# Manual-only check. Config docs are auto-regenerated in every version bump
+# PR opened by version_check.yml, so a blocking PR check is unnecessary and
+# creates manual work for contributors.
on:
workflow_dispatch:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f5eea3db63..40f0c1132d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -354,6 +354,17 @@ jobs:
fi
echo "Version verified: $EXPECTED_VERSION"
+ # A merged stale patch/minor bump PR (or a hand-written bump) must not
+ # publish pending breaking changes under a compatible-looking version.
+ # Detection mirrors towncrier, so it sees every fragment the
+ # create-release job's "Render changelog from fragments" step would
+ # publish as breaking.
+ - name: Refuse a non-major release with pending breaking changes
+ if: steps.check_release.outputs.exists == 'false'
+ env:
+ RELEASE_VERSION: ${{ steps.version.outputs.version }}
+ run: python3 scripts/ci/check_breaking_release.py version "$RELEASE_VERSION"
+
- name: Download tested Python distributions
if: steps.check_release.outputs.exists == 'false'
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
diff --git a/.github/workflows/version_check.yml b/.github/workflows/version_check.yml
index 07eaea97e3..c49eb73ee4 100644
--- a/.github/workflows/version_check.yml
+++ b/.github/workflows/version_check.yml
@@ -9,7 +9,9 @@ name: Version Auto-Bump
# - Uses fixed branch name to avoid clutter
#
# Manual dispatch supports minor/major bumps via the Actions tab dropdown.
-# Auto-triggered runs (push to main) always bump patch.
+# Auto-triggered runs bump patch only when no breaking fragments are pending;
+# while they are pending, an open non-major bump PR is closed and only a
+# major version (N.0.0, or 0.N.0 before 1.0) can be proposed.
on:
push:
branches:
@@ -58,18 +60,67 @@ jobs:
- name: Determine release type
id: release
+ shell: bash
+ env:
+ EVENT_NAME: ${{ github.event_name }}
+ REQUESTED_TYPE: ${{ inputs.release_type }}
run: |
- if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
- release_type="${{ inputs.release_type }}"
+ if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+ release_type="$REQUESTED_TYPE"
else
release_type="patch"
fi
+ case "$release_type" in
+ patch|minor|major) ;;
+ *) echo "::error::Invalid release type"; exit 1 ;;
+ esac
+
+ # Detect breaking fragments the way towncrier renders them
+ # (dot-prefixed and counter-suffixed names included). A failure
+ # here aborts the step instead of reading as "none pending".
+ breaking=$(python3 scripts/ci/check_breaking_release.py pending)
+ if [ -n "$breaking" ]; then
+ if [ "$EVENT_NAME" != "workflow_dispatch" ]; then
+ echo "::notice::Breaking changes are pending. Run Version Auto-Bump manually and select major (minor only before 1.0) after reviewing the release scope."
+ echo "allowed=false" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ if [ "$release_type" = "patch" ]; then
+ echo "::error::Breaking changes cannot use a patch bump. Select major (minor only before 1.0) explicitly; see docs/RELEASE_GUIDE.md."
+ exit 1
+ fi
+ fi
+
+ echo "allowed=true" >> "$GITHUB_OUTPUT"
echo "type=$release_type" >> "$GITHUB_OUTPUT"
echo "Release type: $release_type"
+ # Breaking fragments are pending, so an open automatic patch/minor bump
+ # PR from an earlier run would publish them under a compatible-looking
+ # version if merged. Close it; a major bump PR is kept.
+ - name: Close stale non-major bump PR
+ if: steps.release.outputs.allowed == 'false'
+ shell: bash
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ GH_REPO: ${{ github.repository }}
+ run: |
+ stale="$RUNNER_TEMP/stale-bump-prs.tsv"
+ gh pr list --head chore/auto-version-bump --state open \
+ --json number,title,isCrossRepository \
+ --jq '.[] | select(.isCrossRepository | not) | "\(.number)\t\(.title)"' > "$stale"
+ while IFS=$'\t' read -r number title; do
+ version="${title##* version to }"
+ if python3 scripts/ci/check_breaking_release.py version "$version"; then
+ echo "PR #$number ($title) is a major bump; keeping it open."
+ continue
+ fi
+ gh pr close "$number" --comment "Closed by Version Auto-Bump: breaking changelog fragments are pending, so this non-major bump would publish them as $version. Run Version Auto-Bump manually and select major; see docs/RELEASE_GUIDE.md."
+ done < "$stale"
+
- name: Check if version was bumped in this push
id: check
- if: github.event_name != 'workflow_dispatch'
+ if: steps.release.outputs.allowed == 'true' && github.event_name != 'workflow_dispatch'
run: |
# Check if version changed in the commits being pushed
if git diff HEAD~1 -G"__version__" -- src/local_deep_research/__version__.py | grep -E '\+.*__version__.*='; then
@@ -81,24 +132,24 @@ jobs:
fi
- name: Set up Python
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.12'
- name: Set up PDM with pdm-bump plugin
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
uses: pdm-project/setup-pdm@544d7237314ee09c256785bd360f6b30add38b37 # v4.6
with:
python-version: '3.12'
- name: Install pdm-bump plugin
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
run: |
pdm self add pdm-bump
- name: Bump version
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
id: bump
run: |
release_type="${{ steps.release.outputs.type }}"
@@ -122,8 +173,17 @@ jobs:
mv package.json.tmp package.json
echo "Updated package.json version to $new_version"
+ # Same rule release.yml enforces before publishing: while breaking
+ # fragments are pending, only N.0.0 (or 0.N.0 before 1.0) may be
+ # proposed. Rejects a manual minor bump of a 1.x release.
+ - name: Refuse a non-major version for breaking changes
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
+ env:
+ NEW_VERSION: ${{ steps.bump.outputs.new_version }}
+ run: python scripts/ci/check_breaking_release.py version "$NEW_VERSION"
+
- name: Regenerate configuration docs
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
run: python scripts/generate_config_docs.py
# Refreshes docs/ci/workflow-status.md so the version-bump PR
@@ -136,7 +196,7 @@ jobs:
# 1000/hr workflow-runs limit). Needs `actions: read` on the
# job permissions block above.
- name: Regenerate workflow status dashboard
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
# Don't block the version bump if the dashboard refresh fails.
# The regen calls ~340 GitHub API endpoints; a transient outage
# or rate-limit hit would otherwise prevent the version-bump PR
@@ -150,7 +210,7 @@ jobs:
python scripts/generate_workflow_status.py
- name: Generate PR body
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
id: pr_body
run: |
release_type="${{ steps.release.outputs.type }}"
@@ -189,7 +249,7 @@ jobs:
# Use peter-evans/create-pull-request with GITHUB_TOKEN so the PR is created
# by github-actions[bot] - this allows the repo owner to approve the PR
- name: Create Pull Request
- if: steps.check.outputs.needs_bump != 'false'
+ if: steps.release.outputs.allowed == 'true' && steps.check.outputs.needs_bump != 'false'
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
with:
token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.pre-commit-hooks/_changelog_fragments.py b/.pre-commit-hooks/_changelog_fragments.py
index a26bd06c60..a76d8071da 100644
--- a/.pre-commit-hooks/_changelog_fragments.py
+++ b/.pre-commit-hooks/_changelog_fragments.py
@@ -5,8 +5,10 @@ Used by the blocking ``check-changelog-fragments`` hook and the advisory
list can't drift between them.
"""
+import os
import re
import tomllib
+from fnmatch import fnmatch
from pathlib import Path
# changelog.d/<id>.<category>[.<n>].md or changelog.d/+<slug>.<category>[.<n>].md
@@ -54,3 +56,70 @@ def classify_fragment(name, categories):
if category not in categories:
return "bad-category", category
return "ok", category
+
+
+# towncrier 24.8's built-in ignore list (``_builder.find_fragments``). It is
+# matched with ``fnmatch`` against the lower-cased basename.
+TOWNCRIER_IGNORED = (
+ ".gitignore",
+ ".gitkeep",
+ ".keep",
+ "readme",
+ "readme.md",
+ "readme.rst",
+)
+
+
+def load_towncrier_ignores(pyproject_path):
+ """Return the extra ignore patterns towncrier adds from *pyproject_path*.
+
+ Mirrors ``find_fragments``: a string ``template`` contributes its
+ basename verbatim and every ``ignore`` entry is lower-cased.
+ """
+ with Path(pyproject_path).open("rb") as fh:
+ cfg = tomllib.load(fh)["tool"]["towncrier"]
+ extra = []
+ template = cfg.get("template")
+ if isinstance(template, str):
+ extra.append(Path(template).name)
+ extra.extend(str(pattern).lower() for pattern in cfg.get("ignore", ()))
+ return tuple(extra)
+
+
+def towncrier_category(name, categories, ignores=()):
+ """Return the category towncrier renders *name* under, or ``None``.
+
+ This mirrors towncrier 24.8 exactly, not the stricter repo grammar in
+ ``FRAGMENT_RE``: ``find_fragments`` lists every directory entry
+ (dot-prefixed names and non-``.md`` extensions included), skips the
+ ignore list, and ``parse_newfragment_basename`` takes the last
+ dot-separated part after the first that names a declared category.
+ ``tests/ci/test_version_bump_selection.py`` checks it against
+ towncrier's own ``find_fragments``.
+ """
+ lowered = name.lower()
+ if any(fnmatch(lowered, pattern) for pattern in TOWNCRIER_IGNORED):
+ return None
+ if any(fnmatch(lowered, pattern) for pattern in ignores):
+ return None
+ parts = name.split(".")
+ for part in reversed(parts[1:]):
+ if part in categories:
+ return part
+ return None
+
+
+def towncrier_fragments(changelog_dir, pyproject_path):
+ """Map each entry towncrier would render from *changelog_dir* to its category."""
+ categories = load_categories(pyproject_path)
+ ignores = load_towncrier_ignores(pyproject_path)
+ try:
+ names = sorted(os.listdir(changelog_dir))
+ except FileNotFoundError:
+ names = []
+ found = {}
+ for name in names:
+ category = towncrier_category(name, categories, ignores)
+ if category is not None:
+ found[name] = category
+ return found
diff --git a/.pre-commit-hooks/check-changelog-fragments.py b/.pre-commit-hooks/check-changelog-fragments.py
index 866f0378f1..e62a5b5b97 100755
--- a/.pre-commit-hooks/check-changelog-fragments.py
+++ b/.pre-commit-hooks/check-changelog-fragments.py
@@ -18,7 +18,11 @@ from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _changelog_fragments import classify_fragment, load_categories
+from _changelog_fragments import (
+ classify_fragment,
+ load_categories,
+ towncrier_category,
+)
REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -27,14 +31,27 @@ def validate_directory(changelog_dir, categories):
"""Return one problem string per invalid file in *changelog_dir*.
Every regular file except README.md must be a valid fragment.
- Dotfiles are skipped so local editor/OS droppings (e.g. .DS_Store)
- don't fail commits that never stage them.
+ Dotfiles that towncrier would not render (e.g. .DS_Store, .gitkeep)
+ are skipped so local editor/OS droppings don't fail commits that never
+ stage them. A dotfile that towncrier *would* render (``.123.breaking.md``
+ parses as issue ``.123``, category ``breaking``) is refused: it is
+ published in the release notes while hiding from shell globs such as
+ the release-type selector's.
"""
problems = []
for path in sorted(Path(changelog_dir).iterdir()):
if not path.is_file():
continue
- if path.name == "README.md" or path.name.startswith("."):
+ if path.name.startswith("."):
+ category = towncrier_category(path.name, categories)
+ if category is not None:
+ problems.append(
+ f"{path.name} — dot-prefixed fragment; towncrier renders "
+ f"it under `{category}` but globs skip it. Rename it to "
+ f"`<id>.{category}.md` or `+<slug>.{category}.md`"
+ )
+ continue
+ if path.name == "README.md":
continue
kind, category = classify_fragment(path.name, categories)
if kind == "bad-name":
diff --git a/changelog.d/+breaking-release-selection.bugfix.md b/changelog.d/+breaking-release-selection.bugfix.md
new file mode 100644
index 0000000000..d06711cc52
--- /dev/null
+++ b/changelog.d/+breaking-release-selection.bugfix.md
@@ -0,0 +1 @@
+Stop automatic patch version proposals while breaking-change fragments are pending, close any open non-major version-bump PR, and refuse to propose or publish anything but a major release (`N.0.0`, or `0.N.0` before 1.0) until those fragments are released. Detection matches what towncrier renders, including counter-suffixed and dot-prefixed fragment names, and the changelog fragment check now rejects dot-prefixed fragments.
diff --git a/docs/RELEASE_GUIDE.md b/docs/RELEASE_GUIDE.md
index 38bb8f4e12..1be801446d 100644
--- a/docs/RELEASE_GUIDE.md
+++ b/docs/RELEASE_GUIDE.md
@@ -168,6 +168,28 @@ Code owners (defined in `.github/CODEOWNERS`):
from `changelog.d/`. Squash-merge — the diff has no review value
beyond a sanity check that the rendered notes look right.
+When `changelog.d/` contains a pending breaking fragment (any file towncrier
+renders under **Breaking Changes**, such as `<id>.breaking.md`,
+`+<slug>.breaking.md` or a counter-suffixed `<id>.breaking.<n>.md`),
+**Version Auto-Bump** skips automatic patch PR creation and updates, and on each run closes
+any open automatic bump PR whose version is not a major release. Review the
+release scope, then open Actions → **Version Auto-Bump** → **Run workflow** on
+`main` and explicitly choose **major** (for example, the FastAPI migration from
+1.x to 2.0.0). A manual **patch** is rejected. A manual **minor** is accepted
+only before 1.0 (`0.N.0`); on 1.x and later the bump job fails before opening a
+PR.
+
+The release workflow applies the same rule in its `build` job, before it
+attests, signs or publishes anything: while
+breaking fragments are pending it refuses to publish any version other than
+`N.0.0` (or `0.N.0` before 1.0), so a stale patch PR or a handwritten bump
+cannot ship breaking changes as `1.x.y`. `scripts/ci/check_breaking_release.py`
+implements both checks. Fragments stay pending until the cleanup PR (step 4)
+deletes them, so merge it before the next patch release. Review the selected
+version, release notes and complete release-gate results before merging the
+bump PR. Running Version Auto-Bump prepares a PR; merging that PR starts the
+release workflow described above.
+
To preview the rendered notes locally before merging the bump:
```bash
diff --git a/scripts/ci/check_breaking_release.py b/scripts/ci/check_breaking_release.py
new file mode 100644
index 0000000000..c3850021d4
--- /dev/null
+++ b/scripts/ci/check_breaking_release.py
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Detect pending breaking changelog fragments and refuse non-major releases.
+
+Used by ``version_check.yml`` (release-type selection, post-bump check and
+closing a stale bump PR) and ``release.yml`` (pre-publish guard).
+
+Fragment detection mirrors what towncrier renders, not a shell glob: a
+dot-prefixed ``changelog.d/.123.breaking.md`` or a counter-suffixed
+``123.breaking.2.md`` still lands under "Breaking Changes", so it must
+count here too. See ``towncrier_category`` in
+``.pre-commit-hooks/_changelog_fragments.py``.
+
+Subcommands:
+
+``pending``
+ Print every pending breaking fragment, one per line. Exit 0 whether or
+ not any exist; any other exit status is an error and callers must treat
+ it as a failure (never as "nothing pending").
+
+``version VERSION``
+ Exit 1 when breaking fragments are pending and VERSION is not a major
+ release: ``N.0.0`` for N >= 1, or ``0.N.0`` while still pre-1.0. A
+ patch (``1.10.8``) or minor (``1.11.0``) release would publish breaking
+ notes under a compatible-looking version. Exit 0 otherwise.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(
+ 0, str(Path(__file__).resolve().parents[2] / ".pre-commit-hooks")
+)
+
+from _changelog_fragments import towncrier_fragments # noqa: E402
+
+BREAKING = "breaking"
+_VERSION_RE = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)(?!\d)")
+
+
+def pending_breaking(changelog_dir, pyproject):
+ """Return the sorted names towncrier would render as breaking changes."""
+ found = towncrier_fragments(changelog_dir, pyproject)
+ return sorted(name for name, cat in found.items() if cat == BREAKING)
+
+
+def is_major_release(version):
+ """True for ``N.0.0`` (N >= 1) or ``0.N.0`` (N >= 1), pre-release suffixes allowed.
+
+ Anything unparseable is refused (returns False) so the guard fails closed.
+ """
+ match = _VERSION_RE.match(version.strip())
+ if not match:
+ return False
+ major, minor, patch = (int(group) for group in match.groups())
+ if patch != 0:
+ return False
+ if major >= 1:
+ return minor == 0
+ return minor >= 1
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("--changelog-dir", default="changelog.d")
+ parser.add_argument("--pyproject", default="pyproject.toml")
+ sub = parser.add_subparsers(dest="command", required=True)
+ sub.add_parser("pending", help="list pending breaking fragments")
+ check = sub.add_parser(
+ "version",
+ help="refuse a non-major VERSION while breaking fragments are pending",
+ )
+ check.add_argument("version")
+ args = parser.parse_args(argv)
+
+ breaking = pending_breaking(args.changelog_dir, args.pyproject)
+ if args.command == "pending":
+ for name in breaking:
+ print(name)
+ return 0
+
+ if breaking and not is_major_release(args.version):
+ print(
+ f"::error::Version {args.version} is not a major release, but "
+ f"breaking changelog fragments are pending: {', '.join(breaking)}. "
+ "Breaking changes need N.0.0 (or 0.N.0 before 1.0); see "
+ "docs/RELEASE_GUIDE.md."
+ )
+ return 1
+ if breaking:
+ print(
+ f"Version {args.version} is a major release; breaking fragments allowed."
+ )
+ else:
+ print("No breaking changelog fragments are pending.")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/ci/test_version_bump_selection.py b/tests/ci/test_version_bump_selection.py
new file mode 100644
index 0000000000..1febb01b9b
--- /dev/null
+++ b/tests/ci/test_version_bump_selection.py
@@ -0,0 +1,389 @@
+"""Execute the actual workflow selector before it can propose a release PR.
+
+Also pins the breaking-release guard shared by version_check.yml and
+release.yml (``scripts/ci/check_breaking_release.py``): breaking-fragment
+detection must agree with what towncrier renders, and a non-major version
+must never be proposed or published while breaking fragments are pending.
+"""
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+import pytest
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[2]
+WORKFLOW = ROOT / ".github/workflows/version_check.yml"
+RELEASE_WORKFLOW = ROOT / ".github/workflows/release.yml"
+SCRIPT = ROOT / "scripts/ci/check_breaking_release.py"
+STALE_STEP = "Close stale non-major bump PR"
+
+sys.path.insert(0, str(ROOT / "scripts/ci"))
+sys.path.insert(0, str(ROOT / ".pre-commit-hooks"))
+
+import check_breaking_release # noqa: E402
+from _changelog_fragments import towncrier_fragments # noqa: E402
+
+
+def _steps():
+ return yaml.safe_load(WORKFLOW.read_text())["jobs"]["version-bump"]["steps"]
+
+
+def _step(steps, **match):
+ return next(
+ step
+ for step in steps
+ if all(step.get(key) == value for key, value in match.items())
+ )
+
+
+def _repo_tree(tmp_path, fragments):
+ """Lay out the files the workflow scripts read, relative to the cwd."""
+ for name in ("scripts", ".pre-commit-hooks", "pyproject.toml"):
+ (tmp_path / name).symlink_to(ROOT / name)
+ if fragments:
+ directory = tmp_path / "changelog.d"
+ directory.mkdir()
+ for name in fragments:
+ (directory / name).write_text("Release change\n")
+
+
+def _bash(script, cwd, env):
+ # GitHub's `shell: bash` runs `bash --noprofile --norc -eo pipefail`.
+ return subprocess.run(
+ ["bash", "--noprofile", "--norc", "-eo", "pipefail", "-c", script],
+ cwd=cwd,
+ env={**os.environ, **env},
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+
+
+def _run_selector(tmp_path, event, requested):
+ output = tmp_path / "outputs"
+ output.touch()
+ selector = _step(_steps(), id="release")
+ result = _bash(
+ selector["run"],
+ tmp_path,
+ {
+ "EVENT_NAME": event,
+ "REQUESTED_TYPE": requested,
+ "GITHUB_OUTPUT": str(output),
+ },
+ )
+ outputs = dict(
+ line.split("=", 1) for line in output.read_text().splitlines()
+ )
+ return result, outputs
+
+
+ "fragments,event,requested,expected_type,allowed,exit_code",
+ [
+ ([], "push", "", "patch", True, 0),
+ (["123.bugfix.md"], "push", "", "patch", True, 0),
+ (["123.feature.md"], "push", "", "patch", True, 0),
+ (["123.breaking.md"], "push", "", None, False, 0),
+ (["123.bugfix.md", "456.breaking.md"], "push", "", None, False, 0),
+ ([], "workflow_dispatch", "patch", "patch", True, 0),
+ ([], "workflow_dispatch", "minor", "minor", True, 0),
+ (["123.breaking.md"], "workflow_dispatch", "patch", None, False, 1),
+ (["123.breaking.md"], "workflow_dispatch", "minor", "minor", True, 0),
+ (["123.breaking.md"], "workflow_dispatch", "major", "major", True, 0),
+ ([], "workflow_dispatch", "invalid", None, False, 1),
+ # Counter-suffixed breaking fragments are sanctioned by the
+ # changelog-fragment grammar (pre-commit hook: <id>.<category>.<n>.md,
+ # rendered as a separate breaking bullet) and MUST trip the gate too.
+ (["456.breaking.2.md"], "push", "", None, False, 0),
+ (["456.breaking.2.md"], "workflow_dispatch", "patch", None, False, 1),
+ (["+two-breaks.breaking.3.md"], "push", "", None, False, 0),
+ # towncrier renders a dot-prefixed fragment (issue ".123") under
+ # Breaking Changes even though shell globs skip it.
+ ([".123.breaking.md"], "push", "", None, False, 0),
+ ([".123.breaking.md"], "workflow_dispatch", "patch", None, False, 1),
+ # towncrier takes the LAST declared category, so this is a bugfix.
+ (["123.breaking.bugfix.md"], "push", "", "patch", True, 0),
+ # A slug containing "breaking" is not the breaking category.
+ (
+ ["+breaking-release-selection.bugfix.md"],
+ "push",
+ "",
+ "patch",
+ True,
+ 0,
+ ),
+ ],
+)
+def test_release_selection(
+ tmp_path, fragments, event, requested, expected_type, allowed, exit_code
+):
+ _repo_tree(tmp_path, fragments)
+ result, outputs = _run_selector(tmp_path, event, requested)
+ assert result.returncode == exit_code, result.stdout + result.stderr
+ assert (outputs.get("allowed") == "true") is allowed
+ assert outputs.get("type") == expected_type
+ if not allowed and exit_code == 0:
+ assert "Breaking changes" in result.stdout
+
+
+def test_selector_fails_closed_when_detection_errors(tmp_path):
+ # Without pyproject.toml the detector cannot know the categories. That
+ # must fail the step, never read as "no breaking fragments pending".
+ (tmp_path / "scripts").symlink_to(ROOT / "scripts")
+ (tmp_path / ".pre-commit-hooks").symlink_to(ROOT / ".pre-commit-hooks")
+ (tmp_path / "changelog.d").mkdir()
+ (tmp_path / "changelog.d" / "123.breaking.md").write_text("x\n")
+ result, outputs = _run_selector(tmp_path, "push", "")
+ assert result.returncode != 0
+ assert "allowed" not in outputs
+
+
+def test_selector_env_maps_the_real_event_and_dispatch_input():
+ # The selector tests above inject EVENT_NAME / REQUESTED_TYPE directly,
+ # so pin the workflow's own mapping from the GitHub context.
+ workflow = yaml.safe_load(WORKFLOW.read_text())
+ selector = _step(_steps(), id="release")
+ assert selector["shell"] == "bash"
+ assert selector["env"] == {
+ "EVENT_NAME": "${{ github.event_name }}",
+ "REQUESTED_TYPE": "${{ inputs.release_type }}",
+ }
+ # Only the mapped variables reach the script; no inline expressions.
+ assert "${{" not in selector["run"]
+ assert '"$EVENT_NAME"' in selector["run"]
+ assert '"$REQUESTED_TYPE"' in selector["run"]
+ # PyYAML parses the bare `on:` key as boolean True.
+ triggers = workflow.get("on", workflow.get(True))
+ release_input = triggers["workflow_dispatch"]["inputs"]["release_type"]
+ assert release_input["options"] == ["patch", "minor", "major"]
+
+
+def test_every_downstream_step_requires_an_allowed_release():
+ # A correct selector alone is insufficient if PR creation can bypass it.
+ steps = _steps()
+ selector_index = next(
+ index for index, step in enumerate(steps) if step.get("id") == "release"
+ )
+ downstream = steps[selector_index + 1 :]
+ assert any(step["name"] == "Create Pull Request" for step in downstream)
+ for step in downstream:
+ if step["name"] == STALE_STEP:
+ # The only step for the blocked case; it closes, never creates.
+ assert step["if"] == "steps.release.outputs.allowed == 'false'"
+ assert "gh pr create" not in step["run"]
+ continue
+ condition = step.get("if", "")
+ assert condition.startswith(
+ "steps.release.outputs.allowed == 'true' && "
+ ), step["name"]
+ assert "||" not in condition, step["name"]
+
+
+def test_bump_is_rechecked_against_pending_breaking_fragments():
+ steps = _steps()
+ names = [step["name"] for step in steps]
+ guard = _step(steps, name="Refuse a non-major version for breaking changes")
+ assert names.index("Bump version") < names.index(guard["name"])
+ assert names.index(guard["name"]) < names.index("Create Pull Request")
+ assert guard["env"] == {
+ "NEW_VERSION": "${{ steps.bump.outputs.new_version }}"
+ }
+ assert guard["run"].strip() == (
+ 'python scripts/ci/check_breaking_release.py version "$NEW_VERSION"'
+ )
+ assert not guard.get("continue-on-error", False)
+ assert "new_version=" in _step(steps, id="bump")["run"]
+
+
+def test_release_workflow_refuses_non_major_breaking_release():
+ # A stale patch bump PR merged by hand reaches release.yml directly.
+ build = yaml.safe_load(RELEASE_WORKFLOW.read_text())["jobs"]["build"]
+ steps = build["steps"]
+ names = [step.get("name") for step in steps]
+ guard = _step(
+ steps, name="Refuse a non-major release with pending breaking changes"
+ )
+ assert guard["env"] == {
+ "RELEASE_VERSION": "${{ steps.version.outputs.version }}"
+ }
+ assert guard["run"].strip() == (
+ 'python3 scripts/ci/check_breaking_release.py version "$RELEASE_VERSION"'
+ )
+ assert guard["if"] == "steps.check_release.outputs.exists == 'false'"
+ assert not guard.get("continue-on-error", False)
+ # Only pre-flight checks run before the guard: nothing is downloaded,
+ # attested, signed or uploaded for a version the guard refuses.
+ preflight = {
+ "Harden the runner (Audit all outbound calls)",
+ "Checkout code",
+ "Verify build commit is on main",
+ "Determine version",
+ "Check if release already exists",
+ "Verify version matches __version__.py",
+ }
+ guard_index = names.index(guard["name"])
+ assert set(names[:guard_index]) <= preflight
+ for later in (
+ "Download tested Python distributions",
+ "Verify Python artifacts before attestation",
+ "Attest tested Python artifacts at the release commit",
+ "Sign release artifacts with Sigstore",
+ "Upload artifacts for release",
+ ):
+ assert names.index(later) > guard_index, later
+ for step in steps[:guard_index]:
+ uses = step.get("uses", "")
+ for action in ("attest", "download-artifact", "upload-artifact"):
+ assert action not in uses, uses
+ checkout = _step(steps, name="Checkout code")
+ assert "sparse-checkout" not in checkout.get("with", {})
+
+
+ "version,major",
+ [
+ ("2.0.0", True),
+ ("v2.0.0", True),
+ ("2.0.0rc1", True),
+ ("0.5.0", True),
+ ("1.10.8", False),
+ ("1.11.0", False),
+ ("2.0.1", False),
+ ("0.5.1", False),
+ ("0.0.0", False),
+ ("2.0", False),
+ ("garbage", False),
+ ("", False),
+ ],
+)
+def test_is_major_release(version, major):
+ assert check_breaking_release.is_major_release(version) is major
+
+
+ "fragments,version,exit_code",
+ [
+ (["3299.breaking.md"], "1.10.8", 1),
+ (["3299.breaking.md"], "1.11.0", 1),
+ (["3299.breaking.md"], "2.0.0", 0),
+ ([".3299.breaking.md"], "1.10.8", 1),
+ (["3299.breaking.2.md"], "1.10.8", 1),
+ (["3299.bugfix.md"], "1.10.8", 0),
+ ([], "1.10.8", 0),
+ ],
+)
+def test_version_subcommand(tmp_path, fragments, version, exit_code):
+ _repo_tree(tmp_path, fragments)
+ result = subprocess.run(
+ [sys.executable, str(SCRIPT), "version", version],
+ cwd=tmp_path,
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert result.returncode == exit_code, result.stdout + result.stderr
+ if exit_code:
+ assert "::error::" in result.stdout
+
+
+def test_close_stale_bump_pr_closes_only_non_major(tmp_path):
+ # Execute the real step with a fake `gh`: #6083-style patch PRs close,
+ # a manually dispatched major PR stays open.
+ _repo_tree(tmp_path, ["3299.breaking.md"])
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir()
+ log = tmp_path / "gh.log"
+ fake_gh = bin_dir / "gh"
+ fake_gh.write_text(
+ "#!/bin/bash\n"
+ f'echo "$*" >> "{log}"\n'
+ 'if [ "$1 $2" = "pr list" ]; then\n'
+ " printf '6083\\tchore: bump patch version to 1.10.8\\n'\n"
+ " printf '6100\\tchore: bump minor version to 1.11.0\\n'\n"
+ " printf '7000\\tchore: bump major version to 2.0.0\\n'\n"
+ "fi\n"
+ )
+ fake_gh.chmod(0o755)
+ step = _step(_steps(), name=STALE_STEP)
+ assert step["env"]["GH_TOKEN"] == "${{ secrets.GITHUB_TOKEN }}"
+ runner_temp = tmp_path / "runner"
+ runner_temp.mkdir()
+ result = _bash(
+ step["run"],
+ tmp_path,
+ {
+ "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}",
+ "RUNNER_TEMP": str(runner_temp),
+ },
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ calls = log.read_text().splitlines()
+ assert "--head chore/auto-version-bump" in calls[0]
+ assert "isCrossRepository" in calls[0]
+ closed = [call.split()[2] for call in calls if call.startswith("pr close")]
+ assert closed == ["6083", "6100"]
+
+
+def _towncrier_rendered(tmp_path, names):
+ towncrier_builder = pytest.importorskip("towncrier._builder")
+ towncrier_load = pytest.importorskip("towncrier._settings.load")
+ (tmp_path / "pyproject.toml").write_text(
+ (ROOT / "pyproject.toml").read_text()
+ )
+ directory = tmp_path / "changelog.d"
+ directory.mkdir()
+ for name in names:
+ (directory / name).write_text("x\n")
+ config = towncrier_load.load_config_from_file(
+ str(tmp_path), str(tmp_path / "pyproject.toml")
+ )
+ _, files = towncrier_builder.find_fragments(
+ str(tmp_path), config, strict=False
+ )
+ return {Path(path).name: category for path, category in files}
+
+
+def test_detection_matches_towncrier_find_fragments(tmp_path):
+ # Distinct (issue, category, counter) keys: towncrier rejects duplicates.
+ names = [
+ "1.breaking.md",
+ "2.breaking.3.md",
+ ".3.breaking.md",
+ ".breaking.md",
+ "4.breaking.txt",
+ "5.breaking",
+ "6.BREAKING.md",
+ "7.breaking.bugfix.md",
+ "8.bugfix.breaking.md",
+ "x.y.breaking.md",
+ "breaking.md",
+ "9.feature.md",
+ "notes.md",
+ "README.md",
+ "readme.rst",
+ "Readme",
+ ".gitkeep",
+ ".keep",
+ ".DS_Store",
+ ]
+ expected = _towncrier_rendered(tmp_path, names)
+ assert expected["1.breaking.md"] == "breaking"
+ assert expected[".3.breaking.md"] == "breaking"
+ actual = towncrier_fragments(
+ tmp_path / "changelog.d", tmp_path / "pyproject.toml"
+ )
+ assert actual == expected
+
+
+def test_repo_changelog_detection_matches_towncrier(tmp_path):
+ names = [p.name for p in (ROOT / "changelog.d").iterdir() if p.is_file()]
+ expected = _towncrier_rendered(tmp_path, names)
+ actual = towncrier_fragments(
+ tmp_path / "changelog.d", tmp_path / "pyproject.toml"
+ )
+ assert actual == expected
diff --git a/tests/hooks/test_check_changelog_fragments.py b/tests/hooks/test_check_changelog_fragments.py
index 9e26146a8b..150941edd8 100644
--- a/tests/hooks/test_check_changelog_fragments.py
+++ b/tests/hooks/test_check_changelog_fragments.py
@@ -165,6 +165,26 @@ class TestHookEndToEnd:
f"stdout={result.stdout!r} stderr={result.stderr!r}"
)
+ def test_towncrier_ignored_dotfiles_pass(self, tmp_path):
+ result = _run_hook(tmp_path, [".gitkeep", ".keep", ".gitignore"])
+ assert result.returncode == 0, (
+ f"stdout={result.stdout!r} stderr={result.stderr!r}"
+ )
+
+ def test_dot_prefixed_fragment_towncrier_renders_fails(self, tmp_path):
+ # towncrier parses `.123.breaking.md` as issue `.123`, category
+ # `breaking`, and publishes it; shell globs never see it, so the
+ # release-type selector could not either.
+ result = _run_hook(tmp_path, [".123.breaking.md", "5023.misc.md"])
+ assert result.returncode == 1
+ assert ".123.breaking.md" in result.stdout
+ assert "dot-prefixed" in result.stdout
+
+ def test_dot_prefixed_counter_fragment_fails(self, tmp_path):
+ result = _run_hook(tmp_path, [".+slug.security.2.md"])
+ assert result.returncode == 1
+ assert "dot-prefixed" in result.stdout
+
def test_empty_changelog_dir_passes(self, tmp_path):
result = _run_hook(tmp_path, ["README.md"])
assert result.returncode == 0