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..5c4c4e14c --- /dev/null +++ b/src/icalendar/tests/test_version_directives.py @@ -0,0 +1,132 @@ +"""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 +from unittest.mock import Mock + +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_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.""" + 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()) + ) + )