From a5106b858d626f5dabaff8c49fc971b08db07089 Mon Sep 17 00:00:00 2001 From: Martin Hauser Date: Tue, 1 Apr 2025 07:23:42 +0200 Subject: [PATCH 1/4] docs(upgrading): Add dependency matrix for NetBox versions Adds a dependency matrix to the upgrade guide, detailing supported Python, PostgreSQL, and Redis versions for each NetBox release. This helps users verify compatibility before upgrading. Fixes #18733 --- docs/installation/upgrading.md | 51 ++++++++++++++++++++++++++++++---- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index e6d05738f..993d3987d 100644 --- a/docs/installation/upgrading.md +++ b/docs/installation/upgrading.md @@ -17,11 +17,52 @@ Prior to upgrading your NetBox instance, be sure to carefully review all [releas NetBox requires the following dependencies: -| Dependency | Supported Versions | -|------------|--------------------| -| Python | 3.10, 3.11, 3.12 | -| PostgreSQL | 13+ | -| Redis | 4.0+ | +=== "Current Version" + + | Dependency | Supported Versions | + |------------|--------------------| + | Python | 3.10, 3.11, 3.12 | + | PostgreSQL | 13+ | + | Redis | 4.0+ | + +=== "All Versions" + + | NetBox Version | Python min | Python max | PostgreSQL min | Redis min | Documentation | + |:--------------:|:----------:|:----------:|:--------------:|:---------:|:-------------------------------------------------------------------------------------------------:| + | 4.2 | 3.10 | 3.12 | **13** | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.2.0/docs/installation/index.md) | + | 4.1 | 3.10 | 3.12 | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.1.0/docs/installation/index.md) | + | 4.0 | **3.10** | **3.12** | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.0.0/docs/installation/index.md) | + | 3.7 | 3.8 | 3.11 | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.7.0/docs/installation/index.md) | + | 3.6 | 3.8 | **3.11** | **12** | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.6.0/docs/installation/index.md) | + | 3.5 | 3.8 | 3.10 | 11 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.5.0/docs/installation/index.md) | + | 3.4 | 3.8 | 3.10 | **11** | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.4.0/docs/installation/index.md) | + | 3.3 | 3.8 | 3.10 | 10 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.3.0/docs/installation/index.md) | + | 3.2 | **3.8** | **3.10** | 10 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.2.0/docs/installation/index.md) | + | 3.1 | 3.7 | 3.9 | **10** | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.1.0/docs/installation/index.md) | + | 3.0 | **3.7** | 3.9 | 9.6 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.0.0/docs/installation/index.md) | + | 2.11 | 3.6 | **3.9** | 9.6 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v2.11.0/docs/installation/index.md) | + | 2.10 | 3.6 | 3.8 | **9.6** | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v2.10.0/docs/installation/index.md) | + | 2.9 | 3.6 | 3.8 | 9.5 | **4.0** | [Link](https://github.com/netbox-community/netbox/blob/v2.9.0/docs/installation/index.md) | + | 2.8 | **3.6** | **3.8** | **9.5** | **3.4** | [Link](https://github.com/netbox-community/netbox/blob/v2.8.0/docs/installation/index.md) | + | 2.7 | 3.5 | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.7.0/docs/installation/index.md) | + | 2.6 | 3.5 | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.6.0/docs/installation/index.md) | + | 2.5 | **3.5** | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.5.0/docs/installation/index.md) | + | 2.4 | **3.4** | **3.7** | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.4.0/docs/installation/index.md) | + | 2.3 | 2.7 | 3.6 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.3.0/docs/installation/postgresql.md) | + | 2.2 | 2.7 | 3.6 | **9.4** | - | [Link](https://github.com/netbox-community/netbox/blob/v2.2.0/docs/installation/postgresql.md) | + | 2.1 | 2.7 | 3.6 | 9.3 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.1.0/docs/installation/postgresql.md) | + | 2.0 | 2.7 | **3.6** | **9.3** | - | [Link](https://github.com/netbox-community/netbox/blob/v2.0.0/docs/installation/postgresql.md) | + | 1.9 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.9.0-r1/docs/installation/postgresql.md) | + | 1.8 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.8.0/docs/installation/postgresql.md) | + | 1.7 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.7.0/docs/installation/postgresql.md) | + | 1.6 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.6.0/docs/installation/postgresql.md) | + | 1.5 | 2.7 | 3.5 | **9.2** | - | [Link](https://github.com/netbox-community/netbox/blob/v1.5.0/docs/installation/postgresql.md) | + | 1.4 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.4.0/docs/installation/postgresql.md) | + | 1.3 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.3.0/docs/installation/postgresql.md) | + | 1.2 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.2.0/docs/installation/postgresql.md) | + | 1.1 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.1.0/docs/getting-started.md) | + | 1.0 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/1.0.0/docs/getting-started.md) | + ## 3. Install the Latest Release From 45779a24a40b4feefa9ed7bfd8eeffbfd7f902c2 Mon Sep 17 00:00:00 2001 From: Martin Hauser Date: Wed, 2 Apr 2025 21:41:36 +0200 Subject: [PATCH 2/4] docs(release): Update checklist with dependency requirements Add steps to update the dependency requirements matrix for each minor release in the release checklist. Clarify how to document changes for system requirements and linked installation guides. Fixes #18733 --- docs/development/release-checklist.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index 5b31a6391..c507a777a 100644 --- a/docs/development/release-checklist.md +++ b/docs/development/release-checklist.md @@ -31,6 +31,29 @@ Close the [release milestone](https://github.com/netbox-community/netbox/milesto Check that a link to the release notes for the new version is present in the navigation menu (defined in `mkdocs.yml`), and that a summary of all major new features has been added to `docs/index.md`. +### Adopt the Dependency Requirements Matrix + +For every minor release, update the dependency requirements matrix in `docs/installation/upgrading.md` ("All versions") to reflect the supported versions of Python, PostgreSQL, and Redis: + +1. Add a new row with the supported dependency versions. +2. Include a documentation link using the release tag format: `https://github.com/netbox-community/netbox/blob/v4.2.0/docs/installation/index.md` +3. Bold any version changes for clarity. + +**Example Update:** + +```markdown +| NetBox Version | Python min | Python max | PostgreSQL min | Redis min | Documentation | +|:--------------:|:----------:|:----------:|:--------------:|:---------:|:-------------------------------------------------------------------------------------------------:| +| 4.2 | 3.10 | 3.12 | **13** | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.2.0/docs/installation/index.md) | +``` + +### Update System Requirements + +If a new Django release is adopted or other major dependencies (Python, PostgreSQL, Redis) change: + +* Update the installation guide (`docs/installation/index.md`) with the new minimum versions. +* Update the upgrade guide (`docs/installation/upgrading.md`) for the current version accordingly. + ### Manually Perform a New Install Start the documentation server and navigate to the current version of the installation docs: From f8f5ab8d611e21f64df0e12c2a7844418438b9f6 Mon Sep 17 00:00:00 2001 From: Martin Hauser Date: Mon, 7 Apr 2025 16:55:23 +0200 Subject: [PATCH 3/4] docs(release): Correct formatting in release checklist --- docs/development/release-checklist.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index c507a777a..1b76ed31d 100644 --- a/docs/development/release-checklist.md +++ b/docs/development/release-checklist.md @@ -1,12 +1,12 @@ # Release Checklist -This documentation describes the process of packaging and publishing a new NetBox release. There are three types of release: +This documentation describes the process of packaging and publishing a new NetBox release. There are three types of releases: * Major release (e.g. v3.7.8 to v4.0.0) * Minor release (e.g. v4.0.10 to v4.1.0) * Patch release (e.g. v4.1.0 to v4.1.1) -While major releases generally introduce some very substantial change to the application, they are typically treated the same as minor version increments for the purpose of release packaging. +While major releases generally introduce some very substantial changes to the application, they are typically treated the same as minor version increments for the purpose of release packaging. For patch releases (e.g. upgrading from v4.2.2 to v4.2.3), begin at the [patch releases](#patch-releases) heading below. For minor or major releases, complete the entire checklist. @@ -62,15 +62,25 @@ Start the documentation server and navigate to the current version of the instal mkdocs serve ``` -Follow these instructions to perform a new installation of NetBox in a temporary environment. This process must not be automated: The goal of this step is to catch any errors or omissions in the documentation, and ensure that it is kept up-to-date for each release. Make any necessary changes to the documentation before proceeding with the release. +Follow these instructions to perform a new installation of NetBox in a temporary environment. This process must not be automated: The goal of this step is to catch any errors or omissions in the documentation and ensure that it is kept up to date for each release. Make any necessary changes to the documentation before proceeding with the release. ### Test Upgrade Paths -Upgrading from a previous version typically involves database migrations, which must work without errors. Supported upgrade paths include from one minor version to another within the same major version (i.e. 4.0 to 4.1), as well as from the latest patch version of the previous minor version (i.e. 3.7 to 4.0 or to 4.1). Prior to release, test all these supported paths by loading demo data from the source version and performing a `./manage.py migrate`. +Upgrading from a previous version typically involves database migrations, which must work without errors. +Test the following supported upgrade paths: + +- From one minor version to another within the same major version (e.g. 4.0 to 4.1). +- From the latest patch version of the previous minor version (e.g. 3.7 to 4.0 or 4.1). + +Prior to release, test all these supported paths by loading demo data from the source version and performing: + +```no-highlight +./manage.py migrate +``` ### Merge the `feature` Branch -Submit a pull request to merge the `feature` branch into the `main` branch in preparation for its release. Once it has been merged, continue with the section for patch releases below. +Submit a pull request to merge the `feature` branch into the `main` branch in preparation for its release. Once it has been merged, continue with the section for the patch releases below. ### Rebuild Demo Data (After Release) @@ -82,7 +92,7 @@ After the release of a new minor version, generate a new demo data snapshot comp ### Create a Release Branch -Begin by creating a new branch (based off of `main`) to effect the release. This will comprise the changes listed below. +Begin by creating a new branch (based on `main`) to effect the release. This will comprise the changes listed below. ``` git checkout main @@ -159,7 +169,7 @@ Then, compile these portable (`.po`) files for use in the application: * Add a section for this release at the top of the changelog page for the minor version (e.g. `docs/release-notes/version-4.2.md`) listing all relevant changes made in this release. !!! tip - Put yourself in the shoes of the user when recording change notes. Focus on the effect that each change has for the end user, rather than the specific bits of code that were modified in a PR. Ensure that each message conveys meaning absent context of the initial feature request or bug report. Remember to include key words or phrases (such as exception names) that can be easily searched. + Put yourself in the shoes of the user when recording change notes. Focus on the effect that each change has for the end user, rather than the specific bits of code that were modified in a PR. Ensure that each message conveys meaning absent context of the initial feature request or bug report. Remember to include keywords or phrases (such as exception names) that can be easily searched. ### Submit a Pull Request From 10e1ae8292c9efbfd39ef5634f5442e1a07c6fc8 Mon Sep 17 00:00:00 2001 From: Martin Hauser Date: Mon, 7 Apr 2025 17:17:26 +0200 Subject: [PATCH 4/4] docs(release): Update Dependency Requirements Matrix header Renames the "Adopt the Dependency Requirements Matrix" section to "Update the Dependency Requirements Matrix" for clarity. --- docs/development/release-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index 1b76ed31d..a58670e61 100644 --- a/docs/development/release-checklist.md +++ b/docs/development/release-checklist.md @@ -31,7 +31,7 @@ Close the [release milestone](https://github.com/netbox-community/netbox/milesto Check that a link to the release notes for the new version is present in the navigation menu (defined in `mkdocs.yml`), and that a summary of all major new features has been added to `docs/index.md`. -### Adopt the Dependency Requirements Matrix +### Update the Dependency Requirements Matrix For every minor release, update the dependency requirements matrix in `docs/installation/upgrading.md` ("All versions") to reflect the supported versions of Python, PostgreSQL, and Redis: