From b09c1166f4667ab8b643ef30093d0271de7925f3 Mon Sep 17 00:00:00 2001
From: Rob Hudson <robhudson@mozilla.com>
Date: Thu, 2 May 2024 09:08:37 -0700
Subject: [PATCH] Add migration guide

---
 docs/configuration.rst   |  8 ++++
 docs/migration-guide.rst | 80 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 docs/migration-guide.rst

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 261e9fb..ce34f23 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -15,6 +15,14 @@ before configuring django-csp.
    policies and even errors when mistakenly configuring them as a ``string``.
 
 
+============================
+Migrating from django-csp v3
+============================
+
+Version 4.x of django-csp introduces a new configuration format that breaks compatibility with
+previous versions.  If you are migrating from django-csp v3, you will need to update your settings
+to the new format. See the :ref:`migration guide <migration-guide>` for more information.
+
 =============
 Configuration
 =============
diff --git a/docs/migration-guide.rst b/docs/migration-guide.rst
new file mode 100644
index 0000000..47cef0d
--- /dev/null
+++ b/docs/migration-guide.rst
@@ -0,0 +1,80 @@
+
+# django-csp v4 Migration Guide
+
+## Overview
+
+In the latest version of `django-csp`, the format for configuring Content Security Policy (CSP)
+settings has been updated are are backwards-incompatible with prior versions. The previous approach
+of using individual settings prefixed with `CSP_` for each directive is no longer valid. Instead,
+all CSP settings are now consolidated into one of two dict-based settings: `CONTENT_SECURITY_POLICY`
+or `CONTENT_SECURITY_POLICY_REPORT_ONLY`.
+
+## Migrating from the Old Settings Format
+
+### Step 1: Identify Existing CSP Settings
+
+First, locate all the existing CSP settings in your Django project. These settings typically start
+with the `CSP_` prefix, such as `CSP_DEFAULT_SRC`, `CSP_SCRIPT_SRC`, `CSP_IMG_SRC`, and
+`CSP_EXCLUDE_URL_PREFIXES`.
+
+### Step 2: Create the New Settings Dictionary
+
+In your Django project's `settings.py` file, create a new dictionary called
+`CONTENT_SECURITY_POLICY` or `CONTENT_SECURITY_POLICY_REPORT_ONLY`, depending on whether you want to
+enforce the policy or report violations.
+
+```python
+CONTENT_SECURITY_POLICY = {
+    "EXCLUDE_URL_PREFIXES": [],
+    "DIRECTIVES": {},
+}
+```
+
+### Step 3: Migrate Existing Settings
+
+Migrate your existing CSP settings to the new format by populating the `DIRECTIVES` dictionary
+inside the `CONTENT_SECURITY_POLICY` setting. The keys of the `DIRECTIVES` dictionary should be the
+CSP directive names in lowercase, and the values should be lists containing the corresponding
+sources.
+
+For example, if you had the following old settings:
+
+```python
+CSP_DEFAULT_SRC = ["'self'", "*.example.com"]
+CSP_SCRIPT_SRC = ["'self'", "js.cdn.com/example/"]
+CSP_IMG_SRC = ["'self'", "data:", "example.com"]
+CSP_EXCLUDE_URL_PREFIXES = ["/admin"]
+```
+
+The new settings would be:
+
+```python
+CONTENT_SECURITY_POLICY = {
+    "EXCLUDE_URL_PREFIXES": ["/admin"],
+    "DIRECTIVES": {
+        "default-src": ["'self'", "*.example.com"],
+        "script-src": ["'self'", "js.cdn.com/example/"],
+        "img-src": ["'self'", "data:", "example.com"],
+    },
+}
+```
+
+Note that the directive names in the `DIRECTIVES` dictionary are in lowercase and use dashes instead
+of underscores.
+
+### Step 4: Remove Old Settings
+
+After migrating to the new settings format, remove all the old `CSP_` prefixed settings from your
+`settings.py` file.
+
+### Step 5: Update the django-csp Version
+
+Finally, update your `django-csp` version to the latest version that support the new settings
+format.
+
+## Conclusion
+
+By following this migration guide, you should be able to successfully update your Django project to
+use the new dict-based CSP settings format introduced in the latest version of `django-csp`. This
+change aligns the package with the latest CSP specification and provides a more organized and
+flexible way to configure your Content Security Policy.