feat: ✨ Decommissioning Job (#85)

* Updates pyproject.toml for 3.11

* fix: Updates for OSRB documentation review

fixes #78

* docs: The custom `indent` filter was removed in favor of using the builtin `indent` filter

* docs: Documentation updates

* docs: Removed unneeded doc template

* feat: ✨ Decommissioning Job

* Apply suggestions from code review

Co-authored-by: Leo Kirchner <[email protected]>

* Decouple pre decommission job

* use callable

* generalize hook

* wip

* wip

* fix: Fixed test failures.

The `TransactionTestCase` actually has less test isolation than `TestCase` which caused the test designs to not actually get reverted between tests.

* refactor: JournalEntry can now be reverted.

Moved the revertting code from the decommissioning job and into the JournalEntry model. Also added some tests to validate the code.

* fix tests

* fix dict logic

* docs: Documented why refreshing `design_object` is necessary

* refactor: Refactored revert code into `Journal` model

* docs: Updated branding from `plugin` to `app`

* refactor: Refactored decom code to model and hooks to signals

Moved the design instance decommissioning code into the `DesignInstance` model. Also implemented the pre/post decom hooks as signals.

* style: Autoformatting

* Add l3vpn design example

* fix old dict value null

* refactor: Minor refactoring of `JournalEntry` revert and the model itself.

* fix tests

* update the l3vppn example and add a hook to validate input data

* bump version

* avoid overwrite of  method

* clean up some leftovers

* Missing part of previous commit

* Rename variables for consistency

* fix: Fixed extra `{% endmacro %}` that got added at some point.

* fix: Now logging the design instance and journal objects.

* Adjust test with warning, improve logging plus journalentry retrieve view

* adjust logging

* mre info

* fix exception chain

---------

Co-authored-by: Josh VanDeraa <[email protected]>
Co-authored-by: Andrew Bates <[email protected]>
Co-authored-by: Leo Kirchner <[email protected]>

.cookiecutter.json

@@ -3,24 +3,20 @@
     "codeowner_github_usernames": "@abates @mzbroch",
     "full_name": "Network to Code, LLC",
     "email": "[email protected]",
-    "github_org": "networktocode-llc",
-    "plugin_name": "design_builder",
-    "verbose_name": "Design Builder",
-    "plugin_slug": "design-builder",
+    "github_org": "nautobot",
+    "plugin_name": "nautobot_design_builder",
+    "verbose_name": "Nautobot Design Builder",
+    "plugin_slug": "nautobot-design-builder",
     "project_slug": "nautobot-plugin-design-builder",
-    "repo_url": "https://github.com/networktocode-llc/nautobot-plugin-design-builder",
+    "repo_url": "https://github.com/nautobot/nautobot-plugin-design-builder",
     "base_url": "design-builder",
-    "min_nautobot_version": "1.2.0",
+    "min_nautobot_version": "1.6.0",
     "max_nautobot_version": "1.9999",
-    "nautobot_version": "latest",
-    "camel_name": "DesignBuilder",
-    "project_short_description": "A plugin that uses design templates to easily create data objects in Nautobot with minimal input from a user.",
-    "version": "0.1.0",
+    "camel_name": "NautobotDesignBuilder",
+    "project_short_description": "A Nautobot App that uses design templates to easily create data objects in Nautobot with minimal input from a user.",
     "model_class_name": "None",
-    "open_source_license": "Not open source",
+    "open_source_license": "Apache-2.0",
     "docs_base_url": "https://docs.nautobot.com",
-    "docs_app_url": "https://docs.nautobot.com/projects/design-builder/en/latest",
-    "_template": "cookiecutter-ntc/nautobot-plugin",
-    "_output_dir": "/Users/abates/local/devel"
+    "docs_app_url": "https://docs.nautobot.com/projects/design-builder/en/latest"
   }
-}
+}

.gitignore

@@ -56,6 +56,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+lcov.info
 
 # Translations
 *.mo

README.md

@@ -3,8 +3,8 @@
 <p align="center">
   <img src="/docs/images/icon-design-builder.png" class="logo" height="200px">
   <br>
