feat!: add deprecated v2 OCR env var warnings to system checks

src/paperless/checks.py

@@ -293,6 +293,41 @@ def check_deprecated_db_settings(
     return warnings
 
 
+@register()
+def check_deprecated_v2_ocr_env_vars(
+    app_configs: object,
+    **kwargs: object,
+) -> list[Warning]:
+    """Warn when deprecated v2 OCR environment variables are set.
+
+    Users upgrading from v2 may still have these in their environment or
+    config files, where they are now silently ignored.
+    """
+    warnings: list[Warning] = []
+
+    if os.environ.get("PAPERLESS_OCR_SKIP_ARCHIVE_FILE"):
+        warnings.append(
+            Warning(
+                "PAPERLESS_OCR_SKIP_ARCHIVE_FILE is set but has no effect. "
+                "Use PAPERLESS_ARCHIVE_FILE_GENERATION=never/always/auto instead.",
+                id="paperless.W002",
+            ),
+        )
+
+    ocr_mode = os.environ.get("PAPERLESS_OCR_MODE", "")
+    if ocr_mode in {"skip", "skip_noarchive"}:
+        warnings.append(
+            Warning(
+                f"PAPERLESS_OCR_MODE={ocr_mode!r} is not a valid value. "
+                f"Use PAPERLESS_OCR_MODE=auto (and PAPERLESS_ARCHIVE_FILE_GENERATION=never "
+                f"if you used skip_noarchive) instead.",
+                id="paperless.W003",
+            ),
+        )
+
+    return warnings
+
+
 @register()
 def check_remote_parser_configured(app_configs, **kwargs) -> list[Error]:
     if settings.REMOTE_OCR_ENGINE == "azureai" and not (

src/paperless/tests/test_checks_v3.py

@@ -0,0 +1,53 @@
+"""Tests for v3 system checks: deprecated v2 OCR env var warnings."""
+
+from __future__ import annotations
+
+import pytest
+from django.core import checks as django_checks
+
+
+@pytest.mark.django_db
+class TestDeprecatedV2OcrEnvVarWarnings:
+    def test_old_skip_archive_file_env_warns(self, monkeypatch) -> None:
+        monkeypatch.setenv("PAPERLESS_OCR_SKIP_ARCHIVE_FILE", "always")
+        all_checks = django_checks.run_checks()
+        warns = [
+            e
+            for e in all_checks
+            if "PAPERLESS_OCR_SKIP_ARCHIVE_FILE" in str(getattr(e, "msg", ""))
+        ]
+        assert warns
+
+    def test_old_skip_mode_env_warns(self, monkeypatch) -> None:
+        monkeypatch.setenv("PAPERLESS_OCR_MODE", "skip")
+        all_checks = django_checks.run_checks()
+        warns = [
+            e
+            for e in all_checks
+            if "skip" in str(getattr(e, "msg", "")).lower()
+            and "OCR_MODE" in str(getattr(e, "msg", ""))
+        ]
+        assert warns
+
+    def test_old_skip_noarchive_mode_env_warns(self, monkeypatch) -> None:
+        monkeypatch.setenv("PAPERLESS_OCR_MODE", "skip_noarchive")
+        all_checks = django_checks.run_checks()
+        warns = [
+            e for e in all_checks if "skip_noarchive" in str(getattr(e, "msg", ""))
+        ]
+        assert warns
+
+    def test_no_deprecated_vars_no_warning(self, monkeypatch) -> None:
+        monkeypatch.delenv("PAPERLESS_OCR_SKIP_ARCHIVE_FILE", raising=False)
+        monkeypatch.setenv("PAPERLESS_OCR_MODE", "auto")
+        all_checks = django_checks.run_checks()
+        deprecated_warns = [
+            e
+            for e in all_checks
+            if "PAPERLESS_OCR_SKIP_ARCHIVE_FILE" in str(getattr(e, "msg", ""))
+            or (
+                "skip" in str(getattr(e, "msg", "")).lower()
+                and "OCR_MODE" in str(getattr(e, "msg", ""))
+            )
+        ]
+        assert not deprecated_warns