Add auto-generated compatibility matrix docs

docs/_templates/sdk_compatibility.j2

@@ -0,0 +1,62 @@
+---
+title: Compatibility matrix
+---
+# Compatibility matrix
+
+This page documents which versions of the Infrahub Python SDK are compatible with each version of Infrahub.
+
+## Version mapping
+
+Each Infrahub release pins a specific SDK version. Using the matching SDK version ensures full compatibility. Newer patch releases of the SDK within the same minor version are generally safe to use.
+
+<!-- vale off -->
+| Infrahub | Required SDK | Release date |
+| --- | --- | --- |
+{% for v in version_ranges %}
+| {{ v.infrahub }} | >= {{ v.min_sdk }} | {{ v.date }} |
+{% endfor %}
+<!-- vale on -->
+
+## Detailed release mapping
+
+The table below shows the exact SDK version pinned to each Infrahub release.
+
+<!-- vale off -->
+| Infrahub | SDK version | Infrahub release date |
+| --- | --- | --- |
+{% for r in release_mappings %}
+| {{ r.infrahub }} | {{ r.sdk }} | {{ r.date }} |
+{% endfor %}
+<!-- vale on -->
+
+## Python version support
+
+<!-- vale off -->
+| SDK version | Python versions |
+| --- | --- |
+{% for p in python_support %}
+| {{ p.sdk_range }} | {{ p.python_versions }} |
+{% endfor %}
+<!-- vale on -->
+
+:::note
+The Infrahub server requires Python 3.12 or later. The SDK supports older Python versions so it can be used from environments that do not run the server itself.
+:::
+
+## Feature-specific requirements
+
+Some SDK features require a minimum Infrahub version:
+
+<!-- vale off -->
+| Feature | Minimum SDK | Minimum Infrahub |
+| --- | --- | --- |
+{% for f in feature_requirements %}
+| {{ f.feature }} | {{ f.min_sdk }} | {{ f.min_infrahub }} |
+{% endfor %}
+<!-- vale on -->
+
+## General guidance
+
+- **Use the SDK version that matches your Infrahub release.** The version mapping table above shows which SDK version was tested and shipped with each Infrahub release.
+- **Patch upgrades within a minor SDK version are safe.** For example, if your Infrahub version pins SDK 1.18.0, upgrading to 1.18.1 is safe.
+- **Upgrading to a newer minor SDK version may work** but is not guaranteed. New SDK features may depend on server-side changes that are not present in older Infrahub versions.

docs/docs/python-sdk/introduction.mdx

@@ -33,4 +33,5 @@ The Infrahub Python SDK greatly simplifies how you can interact with Infrahub pr
 ## Reference
 
 - [Client configuration](./reference/config.mdx)
+- [Compatibility matrix](./reference/compatibility.mdx)
 - [Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases)

docs/docs/python-sdk/reference/compatibility.mdx

