From 268ded92bc75bda84b70b2e4a6026a5cbe9dc0c1 Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Fri, 8 May 2026 08:19:15 -0700 Subject: [PATCH] Documentation: Update v3 migration docs (#12752) --- docs/migration-v3.md | 8 ++++++++ src/paperless/checks.py | 10 +++++----- src/paperless/tests/test_checks.py | 6 +++--- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/migration-v3.md b/docs/migration-v3.md index 1cedfaa28..e17dd3b65 100644 --- a/docs/migration-v3.md +++ b/docs/migration-v3.md @@ -1,5 +1,9 @@ # v3 Migration Guide +## Pre-Requisites + +Upgrading to Paperless-ngx v3 can only be performed from version 2.20.15. If you are running an older version, please upgrade to v2.20.15 before proceeding with the v3 upgrade. + ## Secret Key is Now Required The `PAPERLESS_SECRET_KEY` environment variable is now required. This is a critical security setting used for cryptographic signing and should be set to a long, random value. @@ -37,6 +41,10 @@ separating the directory ignore from the file ignore. | `CONSUMER_IGNORE_PATTERNS` | [`CONSUMER_IGNORE_PATTERNS`](configuration.md#PAPERLESS_CONSUMER_IGNORE_PATTERNS) | **Now regex, not fnmatch**; user patterns are added to (not replacing) default ones | | _New_ | [`CONSUMER_IGNORE_DIRS`](configuration.md#PAPERLESS_CONSUMER_IGNORE_DIRS) | Additional directories to ignore; user entries are added to (not replacing) defaults | +## Duplicate Handling Changes + +Paperless-ngx v3 no longer rejects duplicate documents by default. Instead, it now allows duplicates but adds a way to identify them via the UI. To (re-)enable duplicate rejection, set `PAPERLESS_CONSUMER_DELETE_DUPLICATES=true` in your environment. + ## Encryption Support Document and thumbnail encryption is no longer supported. This was previously deprecated in [paperless-ng 0.9.3](https://github.com/paperless-ngx/paperless-ngx/blob/dev/docs/changelog.md#paperless-ng-093) diff --git a/src/paperless/checks.py b/src/paperless/checks.py index adf8b9f07..4d8646112 100644 --- a/src/paperless/checks.py +++ b/src/paperless/checks.py @@ -202,10 +202,10 @@ def check_v3_minimum_upgrade_version( **kwargs: object, ) -> list[Error]: """ - Enforce that upgrades to v3 must start from v2.20.10. + Enforce that upgrades to v3 must start from v2.20.15. v3 squashes all prior migrations into 0001_squashed and 0002_squashed. - If a user skips v2.20.10, the data migration in 1075_workflowaction_order + If a user skips v2.20.15, the data migration in 1075_workflowaction_order never runs and the squash may apply schema changes against an incomplete database state. """ @@ -232,7 +232,7 @@ def check_v3_minimum_upgrade_version( if {"0001_squashed", "0002_squashed"} & applied: return [] - # On v2.20.10 exactly — squash will pick up cleanly from here + # On v2.20.15 exactly — squash will pick up cleanly from here if "1075_workflowaction_order" in applied: return [] @@ -243,8 +243,8 @@ def check_v3_minimum_upgrade_version( Error( "Cannot upgrade to Paperless-ngx v3 from this version.", hint=( - "Upgrading to v3 can only be performed from v2.20.10." - "Please upgrade to v2.20.10, run migrations, then upgrade to v3." + "Upgrading to v3 can only be performed from v2.20.15." + "Please upgrade to v2.20.15, run migrations, then upgrade to v3." "See https://docs.paperless-ngx.com/setup/#upgrading for details." ), id="paperless.E002", diff --git a/src/paperless/tests/test_checks.py b/src/paperless/tests/test_checks.py index c4935c1f1..e5fef4629 100644 --- a/src/paperless/tests/test_checks.py +++ b/src/paperless/tests/test_checks.py @@ -584,11 +584,11 @@ class TestV3MinimumUpgradeVersionCheck: ) -> None: """ GIVEN: - - DB is on an old v2 version (pre-v2.20.10) + - DB is on an old v2 version (pre-v2.20.15) WHEN: - The v3 upgrade check runs THEN: - - The error hint explicitly references v2.20.10 so users know what to do + - The error hint explicitly references v2.20.15 so users know what to do """ mocker.patch.dict( "paperless.checks.connections", @@ -596,7 +596,7 @@ class TestV3MinimumUpgradeVersionCheck: ) result = check_v3_minimum_upgrade_version(None) assert len(result) == 1 - assert "v2.20.10" in result[0].hint + assert "v2.20.15" in result[0].hint def test_db_error_is_swallowed(self, mocker: MockerFixture) -> None: """