#569 - add check for minimum netbox/branching versions for branching support

docs/branching.md

@@ -3,9 +3,9 @@
 When using Custom Objects together with NetBox Branching, the following minimum versions are required:
 
 - NetBox >= 4.6.2
-- netbox-branching >= 1.1.0
+- netbox-branching >= 1.0.4
 
-If you do not use branching, the standard compatibility matrix in `COMPATIBILITY.md` applies.
+These requirements are only enforced when `netbox_branching` is present in `PLUGINS`. If you do not use branching, the standard compatibility matrix in `COMPATIBILITY.md` applies. A Django system check (`netbox_custom_objects.E001` / `E002`) will fail at startup if the combination is misconfigured.
 
 As of version 0.4.0, Custom Objects is _compatible_ with [NetBox Branching](https://netboxlabs.com/docs/extensions/branching/), but not yet fully supported. Users can safely run both plugins together, but there are some caveats to be aware of. See below for how each Custom Objects model interacts with NetBox Branching.
 

netbox_custom_objects/__init__.py

@@ -373,6 +373,11 @@ def ready(self):
         # model is registered (must happen exactly once, before get_model() runs).
         install_clear_cache_suppressor()
 
+        # Register Django system checks (import triggers @register).  These
+        # enforce the conditional NetBox/netbox-branching version floors that
+        # PluginConfig's static min_version/max_version can't express.
+        from . import checks  # noqa: F401
+
         from .models import CustomObjectType
         from netbox_custom_objects.api.serializers import get_serializer_class
 

netbox_custom_objects/checks.py

@@ -0,0 +1,75 @@
+"""Django system checks.
+
+Enforces conditional version floors that PluginConfig's static
+``min_version``/``max_version`` can't express: when netbox-branching is
+installed, NetBox and netbox-branching versions are pinned tighter because
+the branching integration relies on APIs that only landed in those releases:
+
+- ``serializer_resolver`` / ``register_serializer_resolver`` — NetBox 4.6.2
+- ``register_branching_resolver``, ``register_objectchange_field_migrator``,
+  and the ``squash_dependency_graph_built`` signal — netbox-branching 1.0.4
+
+Users who never install netbox-branching keep the broader compatibility
+window declared by PluginConfig.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from django.apps import apps
+from django.conf import settings
+from django.core.checks import Error, Warning, register
+from packaging.version import InvalidVersion, Version
+
+
+# Version floors enforced only when netbox-branching is installed.
+REQUIRED_NETBOX_VERSION = '4.6.2'
+REQUIRED_BRANCHING_VERSION = '1.0.4'
+
+
+@register()
+def check_branching_compatibility(app_configs, **kwargs):
+    """Enforce branching-only version floors; no-op without netbox-branching."""
+    if not apps.is_installed('netbox_branching'):
+        return []
+
+    errors = []
+
+    try:
+        netbox_version = Version(settings.RELEASE.version)
+        if netbox_version < Version(REQUIRED_NETBOX_VERSION):
+            errors.append(Error(
+                f'netbox-custom-objects requires NetBox >= {REQUIRED_NETBOX_VERSION} '
+                f'when netbox-branching is installed (detected {netbox_version}).',
+                hint='Upgrade NetBox, or remove netbox-branching from PLUGINS '
+                     'if you do not need branching support for custom objects.',
+                id='netbox_custom_objects.E001',
+            ))
+    except (AttributeError, InvalidVersion):
+        pass  # settings.RELEASE missing/unparseable — other checks surface it
+
+    try:
+        branching_version = Version(_pkg_version('netbox-branching'))
+        if branching_version < Version(REQUIRED_BRANCHING_VERSION):
+            errors.append(Error(
+                f'netbox-custom-objects requires netbox-branching >= '
+                f'{REQUIRED_BRANCHING_VERSION} (detected {branching_version}).',
+                hint=f'Upgrade with: pip install "netbox-branching>={REQUIRED_BRANCHING_VERSION}"',
+                id='netbox_custom_objects.E002',
+            ))
+    except PackageNotFoundError:
+        # netbox-branching is an installed app but its distribution metadata
+        # isn't discoverable (e.g. an editable checkout without dist-info), so
+        # the version floor can't be enforced.  Warn rather than silently pass
+        # so an incompatible checkout doesn't slip through unnoticed.
+        errors.append(Warning(
+            'netbox-branching is installed but its version could not be '
+            f'determined, so the >= {REQUIRED_BRANCHING_VERSION} requirement '
+            'cannot be verified.',
+            hint='If using an editable install, ensure its dist-info metadata '
+                 'is present (reinstall with `pip install -e`).',
+            id='netbox_custom_objects.W001',
+        ))
+    except InvalidVersion:
+        pass  # unparseable version string — skip rather than emit a confusing error
+
+    return errors

netbox_custom_objects/tests/test_checks.py

@@ -0,0 +1,87 @@
+"""
+Tests for the conditional netbox-branching version system check
+(``netbox_custom_objects.checks.check_branching_compatibility``).
+
+The check is pure version-comparison logic gated on whether netbox-branching
+is installed, so every branch is exercised by mocking its three inputs:
+``apps.is_installed``, ``settings.RELEASE``, and the importlib.metadata
+``version`` lookup.  No database is required, hence ``SimpleTestCase``.
+"""
+from importlib.metadata import PackageNotFoundError
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from django.test import SimpleTestCase
+
+from netbox_custom_objects import checks
+
+
+def _run(*, branching_installed=True, netbox_version='4.6.2', branching_version='1.0.4'):
+    """Invoke the check with each input mocked.
+
+    ``netbox_version`` / ``branching_version`` may be a version string, or an
+    Exception instance/class to simulate the failure paths (a missing
+    ``settings.RELEASE``, an unparseable version, or ``PackageNotFoundError``).
+    """
+    if isinstance(netbox_version, str):
+        release = SimpleNamespace(version=netbox_version)
+    else:
+        # No RELEASE attribute -> accessing settings.RELEASE raises AttributeError.
+        release = None
+
+    def fake_pkg_version(_name):
+        if isinstance(branching_version, str):
+            return branching_version
+        raise branching_version  # Exception instance or class
+
+    settings_stub = SimpleNamespace()
+    if release is not None:
+        settings_stub.RELEASE = release
+
+    with patch.object(checks.apps, 'is_installed', return_value=branching_installed), \
+         patch.object(checks, 'settings', settings_stub), \
+         patch.object(checks, '_pkg_version', fake_pkg_version):
+        return checks.check_branching_compatibility(app_configs=None)
+
+
+def _ids(errors):
+    return {e.id for e in errors}
+
+
+class CheckBranchingCompatibilityTest(SimpleTestCase):
+    def test_no_branching_is_noop(self):
+        """Without netbox-branching installed, the check returns no messages."""
+        self.assertEqual(_run(branching_installed=False), [])
+
+    def test_both_versions_satisfied(self):
+        """Versions at the floor produce no errors."""
+        self.assertEqual(_run(netbox_version='4.6.2', branching_version='1.0.4'), [])
+
+    def test_newer_versions_satisfied(self):
+        self.assertEqual(_run(netbox_version='4.7.0', branching_version='1.1.0'), [])
+
+    def test_netbox_too_old(self):
+        errors = _run(netbox_version='4.6.1', branching_version='1.0.4')
+        self.assertEqual(_ids(errors), {'netbox_custom_objects.E001'})
+
+    def test_branching_too_old(self):
+        errors = _run(netbox_version='4.6.2', branching_version='1.0.3')
+        self.assertEqual(_ids(errors), {'netbox_custom_objects.E002'})
+
+    def test_both_too_old(self):
+        errors = _run(netbox_version='4.5.0', branching_version='0.9.0')
+        self.assertEqual(_ids(errors), {'netbox_custom_objects.E001', 'netbox_custom_objects.E002'})
+
+    def test_missing_release_skips_netbox_check(self):
+        """A missing settings.RELEASE skips E001 but still evaluates branching."""
+        errors = _run(netbox_version=AttributeError, branching_version='1.0.3')
+        self.assertEqual(_ids(errors), {'netbox_custom_objects.E002'})
+
+    def test_unparseable_netbox_version_skips_netbox_check(self):
+        errors = _run(netbox_version='not-a-version', branching_version='1.0.4')
+        self.assertEqual(errors, [])
+
+    def test_unresolvable_branching_version_warns(self):
+        """An installed-but-unmeasurable branching dist warns rather than passing silently."""
+        errors = _run(netbox_version='4.6.2', branching_version=PackageNotFoundError())
+        self.assertEqual(_ids(errors), {'netbox_custom_objects.W001'})

pyproject.toml

@@ -32,6 +32,11 @@ dependencies = [
 [project.optional-dependencies]
 dev = ["check-manifest", "mkdocs", "mkdocs-material", "ruff"]
 test = ["coverage", "pytest", "pytest-cov"]
+# Install with `pip install "netboxlabs-netbox-custom-objects[branching]"` when
+# pairing this plugin with netbox-branching.  Note: this extra also implies a
+# stricter NetBox version requirement (>= 4.6.2), which is enforced at startup
+# by netbox_custom_objects.checks rather than declared here.
+branching = ["netbox-branching>=1.0.4"]
 
 [project.urls]
 "Homepage" = "https://netboxlabs.com/"