-  <a href="https://github.com/networktocode-llc/nautobot-plugin-design-builder/actions"><img src="https://github.com/networktocode-llc/nautobot-plugin-design-builder/actions/workflows/ci.yml/badge.svg?branch=main"></a>
-  <a href="https://docs.nautobot.com/projects/design-builder/en/latest"><img src="https://readthedocs.org/projects/nautobot-plugin-design-builder/badge/"></a>
+  <a href="https://github.com/nautobot/nautobot-app-design-builder/actions"><img src="https://github.com/nautobot/nautobot-app-design-builder/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="https://docs.nautobot.com/projects/design-builder/en/latest"><img src="https://readthedocs.org/projects/nautobot-app-design-builder/badge/"></a>
   <a href="https://pypi.org/project/design-builder/"><img src="https://img.shields.io/pypi/v/design-builder"></a>
   <a href="https://pypi.org/project/design-builder/"><img src="https://img.shields.io/pypi/dm/design-builder"></a>
   <br>
@@ -27,7 +27,7 @@ Full documentation for this App can be found over on the [Nautobot Docs](https:/
 
 ### Contributing to the Documentation
 
-You can find all the Markdown source for the App documentation under the [`docs`](https://github.com/networktocode-llc/nautobot-plugin-design-builder/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away.
+You can find all the Markdown source for the App documentation under the [`docs`](https://github.com/nautobot/nautobot-app-design-builder/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away.
 
 If you need to view the fully-generated documentation site, you can build it with [MkDocs](https://www.mkdocs.org/). A container hosting the documentation can be started using the `invoke` commands (details in the [Development Environment Guide](https://docs.nautobot.com/projects/design-builder/en/latest/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). Using this container, as your changes to the documentation are saved, they will be automatically rebuilt and any pages currently being viewed will be reloaded in your browser.
 

development/Dockerfile

@@ -1,4 +1,4 @@
-ARG NAUTOBOT_VER="1.0.1"
+ARG NAUTOBOT_VER="1.6"
 ARG PYTHON_VER=3.8
 FROM ghcr.io/nautobot/nautobot-dev:${NAUTOBOT_VER}-py${PYTHON_VER}
 

development/development.env

@@ -39,9 +39,3 @@ POSTGRES_DB=${NAUTOBOT_DB_NAME}
 MYSQL_USER=${NAUTOBOT_DB_USER}
 MYSQL_DATABASE=${NAUTOBOT_DB_NAME}
 MYSQL_ROOT_HOST=%
-
-# This needs to match the slug for the desired config context repo design builder will use
-DESIGN_BUILDER_GIT_SERVER=http://git-server.local:3000
-DESIGN_BUILDER_CONTEXT_REPO_SLUG=config-contexts
-DESIGN_BUILDER_CONTEXT_REPO=config-contexts.git
-DESIGN_BUILDER_DESIGN_REPO=designs.git

development/nautobot_config.py

@@ -143,6 +143,16 @@
 if nautobot_version < Version("2.0"):
     PLUGINS.append("nautobot_bgp_models")
 
-PLUGINS_CONFIG = {"design_builder": {"context_repository": os.getenv("DESIGN_BUILDER_CONTEXT_REPO_SLUG", None)}}
+
+def pre_decommission_hook_example(design_instance):
+    return True, "Everything good!"
+
+
+PLUGINS_CONFIG = {
+    "nautobot_design_builder": {
+        "context_repository": os.getenv("DESIGN_BUILDER_CONTEXT_REPO_SLUG", None),
+        "pre_decommission_hook": pre_decommission_hook_example,
+    }
+}
 
 STRICT_FILTERING = False

docs/admin/compatibility_matrix.md

@@ -1,10 +1,5 @@
 # Compatibility Matrix
 
-!!! warning "Developer Note - Remove Me!"
-    Explain how the release models of the plugin and of Nautobot work together, how releases are supported, how features and older releases are deprecated etc.
-
 | Design Builder Version | Nautobot First Support Version | Nautobot Last Support Version |
 | ------------- | -------------------- | ------------- |
-| 1.0.X         | 1.2.0                | 1.99.99        |
-| 1.1.X         | 1.4.0                | 1.99.99        |
-| 1.2.X         | 2.0.0                | 2.99.99        |
+| 1.0.X         | 1.6.0                | 2.0.X        |

docs/admin/install.md

@@ -2,50 +2,46 @@
 
 Here you will find detailed instructions on how to **install** and **configure** the App within your Nautobot environment.
 
-!!! warning "Developer Note - Remove Me!"
-    Detailed instructions on installing the App. You will need to update this section based on any additional dependencies or prerequisites.
-
 ## Prerequisites
 
-- The plugin is compatible with Nautobot 1.2.0 and higher.
+- The plugin is compatible with Nautobot 1.6.0 and higher.
 - Databases supported: PostgreSQL, MySQL
 
 !!! note
     Please check the [dedicated page](compatibility_matrix.md) for a full compatibility matrix and the deprecation policy.
 
 ### Access Requirements
 
-!!! warning "Developer Note - Remove Me!"
-    What external systems (if any) it needs access to in order to work.
+Design Builder does not necessarily require any external system access. However, if design jobs will be loaded from a git repository, then the Nautobot instances will need access to the git repo.
 
 ## Install Guide
 
 !!! note
-    Plugins can be installed manually or using Python's `pip`. See the [nautobot documentation](https://nautobot.readthedocs.io/en/latest/plugins/#install-the-package) for more details. The pip package name for this plugin is [`design-builder`](https://pypi.org/project/design-builder/).
+    Plugins can be installed manually or using Python's `pip`. See the [nautobot documentation](https://nautobot.readthedocs.io/en/latest/plugins/#install-the-package) for more details. The pip package name for this plugin is [`nautobot-design-builder`](https://pypi.org/project/nautobot/design-builder/).
 
 The plugin is available as a Python package via PyPI and can be installed with `pip`:
 
 ```shell
-pip install design-builder
+pip install nautobot-design-builder
 ```
 
-To ensure Design Builder is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `design-builder` package:
+To ensure Design Builder is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-design-builder` package:
 
 ```shell
-echo design-builder >> local_requirements.txt
+echo nautobot-design-builder >> local_requirements.txt
 ```
 
 Once installed, the plugin needs to be enabled in your Nautobot configuration. The following block of code below shows the additional configuration required to be added to your `nautobot_config.py` file:
 
-- Append `"design_builder"` to the `PLUGINS` list.
-- Append the `"design_builder"` dictionary to the `PLUGINS_CONFIG` dictionary and override any defaults.
+- Append `"nautobot_design_builder"` to the `PLUGINS` list.
+- Append the `"nautobot_design_builder"` dictionary to the `PLUGINS_CONFIG` dictionary and override any defaults.
 
 ```python
 # In your nautobot_config.py
-PLUGINS = ["design_builder"]
+PLUGINS = ["nautobot_design_builder"]
 
 # PLUGINS_CONFIG = {
-#   "design_builder": {
+#   "nautobot_design_builder": {
 #     ADD YOUR SETTINGS HERE
 #   }
 # }
@@ -66,16 +62,3 @@ Then restart (if necessary) the Nautobot services which may include:
 ```shell
 sudo systemctl restart nautobot nautobot-worker nautobot-scheduler
 ```
-
-## App Configuration
-
-!!! warning "Developer Note - Remove Me!"
-    Any configuration required to get the App set up. Edit the table below as per the examples provided.
-
-The plugin behavior can be controlled with the following list of settings:
-
-| Key     | Example | Default | Description                          |
-| ------- | ------ | -------- | ------------------------------------- |
-| `enable_backup` | `True` | `True` | A boolean to represent whether or not to run backup configurations within the plugin. |
-| `platform_slug_map` | `{"cisco_wlc": "cisco_aireos"}` | `None` | A dictionary in which the key is the platform slug and the value is what netutils uses in any "network_os" parameter. |
-| `per_feature_bar_width` | `0.15` | `0.15` | The width of the table bar within the overview report |

docs/admin/release_notes/version_1.0.md

@@ -1,48 +1,11 @@
 # v1.0 Release Notes
 
-!!! warning "Developer Note - Remove Me!"
-    Guiding Principles:
-
-    - Changelogs are for humans, not machines.
-    - There should be an entry for every single version.
-    - The same types of changes should be grouped.
-    - Versions and sections should be linkable.
-    - The latest version comes first.
-    - The release date of each version is displayed.
-    - Mention whether you follow Semantic Versioning.
-
-    Types of changes:
-
-    - `Added` for new features.
-    - `Changed` for changes in existing functionality.
-    - `Deprecated` for soon-to-be removed features.
-    - `Removed` for now removed features.
-    - `Fixed` for any bug fixes.
-    - `Security` in case of vulnerabilities.
-
-
 This document describes all new features and changes in the release `1.0`. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Release Overview
 
-- Major features or milestones
-- Achieved in this `x.y` release
-- Changes to compatibility with Nautobot and/or other plugins, libraries etc.
-
-## [v1.0.1] - 2021-09-08
-
-### Added
-
-### Changed
-
-### Fixed
-
-- [#123](https://github.com/networktocode-llc/nautobot-plugin-design-builder/issues/123) Fixed Tag filtering not working in job launch form
-
-## [v1.0.0] - 2021-08-03
-
-### Added
+Initial Public Release
 
-### Changed
+## [v1.0.0] - 2023-11-01
 
-### Fixed
+Initial Public Release

docs/admin/uninstall.md

@@ -4,14 +4,8 @@ Here you will find any steps necessary to cleanly remove the App from your Nauto
 
 ## Uninstall Guide
 
-!!! warning "Developer Note - Remove Me!"
-    Detailed instructions on how to remove the app from Nautobot.
-
-Remove the configuration you added in `nautobot_config.py` from `PLUGINS` & `PLUGINS_CONFIG`.
+Remove the `DESIN_BUILDER` section that was added to `nautobot_config.py` `PLUGINS` & `PLUGINS_CONFIG`.
 
 ## Database Cleanup
 
-!!! warning "Developer Note - Remove Me!"
-    Any cleanup operations to ensure the database is clean after the app is removed. Beyond deleting tables, is there anything else that needs cleaning up, such as CFs, relationships, etc. if they're no longer desired?
-
-Drop all tables from the plugin: `nautobot_plugin_design_builder*`.
+The current version of Design Builder does not include any database models, so no database cleanup is necessary.

docs/admin/upgrade.md

@@ -4,7 +4,8 @@ Here you will find any steps necessary to upgrade the App in your Nautobot envir
 
 ## Upgrade Guide
 
-!!! warning "Developer Note - Remove Me!"
-    Add more detailed steps on how the app is upgraded in an existing Nautobot setup and any version specifics (such as upgrading between major versions with breaking changes).
+Since Design Builder does not currently include any custom data models the only requirement for updating is to update the `nautobot-design-builder` package using the `pip` command:
 
-When a new release comes out it may be necessary to run a migration of the database to account for any changes in the data models used by this plugin. Execute the command `nautobot-server post-upgrade` within the runtime environment of your Nautobot installation after updating the `design-builder` package via `pip`.
+```python
+pip install --upgrade nautobot-design-builder
+```

docs/dev/contributing.md

@@ -1,5 +1,9 @@
 # Contributing to the App
 
+Contributions are encouraged and we are always delighted in any form of work. We are always looking for feedback both in the development of code as well as documentation, use cases, and examples. To contribute to this project, please use the following guidlines:
+
+## Code Development
+
 The project is packaged with a light [development environment](dev_environment.md) based on `docker-compose` to help with the local development of the project and to run tests.
 
 The project is following Network to Code software development guidelines and is leveraging the following:
@@ -10,12 +14,18 @@ The project is following Network to Code software development guidelines and is
 
 Documentation is built using [mkdocs](https://www.mkdocs.org/). The [Docker based development environment](dev_environment.md#docker-development-environment) automatically starts a container hosting a live version of the documentation website on [http://localhost:8001](http://localhost:8001) that auto-refreshes when you make any changes to your local files.
 
+## Documentation
+
+Code documentation follows the [Google docstring](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) style. Where possible, include a description, argument documentation and examples.
+
+The user and developer documentation is located in the top level `docs/` directory. The documenation is written in markdown format and is rendered using MkDocs.
+
+Example designs should be placed in the top level `examples/` directory, as appropriate.
+
 ## Branching Policy
 
-!!! warning "Developer Note - Remove Me!"
-    What branching policy is used for this project and where contributions should be made.
+The active branch in Design Builder is the `develop` branch. However, commits are not allowed directly to this branch. Instead, fork the code and open a pull request to `develop`.
 
 ## Release Policy
 
-!!! warning "Developer Note - Remove Me!"
-    How new versions are released.
+There is no set release schedule for this App. New releases will be published as appropriate when new features and/or bug fixes are ready.

docs/user/app_getting_started.md

@@ -13,6 +13,7 @@ The easiest way to experience Design Builder is to run it in a local environment
 ## What are the next steps?
 
 The Design Builder application ships with some sample designs to demonstrate capabilities. Once the application stack is ready, you should have two designs listed under the "Jobs" -> "Jobs" menu item.
+
 ![Jobs list](../images/screenshots/sample-design-jobs-list.png)
 
 Note that both jobs are disabled. Nautobot automatically marks jobs as disabled when they are first loaded. In order to run these jobs, click the edit button ![edit button](../images/screenshots/edit-button.png) and check the "enabled" checkbox:

docs/user/app_overview.md

@@ -7,6 +7,8 @@ This document provides an overview of the App including critical information and
 
 ## Description
 
+Design Builder provides a system where standardized network designs can be developed to produce collections of objects within Nautobot. These designs are text based templates that can create and update hierarchical data structures within Nautobot.
+
 ## Audience (User Personas) - Who should use this App?
 
 - Network engineers who want to have reproducible sets of Nautobot objects based on some standard design.