From e460843e2e4f27d6083b26d059c73c51230a0edc Mon Sep 17 00:00:00 2001
From: Jeremy Stretch <jstretch@netboxlabs.com>
Date: Wed, 9 Oct 2024 16:21:07 -0400
Subject: [PATCH] Closes #17472: Deprecate the staged changes API

---
 docs/models/extras/branch.md               |  3 +++
 docs/models/extras/stagedchange.md         |  3 +++
 docs/plugins/development/staged-changes.md |  4 ++--
 netbox/extras/models/staging.py            | 15 +++++++++++++++
 4 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/docs/models/extras/branch.md b/docs/models/extras/branch.md
index fd7922b7e36..4599fed8599 100644
--- a/docs/models/extras/branch.md
+++ b/docs/models/extras/branch.md
@@ -1,5 +1,8 @@
 # Branches
 
+!!! danger "Deprecated Feature"
+    This feature has been deprecated in NetBox v4.2 and will be removed in a future release. Please consider using the [netbox-branching plugin](https://github.com/netboxlabs/netbox-branching), which provides much more robust functionality.
+
 A branch is a collection of related [staged changes](./stagedchange.md) that have been prepared for merging into the active database. A branch can be merged by executing its `commit()` method. Deleting a branch will delete all its related changes.
 
 ## Fields
diff --git a/docs/models/extras/stagedchange.md b/docs/models/extras/stagedchange.md
index feda2fee6fa..0693a32d31d 100644
--- a/docs/models/extras/stagedchange.md
+++ b/docs/models/extras/stagedchange.md
@@ -1,5 +1,8 @@
 # Staged Changes
 
+!!! danger "Deprecated Feature"
+    This feature has been deprecated in NetBox v4.2 and will be removed in a future release. Please consider using the [netbox-branching plugin](https://github.com/netboxlabs/netbox-branching), which provides much more robust functionality.
+
 A staged change represents the creation of a new object or the modification or deletion of an existing object to be performed at some future point. Each change must be assigned to a [branch](./branch.md).
 
 Changes can be applied individually via the `apply()` method, however it is recommended to apply changes in bulk using the parent branch's `commit()` method.
diff --git a/docs/plugins/development/staged-changes.md b/docs/plugins/development/staged-changes.md
index 64a1a43e023..a8fd1d232e0 100644
--- a/docs/plugins/development/staged-changes.md
+++ b/docs/plugins/development/staged-changes.md
@@ -1,7 +1,7 @@
 # Staged Changes
 
-!!! danger "Experimental Feature"
-    This feature is still under active development and considered experimental in nature. Its use in production is strongly discouraged at this time.
+!!! danger "Deprecated Feature"
+    This feature has been deprecated in NetBox v4.2 and will be removed in a future release. Please consider using the [netbox-branching plugin](https://github.com/netboxlabs/netbox-branching), which provides much more robust functionality.
 
 NetBox provides a programmatic API to stage the creation, modification, and deletion of objects without actually committing those changes to the active database. This can be useful for performing a "dry run" of bulk operations, or preparing a set of changes for administrative approval, for example.
 
diff --git a/netbox/extras/models/staging.py b/netbox/extras/models/staging.py
index b944a6fb90f..68d37de7f53 100644
--- a/netbox/extras/models/staging.py
+++ b/netbox/extras/models/staging.py
@@ -1,4 +1,5 @@
 import logging
+import warnings
 
 from django.contrib.contenttypes.fields import GenericForeignKey
 from django.db import models, transaction
@@ -44,6 +45,13 @@ class Meta:
         verbose_name = _('branch')
         verbose_name_plural = _('branches')
 
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            'The staged changes functionality has been deprecated and will be removed in a future release.',
+            DeprecationWarning
+        )
+        super().__init__(*args, **kwargs)
+
     def __str__(self):
         return f'{self.name} ({self.pk})'
 
@@ -97,6 +105,13 @@ class Meta:
         verbose_name = _('staged change')
         verbose_name_plural = _('staged changes')
 
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            'The staged changes functionality has been deprecated and will be removed in a future release.',
+            DeprecationWarning
+        )
+        super().__init__(*args, **kwargs)
+
     def __str__(self):
         action = self.get_action_display()
         app_label, model_name = self.object_type.natural_key()