From f510e4042818053aeac3a95c7f6a49179dc2de14 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Mon, 29 Dec 2025 12:39:51 -0500 Subject: [PATCH] Closes #21047: Add compatibility matrix to plugin setup instructions (#21048) --- docs/plugins/development/index.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/plugins/development/index.md b/docs/plugins/development/index.md index 0acf5f90a..78b1460c7 100644 --- a/docs/plugins/development/index.md +++ b/docs/plugins/development/index.md @@ -74,7 +74,7 @@ The plugin source directory contains all the actual Python code and other resour The `PluginConfig` class is a NetBox-specific wrapper around Django's built-in [`AppConfig`](https://docs.djangoproject.com/en/stable/ref/applications/) class. It is used to declare NetBox plugin functionality within a Python package. Each plugin should provide its own subclass, defining its name, metadata, and default and required configuration parameters. An example is below: -```python +```python title="__init__.py" from netbox.plugins import PluginConfig class FooBarConfig(PluginConfig): @@ -151,7 +151,7 @@ Any additional apps must be installed within the same Python environment as NetB An example `pyproject.toml` is below: -``` +```toml title="pyproject.toml" # See PEP 518 for the spec of this file # https://www.python.org/dev/peps/pep-0518/ @@ -179,11 +179,24 @@ classifiers=[ ] requires-python = ">=3.10.0" - ``` Many of these are self-explanatory, but for more information, see the [pyproject.toml documentation](https://packaging.python.org/en/latest/specifications/pyproject-toml/). +## Compatibility Matrix + +Consider adding a file named `COMPATIBILITY.md` to your plugin project root (alongside `pyproject.toml`). This file should contain a table listing the minimum and maximum supported versions of NetBox (`min_version` and `max_version`) for each release. This serves as a handy reference for users who are upgrading from a previous version of your plugin. An example is shown below: + +```markdown title="COMPATIBILITY.md" +# Compatibility Matrix + +| Release | Minimum NetBox Version | Maximum NetBox Version | +|---------|------------------------|------------------------| +| 0.2.0 | 4.4.0 | 4.5.x | +| 0.1.1 | 4.3.0 | 4.4.x | +| 0.1.0 | 4.3.0 | 4.4.x | +``` + ## Create a Virtual Environment It is strongly recommended to create a Python [virtual environment](https://docs.python.org/3/tutorial/venv.html) for the development of your plugin, as opposed to using system-wide packages. This will afford you complete control over the installed versions of all dependencies and avoid conflict with system packages. This environment can live wherever you'd like;however, it should be excluded from revision control. (A popular convention is to keep all virtual environments in the user's home directory, e.g. `~/.virtualenvs/`.)