rebase

Author: Valentijn Scholten

docs/content/en/open_source/upgrading/2.54.md

@@ -2,6 +2,41 @@
 title: 'Upgrading to DefectDojo Version 2.54.x'
 toc_hide: true
 weight: -20251201
-description: No special instructions.
+description: Removal of django-auditlog and exclusive use of django-pghistory for audit logging.
 ---
-There are no special instructions for upgrading to 2.54.x. Check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/2.54.0) for the contents of the release.
+
+## Breaking Change: Removal of django-auditlog
+
+Starting with DefectDojo 2.53, `django-auditlog` support has been removed in favour of `django-pghistory`.
+This is designed to be a backwards compatible change, unless:
+- You're querying the database directly for auditlog events, or,
+- You've set the `DD_AUDITLOG_TYPE` environment variable (or `AUDITLOG_TYPE` settings field)
+
+### Required Actions
+
+If you're using `DD_AUDITLOG_TYPE`, remove it from your configuration/environment.
+
+### Existing Records Preserved
+
+Historical audit log entries stored in the `auditlog_logentry` table will continue to be displayed in the action history view for backward compatibility. No data migration is required.
+
+### Benefits of django-pghistory
+
+The switch to `django-pghistory` provides several advantages:
+
+- **Better performance**: Database-level triggers reduce overhead compared to Django signal-based auditing
+- **More features**: Enhanced context tracking and better support for complex queries
+- **Better data integrity**: PostgreSQL-native implementation ensures consistency
+
+### Migration Notes
+
+- A one-time data migration will take place to populate the `django-pghistory` tables with the initial snapshot of the tracked models.
+- The migration is designed to be fail-safe: if it fails for some reason, it will continue where it left off.
+- The migration can also be performed up front via
+  - `docker compose exec uwsgi bash -c "python manage.py pghistory_backfill_fast"`, or
+  - `docker compose exec uwsgi bash -c "python manage.py pghistory_backfill_simple"`, or
+  - `docker compose exec uwsgi bash -c "python manage.py pghistory_backfill"`
+
+The backfill migration is not mandatory to succeed. If it fails for some reason, the only side effect will be that the first auditlog diff will contain all fields of an object instead just the changed fields.
+
+Check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/2.54.0) for the contents of the release.