Skip to content

Commit

Permalink
Merge pull request #14636 from netbox-community/develop
Browse files Browse the repository at this point in the history
Release v3.7.0
  • Loading branch information
jeremystretch authored Dec 29, 2023
2 parents 0c06725 + d99e651 commit 7b90481
Show file tree
Hide file tree
Showing 400 changed files with 81,924 additions and 3,878 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 3 additions & 9 deletions base_requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
18 changes: 3 additions & 15 deletions docs/administration/error-reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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://[email protected]/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://[email protected]/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:
Expand Down
21 changes: 21 additions & 0 deletions docs/configuration/data-validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
}
```
3 changes: 3 additions & 0 deletions docs/configuration/error-reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 16 additions & 2 deletions docs/configuration/miscellaneous.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.

---

Expand Down
9 changes: 3 additions & 6 deletions docs/configuration/required-parameters.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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,
Expand Down
16 changes: 12 additions & 4 deletions docs/customization/custom-fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/customization/custom-validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
10 changes: 9 additions & 1 deletion docs/development/application-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -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', ...],
},
Expand All @@ -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.
Expand All @@ -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()`.
39 changes: 26 additions & 13 deletions docs/development/extending-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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.
Loading

0 comments on commit 7b90481

Please sign in to comment.