From 4fa6ba5bf0c758ff5d98df1f57ff56bc5c7f63ce Mon Sep 17 00:00:00 2001 From: Dane Parin Date: Mon, 9 Nov 2026 08:04:36 +0700 Subject: [PATCH 1/3] Check Sphinx version directives AI disclosure: GPT-6 Luna reviewed the patch. Prompt: Review the patch for potential issues and suggestions. --- .github/workflows/tests.yml | 2 + news/2026.internal | 1 + src/icalendar/prop/binary.py | 2 +- .../tests/test_version_directives.py | 91 +++++++++++++++++++ 4 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 news/2026.internal create mode 100644 src/icalendar/tests/test_version_directives.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0e0b8d921..127c04803 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -46,6 +46,8 @@ jobs: run: echo "Skipped ${{ matrix.test_name }} (not required for this trigger)" - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 if: ${{ !matrix.skip }} + with: + fetch-tags: true - name: Install uv and Python ${{ matrix.python_version }} if: ${{ !matrix.skip }} uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 diff --git a/news/2026.internal b/news/2026.internal new file mode 100644 index 000000000..d39c1af4e --- /dev/null +++ b/news/2026.internal @@ -0,0 +1 @@ +Added a test that every Sphinx version directive uses a released version tag or the ``0.0.0`` placeholder, and changed the ``vBinary`` removal directive from the unreleased ``8.0.0`` to ``0.0.0``. Reviewed by GPT-6 Luna. @SemTiOne diff --git a/src/icalendar/prop/binary.py b/src/icalendar/prop/binary.py index 23f050b04..bc8079ecc 100644 --- a/src/icalendar/prop/binary.py +++ b/src/icalendar/prop/binary.py @@ -16,7 +16,7 @@ class vBinary: """Binary property values are Base64 encoded. - .. versionremoved:: 8.0.0 + .. versionremoved:: 0.0.0 Removed ``obj`` attribute, use :attr:`bytes` to access the binary content. .. seealso:: :ref:`vbinary-obj-removed`. diff --git a/src/icalendar/tests/test_version_directives.py b/src/icalendar/tests/test_version_directives.py new file mode 100644 index 000000000..6a2f67c7f --- /dev/null +++ b/src/icalendar/tests/test_version_directives.py @@ -0,0 +1,91 @@ +"""Check that Sphinx version directives use released versions. + +``0.0.0`` is allowed until a release replaces it with the release version. +See https://github.com/collective/icalendar/issues/2026 +""" + +import os +import re +import subprocess +from pathlib import Path + +import pytest + +REPOSITORY_ROOT = Path(__file__).parents[3] +VERSION_DIRECTIVE = re.compile( + r"^\s*\.\.\s+" + r"(?:version-?added|version-?changed|version-?removed|version-?deprecated|deprecated)" + r"::\s*(\S+)" +) +RELEASE_BRANCH = re.compile(r"^(?:main|\d+\.x)$") +SOURCE_GLOBS = ("docs/**/*.rst", "src/icalendar/**/*.py") + + +def _is_release_branch(): + """Return whether the current branch is main or a version branch.""" + branch = os.environ.get("GITHUB_REF_NAME") + if branch is None: + try: + branch = subprocess.run( + ["git", "branch", "--show-current"], # noqa: S607 + cwd=REPOSITORY_ROOT, + capture_output=True, + text=True, + check=True, + ).stdout.strip() + except (OSError, subprocess.CalledProcessError): + return False + return RELEASE_BRANCH.match(branch) is not None + + +def _released_versions(): + """Return versions that have a Git tag.""" + try: + result = subprocess.run( + ["git", "tag", "--list"], # noqa: S607 + cwd=REPOSITORY_ROOT, + capture_output=True, + text=True, + check=True, + ) + except (OSError, subprocess.CalledProcessError) as error: + pytest.skip(f"Git tags are not available: {error}") + versions = {tag.removeprefix("v") for tag in result.stdout.split()} + if not versions: + pytest.skip("No Git tags found. Fetch tags to run this check.") + return versions + + +def _version_directives(): + """Yield the location and version of every Sphinx version directive.""" + for pattern in SOURCE_GLOBS: + for path in sorted(REPOSITORY_ROOT.glob(pattern)): + for number, line in enumerate( + path.read_text(encoding="utf-8").splitlines(), 1 + ): + match = VERSION_DIRECTIVE.match(line) + if match: + yield ( + f"{path.relative_to(REPOSITORY_ROOT)}:{number}", + match.group(1), + ) + + +def test_version_directives_use_released_versions(): + """Version directives must use a released version or the 0.0.0 placeholder.""" + if _is_release_branch(): + pytest.skip( + "Version directives are rewritten for a release; checked on pull requests." + ) + allowed = _released_versions() | {"0.0.0"} + directives = list(_version_directives()) + assert directives, "No version directives found. The scanner may be broken." + invalid = { + location: version for location, version in directives if version not in allowed + } + assert not invalid, ( + "Version directives must use a released version or 0.0.0:\n" + + "\n".join( + f" {location}: {version}" for location, version in sorted(invalid.items()) + ) + ) From 883fa803b04f7c2aabcfc16f39f08f750b1fbdc9 Mon Sep 17 00:00:00 2001 From: Dane Parin Date: Mon, 9 Nov 2026 09:14:38 +0700 Subject: [PATCH 2/3] Test Git fallback paths for version directives --- .../tests/test_version_directives.py | 49 +++++++++++++++++-- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/src/icalendar/tests/test_version_directives.py b/src/icalendar/tests/test_version_directives.py index 6a2f67c7f..72c970cc9 100644 --- a/src/icalendar/tests/test_version_directives.py +++ b/src/icalendar/tests/test_version_directives.py @@ -8,6 +8,7 @@ import re import subprocess from pathlib import Path +from unittest.mock import Mock import pytest @@ -71,12 +72,52 @@ def _version_directives(): ) +def test_is_release_branch_returns_false_without_git(monkeypatch): + """A missing Git executable must not fail the check.""" + monkeypatch.delenv("GITHUB_REF_NAME", raising=False) + monkeypatch.setattr( + subprocess, + "run", + Mock(side_effect=FileNotFoundError("git not found")), + ) + + assert _is_release_branch() is False + + +@pytest.mark.parametrize("branch", ["main", "8.x"]) +def test_is_release_branch(monkeypatch, branch): + """Detect main and version release branches.""" + monkeypatch.setenv("GITHUB_REF_NAME", branch) + + assert _is_release_branch() + + +def test_released_versions_skips_without_git(monkeypatch): + """A failing Git command must skip the check.""" + monkeypatch.setattr( + subprocess, + "run", + Mock(side_effect=FileNotFoundError("git not found")), + ) + + with pytest.raises(pytest.skip.Exception, match="Git tags are not available"): + _released_versions() + + +def test_released_versions_skips_without_tags(monkeypatch): + """A repository without tags must skip the check.""" + monkeypatch.setattr(subprocess, "run", Mock(return_value=Mock(stdout=""))) + + with pytest.raises(pytest.skip.Exception, match="No Git tags found"): + _released_versions() + + +@pytest.mark.skipif( + _is_release_branch(), + reason="Version directives are rewritten for a release; checked on pull requests.", +) def test_version_directives_use_released_versions(): """Version directives must use a released version or the 0.0.0 placeholder.""" - if _is_release_branch(): - pytest.skip( - "Version directives are rewritten for a release; checked on pull requests." - ) allowed = _released_versions() | {"0.0.0"} directives = list(_version_directives()) assert directives, "No version directives found. The scanner may be broken." From 2ccdc1c61eee84d12150188c0663293665653374 Mon Sep 17 00:00:00 2001 From: Dane Parin Date: Wed, 11 Nov 2026 17:21:34 +0700 Subject: [PATCH 3/3] Apply suggestion from @stevepiercy Co-authored-by: Steve Piercy --- src/icalendar/tests/test_version_directives.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/tests/test_version_directives.py b/src/icalendar/tests/test_version_directives.py index 72c970cc9..5c4c4e14c 100644 --- a/src/icalendar/tests/test_version_directives.py +++ b/src/icalendar/tests/test_version_directives.py @@ -15,7 +15,7 @@ REPOSITORY_ROOT = Path(__file__).parents[3] VERSION_DIRECTIVE = re.compile( r"^\s*\.\.\s+" - r"(?:version-?added|version-?changed|version-?removed|version-?deprecated|deprecated)" + r"(?:version-?added|version-?changed|version-?removed|version-deprecated|deprecated)" r"::\s*(\S+)" ) RELEASE_BRANCH = re.compile(r"^(?:main|\d+\.x)$")