@@ -0,0 +1,91 @@
+---
+title: Compatibility matrix
+---
+# Compatibility matrix
+
+This page documents which versions of the Infrahub Python SDK are compatible with each version of Infrahub.
+
+## Version mapping
+
+Each Infrahub release pins a specific SDK version. Using the matching SDK version ensures full compatibility. Newer patch releases of the SDK within the same minor version are generally safe to use.
+
+<!-- vale off -->
+| Infrahub | Required SDK | Release date |
+| --- | --- | --- |
+| 1.8.x | >= 1.19.0 | March 2026 |
+| 1.7.x | >= 1.18.0 | January 2026 |
+| 1.6.x | >= 1.16.0 | December 2025 |
+| 1.5.x | >= 1.15.0 | November 2025 |
+| 1.4.x | >= 1.13.5 | August 2025 |
+| 1.3.x | >= 1.13.0 | June 2025 |
+<!-- vale on -->
+
+## Detailed release mapping
+
+The table below shows the exact SDK version pinned to each Infrahub release.
+
+<!-- vale off -->
+| Infrahub | SDK version | Infrahub release date |
+| --- | --- | --- |
+| 1.8.4 | 1.19.0 | 2026-04-02 |
+| 1.8.3 | 1.19.0 | 2026-03-31 |
+| 1.8.2 | 1.19.0 | 2026-03-25 |
+| 1.8.1 | 1.19.0 | 2026-03-19 |
+| 1.8.0 | 1.19.0 | 2026-03-16 |
+| 1.7.7 | 1.18.1 | 2026-03-12 |
+| 1.7.6 | 1.18.1 | 2026-02-25 |
+| 1.7.5 | 1.18.1 | 2026-02-24 |
+| 1.7.4 | 1.18.1 | 2026-02-03 |
+| 1.7.3 | 1.18.1 | 2026-01-28 |
+| 1.7.2 | 1.18.1 | 2026-01-27 |
+| 1.7.1 | 1.18.1 | 2026-01-12 |
+| 1.7.0 | 1.18.1 | 2026-01-09 |
+| 1.6.3 | 1.17.0 | 2026-01-07 |
+| 1.6.2 | 1.17.0 | 2025-12-22 |
+| 1.6.1 | 1.17.0 | 2025-12-11 |
+| 1.6.0 | 1.16.0 | 2025-12-01 |
+| 1.5.5 | 1.15.1 | 2025-12-22 |
+| 1.5.4 | 1.15.1 | 2025-12-16 |
+| 1.5.3 | 1.15.1 | 2025-11-24 |
+| 1.5.2 | 1.15.1 | 2025-11-18 |
+| 1.5.1 | 1.15.1 | 2025-11-13 |
+| 1.5.0 | 1.15.0 | 2025-11-10 |
+| 1.4.1 | 1.13.5 | 2025-08-27 |
+| 1.4.0 | 1.13.5 | 2025-08-26 |
+| 1.3.3 | 1.13.3 | 2025-07-15 |
+| 1.3.2 | 1.13.3 | 2025-06-30 |
+| 1.3.1 | 1.13.2 | 2025-06-27 |
+| 1.3.0 | 1.13.0 | 2025-06-12 |
+<!-- vale on -->
+
+## Python version support
+
+<!-- vale off -->
+| SDK version | Python versions |
+| --- | --- |
+| >= 1.17.0 | 3.10, 3.11, 3.12, 3.13, 3.14 |
+| 1.16.0 | 3.10, 3.11, 3.12, 3.13 |
+| 1.13.0 - 1.15.x | 3.9, 3.10, 3.11, 3.12, 3.13 |
+<!-- vale on -->
+
+:::note
+The Infrahub server requires Python 3.12 or later. The SDK supports older Python versions so it can be used from environments that do not run the server itself.
+:::
+
+## Feature-specific requirements
+
+Some SDK features require a minimum Infrahub version:
+
+<!-- vale off -->
+| Feature | Minimum SDK | Minimum Infrahub |
+| --- | --- | --- |
+| infrahubctl branch report | 1.19.0 | 1.7 |
+| FileObject support | 1.19.0 | 1.8 |
+| NumberPool support | 1.13.0 | 1.3 |
+<!-- vale on -->
+
+## General guidance
+
+- **Use the SDK version that matches your Infrahub release.** The version mapping table above shows which SDK version was tested and shipped with each Infrahub release.
+- **Patch upgrades within a minor SDK version are safe.** For example, if your Infrahub version pins SDK 1.18.0, upgrading to 1.18.1 is safe.
+- **Upgrading to a newer minor SDK version may work** but is not guaranteed. New SDK features may depend on server-side changes that are not present in older Infrahub versions.

docs/docs_generation/compatibility.py

