use tagged releases to pull core porting guides

changelogs/fragments/544-porting_guide_tagged.yaml

@@ -0,0 +1,5 @@
+---
+minor_changes:
+  - Use tagged ansible-core / ansible-documentation releases to retrieve core
+    porting guide
+    (https://github.com/ansible-community/antsibull/pull/544).

src/antsibull/changelog.py

@@ -33,6 +33,7 @@
 from semantic_version import Version as SemVer
 
 from antsibull.collection_meta import CollectionsMetadata
+from antsibull.utils.urls import get_documentation_repo_raw_url
 
 
 class ChangelogData:
@@ -155,12 +156,14 @@ def matcher(filename: str) -> bool:
     return read_file(tarball_path, matcher)
 
 
-def get_porting_guide_filename(version: PypiVer):
-    if version.major == 2 and version.minor == 10:
-        basename = "porting_guide_base"
-    else:
-        basename = "porting_guide_core"
-    return f"docs/docsite/rst/porting_guides/{basename}_{version.major}.{version.minor}.rst"
+def get_core_porting_guide_url(version: PypiVer):
+    major_minor = f"{version.major}.{version.minor}"
+    return (
+        get_documentation_repo_raw_url(version)
+        + f"/v{version}"
+        + "/docs/docsite/rst/porting_guides"
+        + f"/porting_guide_core_{major_minor}.rst"
+    )
 
 
 class CollectionChangelogCollector:
@@ -320,11 +323,7 @@ async def download_changelog(
         self.changelog = ChangelogData.concatenate(changelogs)
 
     async def download_porting_guide(self, aio_session: aiohttp.client.ClientSession):
-        branch_url = (
-            "https://raw.githubusercontent.com/ansible/ansible-documentation/devel"
-        )
-
-        query_url = f"{branch_url}/{get_porting_guide_filename(self.latest)}"
+        query_url = get_core_porting_guide_url(self.latest)
         async with aio_session.get(query_url) as response:
             self.porting_guide = await response.read()
 

src/antsibull/constants.py

@@ -22,3 +22,13 @@
 DOCSITE_COMMUNITY_URL = "https://docs.ansible.com/ansible/latest/community"
 
 COLLECTION_EXCLUDE_DIRS = ("docs", "tests")
+
+# First ansible-core version that has its documentation split out into
+# ansible/ansible-documentation.
+ANSIBLE_DOCUMENTATION_MINIMUM = PypiVer("2.15.2")
+ANSIBLE_DOCUMENTATION_RANGES: dict[str, PypiVer] = {
+    "2.13": PypiVer("2.13.11"),
+    "2.14": PypiVer("2.14.8"),
+}
+ANSIBLE_DOCUMENTATION_RAW_URL = "https://github.com/ansible/ansible-documentation/raw"
+ANSIBLE_CORE_RAW_URL = "https://github.com/ansible/ansible/raw"

src/antsibull/utils/urls.py

@@ -0,0 +1,35 @@
+# Copyright (C) 2023 Maxwell G <[email protected]>
+# SPDX-License-Identifier: GPL-3.0-or-later
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+Utilities for working with ansible URLs
+"""
+
+from __future__ import annotations
+
+from packaging.version import Version as PypiVer
+
+from ..constants import (
+    ANSIBLE_CORE_RAW_URL,
+    ANSIBLE_DOCUMENTATION_MINIMUM,
+    ANSIBLE_DOCUMENTATION_RANGES,
+    ANSIBLE_DOCUMENTATION_RAW_URL,
+)
+
+
+def get_documentation_repo_raw_url(version: PypiVer) -> str:
+    """
+    Return the raw url for retrieving ansible documentation files
+    See https://github.com/ansible-community/community-topics/issues/240.
+    """
+    major_minor = f"{version.major}.{version.minor}"
+    minimum_version = ANSIBLE_DOCUMENTATION_RANGES.get(
+        major_minor, ANSIBLE_DOCUMENTATION_MINIMUM
+    )
+    return (
+        ANSIBLE_DOCUMENTATION_RAW_URL
+        if version >= minimum_version
+        else ANSIBLE_CORE_RAW_URL
+    )

tests/test_changelog.py

@@ -0,0 +1,41 @@
+# Copyright (C) 2023 Maxwell G <[email protected]>
+# SPDX-License-Identifier: GPL-3.0-or-later
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# It doesn't make sense to split up the long URLs
+# flake8: noqa E501
+
+import pytest
+from packaging.version import Version as PypiVer
+
+from antsibull.changelog import get_core_porting_guide_url
+
+
+@pytest.mark.parametrize(
+    "version, expected",
+    [
+        pytest.param(
+            PypiVer("2.12.0"),
+            "https://github.com/ansible/ansible/raw/v2.12.0/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst",
+        ),
+        pytest.param(
+            PypiVer("2.13.0"),
+            "https://github.com/ansible/ansible/raw/v2.13.0/docs/docsite/rst/porting_guides/porting_guide_core_2.13.rst",
+        ),
+        pytest.param(
+            PypiVer("2.13.11"),
+            "https://github.com/ansible/ansible-documentation/raw/v2.13.11/docs/docsite/rst/porting_guides/porting_guide_core_2.13.rst",
+        ),
+        pytest.param(
+            PypiVer("2.14.8"),
+            "https://github.com/ansible/ansible-documentation/raw/v2.14.8/docs/docsite/rst/porting_guides/porting_guide_core_2.14.rst",
+        ),
+        pytest.param(
+            PypiVer("2.16.0a1"),
+            "https://github.com/ansible/ansible-documentation/raw/v2.16.0a1/docs/docsite/rst/porting_guides/porting_guide_core_2.16.rst",
+        ),
+    ],
+)
+def test_get_core_porting_guide_url(version: PypiVer, expected: str):
+    assert get_core_porting_guide_url(version) == expected

tests/test_utils.py

@@ -0,0 +1,24 @@
+# Copyright (C) 2023 Maxwell G <[email protected]>
+# SPDX-License-Identifier: GPL-3.0-or-later
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import pytest
+from packaging.version import Version as PypiVer
+
+from antsibull.constants import ANSIBLE_CORE_RAW_URL, ANSIBLE_DOCUMENTATION_RAW_URL
+from antsibull.utils.urls import get_documentation_repo_raw_url
+
+
+@pytest.mark.parametrize(
+    "version, expected",
+    [
+        pytest.param(PypiVer("2.12.0"), ANSIBLE_CORE_RAW_URL),
+        pytest.param(PypiVer("2.13.0"), ANSIBLE_CORE_RAW_URL),
+        pytest.param(PypiVer("2.13.11"), ANSIBLE_DOCUMENTATION_RAW_URL),
+        pytest.param(PypiVer("2.14.8"), ANSIBLE_DOCUMENTATION_RAW_URL),
+        pytest.param(PypiVer("2.16.0a1"), ANSIBLE_DOCUMENTATION_RAW_URL),
+    ],
+)
+def test_get_documentation_repo_raw_url(version: PypiVer, expected: str):
+    assert get_documentation_repo_raw_url(version) == expected