From 22f2ff9c6742f9064b80c2d08b18180dec0621c6 Mon Sep 17 00:00:00 2001 From: Mark Coleman Date: Wed, 15 Oct 2025 13:11:05 +0200 Subject: [PATCH 1/2] Update docs for 0.4.0 --- README.md | 19 +++++++++++++++++-- docs/branching.md | 24 ++++++++++++++++++++++++ docs/index.md | 10 ++++++++-- 3 files changed, 49 insertions(+), 4 deletions(-) create mode 100644 docs/branching.md diff --git a/README.md b/README.md index 3c33eb5..767679e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ You can find further documentation [here](https://github.com/netboxlabs/netbox-c ## Requirements -* NetBox v4.4 or later +* NetBox v4.4.0 or later +* (Optional) NetBox Branching 0.7.1 or later ## Installation @@ -36,6 +37,20 @@ $ ./manage.py migrate sudo systemctl restart netbox netbox-rq ``` +> [!NOTE] +> If you are using NetBox Custom Objects with NetBox Branching, you need to insert the following into your `configuration.py`. See the docs for a full description of how NetBox Custom Objects currently works with NetBox Branching. + +``` +PLUGINS_CONFIG = { + 'netbox_branching': { + 'exempt_models': [ + 'netbox_custom_objects.customobjecttype', + 'netbox_custom_objects.customobjecttypefield', + ], + }, +} +``` + ## Known Limitations -NetBox Custom Objects is under active development and some features may not be complete as designed. The best place to look for the latest list of known limitations is the [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) list on the GitHub repository. +NetBox Custom Objects is now GA which means you can use it in production and migrations to future versions will work. There are many up and coming features including GraphQL support - the best place to see what's on the way is the [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) list on the GitHub repository. diff --git a/docs/branching.md b/docs/branching.md new file mode 100644 index 0000000..041178c --- /dev/null +++ b/docs/branching.md @@ -0,0 +1,24 @@ +# Using NetBox Custom Objects with NetBox Branching + +As of version 0.4.0 Custom Objects is _compatible_ with NetBox Branching, but not fully supported. This means that users can safely use both plugins together, but there are some caveats to be aware of. See below to learn how each of the Custom Objects models interacts with NetBox Branching. + +> [!NOTE] +> We are working towards fully support for Custom Objects on branches. Keep an eye on the GitHub issues for updates ahead of future releases. + +> [!TIP] +> If you have any questions the best place to start is on the GitHub [discussions](https://github.com/netboxlabs/netbox-custom-objects/discussions). If you are a NetBox Labs customer, you can also contact support. + +## Custom Object Types and Custom Object Type Fields + +Custom Object Types and Custom Object Type fields can be created, updated and deleted on branches, however the changes made on branches will be applied in main. This allows Custom Objects and Branching to be used safely alongside each other, but users should be aware of what this means. + +- When you are in an activated branch any creates, updates and deletes you perform on Custom Object Types and Custom Object Type Fields will not show up in the Diff or Changes Ahead views +- Although you're in an activated branch, these changes will be made directly to main +- Typically it will be NetBox admins who are altering Custom Object Types and Custom Object Type Fields - we recommend that you experiment in your staging instance until you are satisfied with the modelling and then move them into prod + +## Custom Objects + +Changes to Custom Objects on branches are disallowed. + +- When in an activated branch, users will still be able to see the available Custom Object Types and any Custom Objects that were brought into the branch upon branch creation, but will not be able to interact with them to affect changes on the branch. +- This approach was chosen to make sure that users can safely use both Custom Objects and Branching together, while we are working on fuller support. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 552448d..3e060c3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,10 +2,16 @@ [NetBox](https://github.com/netbox-community/netbox) is the world's leading source of truth for infrastructure, featuring an extensive data model. Sometimes it can be useful to extend the NetBox data model to fit specific organizational needs. The Custom Objects plugin introduces a new paradigm for NetBox to help overcome these challenges, allowing NetBox adminstrators to extend the NetBox data model without writing a line of code. -For additional documentation on the REST API, go [here](api.md). +- For additional documentation on the REST API, go [here](api.md). +- For information about using Custom Objects with NetBox Branching, go [here](branching.md) > [!TIP] -> NetBox Custom Objects is still in Public Preview. If you hit any problems please check the [exiting issues](https://github.com/netboxlabs/netbox-custom-objects/issues) before creating a new one. If you're unsure, start a [discussion](https://github.com/netboxlabs/netbox-custom-objects/discussions). +> If you hit any problems please check the [exiting issues](https://github.com/netboxlabs/netbox-custom-objects/issues) before creating a new one. If you're unsure, start a [discussion](https://github.com/netboxlabs/netbox-custom-objects/discussions). + + +> [!TIP] +> If you are using Custom Objects with Custom Scripts or Plugins you need to use Django's `AppConfig.get_model` to retrieve Custom Object Types: [https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.get_model](https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.get_model) +> Pass in the plugin name (`netbox_custom_objects`) and the name of the Custom Object (e.g. `dhcp_scope`) to return the correct object. ## Features From 72161d7ef0beb10363eb1c59b9f426555803e956 Mon Sep 17 00:00:00 2001 From: Mark Coleman Date: Wed, 15 Oct 2025 16:00:25 +0200 Subject: [PATCH 2/2] Resolve PR feedback --- README.md | 2 +- docs/branching.md | 2 +- docs/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 767679e..8293f3d 100644 --- a/README.md +++ b/README.md @@ -53,4 +53,4 @@ PLUGINS_CONFIG = { ## Known Limitations -NetBox Custom Objects is now GA which means you can use it in production and migrations to future versions will work. There are many up and coming features including GraphQL support - the best place to see what's on the way is the [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) list on the GitHub repository. +NetBox Custom Objects is now Generally Available which means you can use it in production and migrations to future versions will work. There are many upcoming features including GraphQL support - the best place to see what's on the way is the [issues](https://github.com/netboxlabs/netbox-custom-objects/issues) list on the GitHub repository. diff --git a/docs/branching.md b/docs/branching.md index 041178c..416fb2b 100644 --- a/docs/branching.md +++ b/docs/branching.md @@ -3,7 +3,7 @@ As of version 0.4.0 Custom Objects is _compatible_ with NetBox Branching, but not fully supported. This means that users can safely use both plugins together, but there are some caveats to be aware of. See below to learn how each of the Custom Objects models interacts with NetBox Branching. > [!NOTE] -> We are working towards fully support for Custom Objects on branches. Keep an eye on the GitHub issues for updates ahead of future releases. +> We are working towards full support for Custom Objects on branches. Keep an eye on the GitHub issues for updates ahead of future releases. > [!TIP] > If you have any questions the best place to start is on the GitHub [discussions](https://github.com/netboxlabs/netbox-custom-objects/discussions). If you are a NetBox Labs customer, you can also contact support. diff --git a/docs/index.md b/docs/index.md index 3e060c3..ed16245 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ - For information about using Custom Objects with NetBox Branching, go [here](branching.md) > [!TIP] -> If you hit any problems please check the [exiting issues](https://github.com/netboxlabs/netbox-custom-objects/issues) before creating a new one. If you're unsure, start a [discussion](https://github.com/netboxlabs/netbox-custom-objects/discussions). +> If you hit any problems please check the [existing issues](https://github.com/netboxlabs/netbox-custom-objects/issues) before creating a new one. If you're unsure, start a [discussion](https://github.com/netboxlabs/netbox-custom-objects/discussions). > [!TIP]