@@ -0,0 +1,127 @@
+"""Compatibility data between the Infrahub Python SDK and Infrahub server.
+
+This module provides structured data for auto-generating the compatibility
+matrix documentation page. Update the lists below when new releases are made.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ReleaseMapping:
+    """Maps an Infrahub server release to its pinned SDK version.
+
+    Args:
+        infrahub: Infrahub server version (e.g. "1.8.4").
+        sdk: SDK version pinned to this release (e.g. "1.19.0").
+        date: Infrahub release date in YYYY-MM-DD format.
+    """
+
+    infrahub: str
+    sdk: str
+    date: str
+
+
+@dataclass
+class VersionRange:
+    """Maps an Infrahub minor version series to its minimum required SDK version.
+
+    Args:
+        infrahub: Infrahub minor version pattern (e.g. "1.8.x").
+        min_sdk: Minimum required SDK version (e.g. "1.19.0").
+        date: Approximate release month (e.g. "March 2026").
+    """
+
+    infrahub: str
+    min_sdk: str
+    date: str
+
+
+@dataclass
+class PythonSupport:
+    """Maps an SDK version range to supported Python versions.
+
+    Args:
+        sdk_range: SDK version range description (e.g. ">= 1.17.0").
+        python_versions: Comma-separated Python versions (e.g. "3.10, 3.11, 3.12, 3.13, 3.14").
+    """
+
+    sdk_range: str
+    python_versions: str
+
+
+@dataclass
+class FeatureRequirement:
+    """Documents a feature that requires specific minimum versions.
+
+    Args:
+        feature: Feature name or description.
+        min_sdk: Minimum SDK version required.
+        min_infrahub: Minimum Infrahub version required.
+    """
+
+    feature: str
+    min_sdk: str
+    min_infrahub: str
+
+
+# Mapping of Infrahub minor version series to minimum SDK versions.
+# Update this list when a new Infrahub minor version is released.
+VERSION_RANGES: list[VersionRange] = [
+    VersionRange(infrahub="1.8.x", min_sdk="1.19.0", date="March 2026"),
+    VersionRange(infrahub="1.7.x", min_sdk="1.18.0", date="January 2026"),
+    VersionRange(infrahub="1.6.x", min_sdk="1.16.0", date="December 2025"),
+    VersionRange(infrahub="1.5.x", min_sdk="1.15.0", date="November 2025"),
+    VersionRange(infrahub="1.4.x", min_sdk="1.13.5", date="August 2025"),
+    VersionRange(infrahub="1.3.x", min_sdk="1.13.0", date="June 2025"),
+]
+
+# Detailed mapping of every Infrahub release to its pinned SDK version.
+# Update this list when a new Infrahub patch release is made.
+RELEASE_MAPPINGS: list[ReleaseMapping] = [
+    ReleaseMapping(infrahub="1.8.4", sdk="1.19.0", date="2026-04-02"),
+    ReleaseMapping(infrahub="1.8.3", sdk="1.19.0", date="2026-03-31"),
+    ReleaseMapping(infrahub="1.8.2", sdk="1.19.0", date="2026-03-25"),
+    ReleaseMapping(infrahub="1.8.1", sdk="1.19.0", date="2026-03-19"),
+    ReleaseMapping(infrahub="1.8.0", sdk="1.19.0", date="2026-03-16"),
+    ReleaseMapping(infrahub="1.7.7", sdk="1.18.1", date="2026-03-12"),
+    ReleaseMapping(infrahub="1.7.6", sdk="1.18.1", date="2026-02-25"),
+    ReleaseMapping(infrahub="1.7.5", sdk="1.18.1", date="2026-02-24"),
+    ReleaseMapping(infrahub="1.7.4", sdk="1.18.1", date="2026-02-03"),
+    ReleaseMapping(infrahub="1.7.3", sdk="1.18.1", date="2026-01-28"),
+    ReleaseMapping(infrahub="1.7.2", sdk="1.18.1", date="2026-01-27"),
+    ReleaseMapping(infrahub="1.7.1", sdk="1.18.1", date="2026-01-12"),
+    ReleaseMapping(infrahub="1.7.0", sdk="1.18.1", date="2026-01-09"),
+    ReleaseMapping(infrahub="1.6.3", sdk="1.17.0", date="2026-01-07"),
+    ReleaseMapping(infrahub="1.6.2", sdk="1.17.0", date="2025-12-22"),
+    ReleaseMapping(infrahub="1.6.1", sdk="1.17.0", date="2025-12-11"),
+    ReleaseMapping(infrahub="1.6.0", sdk="1.16.0", date="2025-12-01"),
+    ReleaseMapping(infrahub="1.5.5", sdk="1.15.1", date="2025-12-22"),
+    ReleaseMapping(infrahub="1.5.4", sdk="1.15.1", date="2025-12-16"),
+    ReleaseMapping(infrahub="1.5.3", sdk="1.15.1", date="2025-11-24"),
+    ReleaseMapping(infrahub="1.5.2", sdk="1.15.1", date="2025-11-18"),
+    ReleaseMapping(infrahub="1.5.1", sdk="1.15.1", date="2025-11-13"),
+    ReleaseMapping(infrahub="1.5.0", sdk="1.15.0", date="2025-11-10"),
+    ReleaseMapping(infrahub="1.4.1", sdk="1.13.5", date="2025-08-27"),
+    ReleaseMapping(infrahub="1.4.0", sdk="1.13.5", date="2025-08-26"),
+    ReleaseMapping(infrahub="1.3.3", sdk="1.13.3", date="2025-07-15"),
+    ReleaseMapping(infrahub="1.3.2", sdk="1.13.3", date="2025-06-30"),
+    ReleaseMapping(infrahub="1.3.1", sdk="1.13.2", date="2025-06-27"),
+    ReleaseMapping(infrahub="1.3.0", sdk="1.13.0", date="2025-06-12"),
+]
+
+# Python version support by SDK version range.
+PYTHON_SUPPORT: list[PythonSupport] = [
+    PythonSupport(sdk_range=">= 1.17.0", python_versions="3.10, 3.11, 3.12, 3.13, 3.14"),
+    PythonSupport(sdk_range="1.16.0", python_versions="3.10, 3.11, 3.12, 3.13"),
+    PythonSupport(sdk_range="1.13.0 - 1.15.x", python_versions="3.9, 3.10, 3.11, 3.12, 3.13"),
+]
+
+# Features that require specific minimum versions of both SDK and Infrahub.
+FEATURE_REQUIREMENTS: list[FeatureRequirement] = [
+    FeatureRequirement(feature="infrahubctl branch report", min_sdk="1.19.0", min_infrahub="1.7"),
+    FeatureRequirement(feature="FileObject support", min_sdk="1.19.0", min_infrahub="1.8"),
+    FeatureRequirement(feature="NumberPool support", min_sdk="1.13.0", min_infrahub="1.3"),
+]

docs/sidebars/sidebars-python-sdk.ts

@@ -37,6 +37,7 @@ const referenceItems = getItemsWithOrder(
   [
     'reference/config',
     'reference/templating',
+    'reference/compatibility',
   ],
   'reference',
 );

tasks.py

@@ -109,6 +109,37 @@ def _generate_infrahub_sdk_configuration_documentation() -> None:
     MDXDocPage(page=page, output_path=output_path).to_mdx()
 
 
+def _generate_infrahub_sdk_compatibility_documentation() -> None:
+    """Generate documentation for the Infrahub SDK compatibility matrix."""
+    from docs.docs_generation.compatibility import (
+        FEATURE_REQUIREMENTS,
+        PYTHON_SUPPORT,
+        RELEASE_MAPPINGS,
+        VERSION_RANGES,
+    )
+    from docs.docs_generation.content_gen_methods import Jinja2DocContentGenMethod
+    from docs.docs_generation.pages import DocPage, MDXDocPage
+    from infrahub_sdk.template import Jinja2Template
+
+    print(" - Generate Infrahub SDK compatibility documentation")
+    page = DocPage(
+        content_gen_method=Jinja2DocContentGenMethod(
+            template=Jinja2Template(
+                template=Path("sdk_compatibility.j2"),
+                template_directory=DOCUMENTATION_DIRECTORY / "_templates",
+            ),
+            template_variables={
+                "version_ranges": VERSION_RANGES,
+                "release_mappings": RELEASE_MAPPINGS,
+                "python_support": PYTHON_SUPPORT,
+                "feature_requirements": FEATURE_REQUIREMENTS,
+            },
+        ),
+    )
+    output_path = DOCUMENTATION_DIRECTORY / "docs" / "python-sdk" / "reference" / "compatibility.mdx"
+    MDXDocPage(page=page, output_path=output_path).to_mdx()
+
+
 def _generate_infrahub_sdk_template_documentation() -> None:
     """Generate documentation for the Infrahub SDK template reference."""
     from docs.docs_generation.content_gen_methods import Jinja2DocContentGenMethod
@@ -360,6 +391,7 @@ def generate_python_sdk(context: Context) -> None:
     """Generate documentation for the Python SDK."""
     _generate_infrahub_sdk_configuration_documentation()
     _generate_infrahub_sdk_template_documentation()
+    _generate_infrahub_sdk_compatibility_documentation()
     _generate_sdk_api_docs(context)