Merge pull request #14636 from netbox-community/develop

Release v3.7.0

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -23,7 +23,7 @@ body:
     attributes:
       label: NetBox Version
       description: What version of NetBox are you currently running?
-      placeholder: v3.6.9
+      placeholder: v3.7.0
     validations:
       required: true
   - type: dropdown

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -14,7 +14,7 @@ body:
     attributes:
       label: NetBox version
       description: What version of NetBox are you currently running?
-      placeholder: v3.6.9
+      placeholder: v3.7.0
     validations:
       required: true
   - type: dropdown

base_requirements.txt

@@ -53,8 +53,7 @@ django-tables2
 
 # User-defined tags for objects
 # https://github.com/jazzband/django-taggit/blob/master/CHANGELOG.rst
-# TODO: Upgrade to v5.0 for NetBox v3.7 beta
-django-taggit<5.0
+django-taggit
 
 # A Django field for representing time zones
 # https://github.com/mfogel/django-timezone-field/
@@ -90,9 +89,8 @@ gunicorn
 Jinja2
 
 # Simple markup language for rendering HTML
-# https://python-markdown.github.io/change_log/
-# mkdocs currently requires Markdown v3.3
-Markdown<3.4
+# https://python-markdown.github.io/changelog/
+Markdown
 
 # File inclusion plugin for Python-Markdown
 # https://github.com/cmacmackin/markdown-include
@@ -126,10 +124,6 @@ PyYAML
 # https://github.com/psf/requests/blob/main/HISTORY.md
 requests
 
-# Sentry SDK
-# https://github.com/getsentry/sentry-python/blob/master/CHANGELOG.md
-sentry-sdk
-
 # Social authentication framework
 # https://github.com/python-social-auth/social-core/blob/master/CHANGELOG.md
 social-auth-core

docs/administration/error-reporting.md

@@ -4,27 +4,15 @@
 
 ### Enabling Error Reporting
 
-NetBox supports native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, simply set `SENTRY_ENABLED` to True in `configuration.py`. Errors will be sent to a Sentry ingestor maintained by the NetBox team for analysis.
-
-```python
-SENTRY_ENABLED = True
-```
-
-### Using a Custom DSN
-
-If you prefer instead to use your own Sentry ingestor, you'll need to first create a new project under your Sentry account to represent your NetBox deployment and obtain its corresponding data source name (DSN). This looks like a URL similar to the example below:
-
-```
-https://examplePublicKey@o0.ingest.sentry.io/0
-```
-
-Once you have obtained a DSN, configure Sentry in NetBox's `configuration.py` file with the following parameters:
+NetBox supports native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, set `SENTRY_ENABLED` to True and define your unique [data source name (DSN)](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/) in `configuration.py`.
 
 ```python
 SENTRY_ENABLED = True
 SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0"
 ```
 
+Setting `SENTRY_ENABLED` to False will disable the Sentry integration.
+
 ### Assigning Tags
 
 You can optionally attach one or more arbitrary tags to the outgoing error reports if desired by setting the `SENTRY_TAGS` parameter:

docs/configuration/data-validation.md

@@ -87,3 +87,24 @@ The following colors are supported:
 * `gray`
 * `black`
 * `white`
+
+---
+
+## PROTECTION_RULES
+
+!!! tip "Dynamic Configuration Parameter"
+
+This is a mapping of models to [custom validators](../customization/custom-validation.md) against which an object is evaluated immediately prior to its deletion. If validation fails, the object is not deleted. An example is provided below:
+
+```python
+PROTECTION_RULES = {
+    "dcim.site": [
+        {
+            "status": {
+                "eq": "decommissioning"
+            }
+        },
+        "my_plugin.validators.Validator1",
+    ]
+}
+```

docs/configuration/error-reporting.md

@@ -18,6 +18,9 @@ Default: False
 
 Set to True to enable automatic error reporting via [Sentry](https://sentry.io/).
 
+!!! note
+    The `sentry-sdk` Python package is required to enable Sentry integration.
+
 ---
 
 ## SENTRY_SAMPLE_RATE

docs/configuration/miscellaneous.md

@@ -80,6 +80,17 @@ changes in the database indefinitely.
 
 ---
 
+## CHANGELOG_SKIP_EMPTY_CHANGES
+
+Default: True
+
+If enabled, a change log record will not be created when an object is updated without any changes to its existing field values.
+
+!!! note
+    The object's `last_updated` field will always reflect the time of the most recent update, regardless of this parameter.
+
+---
+
 ## DATA_UPLOAD_MAX_MEMORY_SIZE
 
 Default: `2621440` (2.5 MB)
@@ -92,9 +103,12 @@ The maximum size (in bytes) of an incoming HTTP request (i.e. `GET` or `POST` da
 
 !!! tip "Dynamic Configuration Parameter"
 
-Default: False
+Default: True
+
+By default, NetBox will prevent the creation of duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This validation can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to False.
 
-By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True.
+!!! info "Changed in v3.7"
+    The default value for this parameter was changed from False to True in NetBox v3.7.
 
 ---
 

docs/configuration/required-parameters.md

@@ -59,10 +59,7 @@ DATABASE = {
 
 ## REDIS
 
-[Redis](https://redis.io/) is an in-memory data store similar to memcached. While Redis has been an optional component of
-NetBox since the introduction of webhooks in version 2.4, it is required starting in 2.6 to support NetBox's caching
-functionality (as well as other planned features). In 2.7, the connection settings were broken down into two sections for
-task queuing and caching, allowing the user to connect to different Redis instances/databases per feature.
+[Redis](https://redis.io/) is a lightweight in-memory data store similar to memcached. NetBox employs Redis for background task queuing and other features.
 
 Redis is configured using a configuration setting similar to `DATABASE` and these settings are the same for both of the `tasks` and `caching` subsections:
 
@@ -81,15 +78,15 @@ REDIS = {
     'tasks': {
         'HOST': 'redis.example.com',
         'PORT': 1234,
-        'USERNAME': 'netbox'
+        'USERNAME': 'netbox',
         'PASSWORD': 'foobar',
         'DATABASE': 0,
         'SSL': False,
     },
     'caching': {
         'HOST': 'localhost',
         'PORT': 6379,
-        'USERNAME': ''
+        'USERNAME': '',
         'PASSWORD': '',
         'DATABASE': 1,
         'SSL': False,

docs/customization/custom-fields.md

@@ -40,14 +40,22 @@ Related custom fields can be grouped together within the UI by assigning each th
 
 This parameter has no effect on the API representation of custom field data.
 
-### Visibility
+### Visibility & Editing
 
-When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI.
+!!! info "This feature was improved in NetBox v3.7."
 
-* **Read/write** (default): The custom field is included when viewing and editing objects.
-* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.)
+When creating a custom field, users can control the conditions under which it may be displayed and edited within the NetBox user interface. The following choices are available for controlling the display of a custom field on an object:
+
+* **Always** (default): The custom field is included when viewing an object.
+* **If Set**: The custom field is included only if a value has been defined for the object.
 * **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users.
 
+Additionally, the following options are available for controlling whether custom field values can be altered within the NetBox UI:
+
+* **Yes** (default): The custom field's value may be modified when editing an object.
+* **No**: The custom field is displayed for reference when editing an object, but its value may not be modified.
+* **Hidden**: The custom field is not displayed when editing an object.
+
 Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API.
 
 ### Validation

docs/customization/custom-validation.md

@@ -26,6 +26,8 @@ The `CustomValidator` class supports several validation types:
 * `regex`: Application of a [regular expression](https://en.wikipedia.org/wiki/Regular_expression)
 * `required`: A value must be specified
 * `prohibited`: A value must _not_ be specified
+* `eq`: A value must be equal to the specified value
+* `neq`: A value must _not_ be equal to the specified value
 
 The `min` and `max` types should be defined for numeric values, whereas `min_length`, `max_length`, and `regex` are suitable for character strings (text values). The `required` and `prohibited` validators may be used for any field, and should be passed a value of `True`.
 

docs/development/application-registry.md

@@ -31,7 +31,7 @@ A dictionary of particular features (e.g. custom fields) mapped to the NetBox mo
         'dcim': ['site', 'rack', 'devicetype', ...],
         ...
     },
-    'webhooks': {
+    'event_rules': {
         'extras': ['configcontext', 'tag', ...],
         'dcim': ['site', 'rack', 'devicetype', ...],
     },
@@ -41,6 +41,10 @@ A dictionary of particular features (e.g. custom fields) mapped to the NetBox mo
 
 Supported model features are listed in the [features matrix](./models.md#features-matrix).
 
+### `models`
+
+This key lists all models which have been registered in NetBox which are not designated for private use. (Setting `_netbox_private` to True on a model excludes it from this list.) As with individual features under `model_features`, models are organized by app label.
+
 ### `plugins`
 
 This store maintains all registered items for plugins, such as navigation menus, template extensions, etc.
@@ -49,6 +53,10 @@ This store maintains all registered items for plugins, such as navigation menus,
 
 A dictionary mapping each model (identified by its app and label) to its search index class, if one has been registered for it.
 
+### `tables`
+
+A dictionary mapping table classes to lists of extra columns that have been registered by plugins using the `register_table_column()` utility function. Each column is defined as a tuple of name and column instance.
+
 ### `views`
 
 A hierarchical mapping of registered views for each model. Mappings are added using the `register_model_view()` decorator, and URLs paths can be generated from these using `get_model_urls()`.

docs/development/extending-models.md

@@ -2,12 +2,25 @@
 
 Below is a list of tasks to consider when adding a new field to a core model.
 
-## 1. Generate and run database migrations
+## 1. Add the field to the model class
+
+Add the field to the model, taking care to address any of the following conditions.
+
+* When adding a GenericForeignKey field, also add an index under `Meta` for its two concrete fields. For example:
+
+    ```python
+    class Meta:
+        indexes = (
+            models.Index(fields=('object_type', 'object_id')),
+        )
+    ```
+
+## 2. Generate and run database migrations
 
 [Django migrations](https://docs.djangoproject.com/en/stable/topics/migrations/) are used to express changes to the database schema. In most cases, Django can generate these automatically, however very complex changes may require manual intervention. Always remember to specify a short but descriptive name when generating a new migration.
 
 ```
-./manage.py makemigrations <app> -n <name>
+./manage.py makemigrations <app> -n <name> --no-header
 ./manage.py migrate
 ```
 
@@ -16,7 +29,7 @@ Where possible, try to merge related changes into a single migration. For exampl
 !!! warning "Do not alter existing migrations"
     Migrations can only be merged within a release. Once a new release has been published, its migrations cannot be altered (other than for the purpose of correcting a bug).
 
-## 2. Add validation logic to `clean()`
+## 3. Add validation logic to `clean()`
 
 If the new field introduces additional validation requirements (beyond what's included with the field itself), implement them in the model's `clean()` method. Remember to call the model's original method using `super()` before or after your custom validation as appropriate:
 
@@ -31,15 +44,15 @@ class Foo(models.Model):
             raise ValidationError()
 ```
 
-## 3. Update relevant querysets
+## 4. Update relevant querysets
 
 If you're adding a relational field (e.g. `ForeignKey`) and intend to include the data when retrieving a list of objects, be sure to include the field using `prefetch_related()` as appropriate. This will optimize the view and avoid extraneous database queries.
 
-## 4. Update API serializer
+## 5. Update API serializer
 
 Extend the model's API serializer in `<app>.api.serializers` to include the new field. In most cases, it will not be necessary to also extend the nested serializer, which produces a minimal representation of the model.
 
-## 5. Add fields to forms
+## 6. Add fields to forms
 
 Extend any forms to include the new field(s) as appropriate. These are found under the `forms/` directory within each app. Common forms include:
 
@@ -48,23 +61,23 @@ Extend any forms to include the new field(s) as appropriate. These are found und
 * **CSV import** - The form used when bulk importing objects in CSV format
 * **Filter** - Displays the options available for filtering a list of objects (both UI and API)
 
-## 6. Extend object filter set
+## 7. Extend object filter set
 
 If the new field should be filterable, add it to the `FilterSet` for the model. If the field should be searchable, remember to query it in the FilterSet's `search()` method.
 
-## 7. Add column to object table
+## 8. Add column to object table
 
 If the new field will be included in the object list view, add a column to the model's table. For simple fields, adding the field name to `Meta.fields` will be sufficient. More complex fields may require declaring a custom column. Also add the field name to `default_columns` if the column should be present in the table by default.
 
-## 8. Update the SearchIndex
+## 9. Update the SearchIndex
 
 Where applicable, add the new field to the model's SearchIndex for inclusion in global search.
 
-## 9. Update the UI templates
+## 10. Update the UI templates
 
 Edit the object's view template to display the new field. There may also be a custom add/edit form template that needs to be updated.
 
-## 10. Create/extend test cases
+## 11. Create/extend test cases
 
 Create or extend the relevant test cases to verify that the new field and any accompanying validation logic perform as expected. This is especially important for relational fields. NetBox incorporates various test suites, including:
 
@@ -74,8 +87,8 @@ Create or extend the relevant test cases to verify that the new field and any ac
 * Model tests
 * View tests
 
-Be diligent to ensure all of the relevant test suites are adapted or extended as necessary to test any new functionality.
+Be diligent to ensure all the relevant test suites are adapted or extended as necessary to test any new functionality.
 
-## 11. Update the model's documentation
+## 12. Update the model's documentation
 
 Each model has a dedicated page in the documentation, at `models/<app>/<model>.md`. Update this file to include any relevant information about the new field.