From 8eca06d205bd500a43445b6504d817742adfb231 Mon Sep 17 00:00:00 2001
From: fabianallendorf <fabian.allendorf@node.energy>
Date: Wed, 5 Nov 2025 17:18:22 +0100
Subject: [PATCH] concise name and documentation update

# Conflicts:
#	docs/source/usage.rst
---
 CHANGELOG.md          |  1 +
 auditlog/conf.py      |  4 ++--
 auditlog/diff.py      |  2 +-
 auditlog/models.py    |  4 ----
 docs/source/usage.rst | 23 +++++++++++++++++++++++
 5 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8923781..a3eb8ee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 #### Improvements
 
+- feat: Add `AUDITLOG_USE_FK_STRING_REPRESENTATION` setting that controls how foreign key changes are represented ([#779)](https://github.com/jazzband/django-auditlog/pull/779))
 - Add `AUDITLOG_USE_BASE_MANAGER` setting to override default manager use ([#766](https://github.com/jazzband/django-auditlog/pull/766))
 - Drop 'Python 3.9' support ([#773](https://github.com/jazzband/django-auditlog/pull/773))
 
diff --git a/auditlog/conf.py b/auditlog/conf.py
index 854e09e..754328b 100644
--- a/auditlog/conf.py
+++ b/auditlog/conf.py
@@ -73,6 +73,6 @@ settings.AUDITLOG_USE_BASE_MANAGER = getattr(
 )
 
 # Use string representation of referenced object in foreign key changes instead of its primary key
-settings.AUDITLOG_USE_STRING_REPRESENTATION_IN_FOREIGN_KEY_CHANGES = getattr(
-    settings, "AUDITLOG_USE_STRING_REPRESENTATION_IN_FOREIGN_KEY_CHANGES", False
+settings.AUDITLOG_USE_FK_STRING_REPRESENTATION = getattr(
+    settings, "AUDITLOG_USE_FK_STRING_REPRESENTATION", False
 )
diff --git a/auditlog/diff.py b/auditlog/diff.py
index 0ac7a9c..8583f37 100644
--- a/auditlog/diff.py
+++ b/auditlog/diff.py
@@ -107,7 +107,7 @@ def get_field_value(obj, field, use_json_for_changes=False):
                 except TypeError:
                     pass
         elif (
-            not settings.AUDITLOG_USE_STRING_REPRESENTATION_IN_FOREIGN_KEY_CHANGES
+            not settings.AUDITLOG_USE_FK_STRING_REPRESENTATION
             and (field.one_to_one or field.many_to_one)
             and hasattr(field, "rel_class")
         ):
diff --git a/auditlog/models.py b/auditlog/models.py
index 49d79bb..edc5dd2 100644
--- a/auditlog/models.py
+++ b/auditlog/models.py
@@ -542,10 +542,6 @@ class AbstractLogEntry(models.Model):
         """
         :return: A string representing a given FK value and the field to which it belongs
         """
-        # Return value if FK value should explicitly be interpreted as string representation
-        if settings.AUDITLOG_USE_STRING_REPRESENTATION_IN_FOREIGN_KEY_CHANGES:
-            return value
-
         # Return "None" if the FK value is "None".
         if value == "None":
             return value
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 9dc4a95..8c2a8a2 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -444,6 +444,29 @@ of the default one.
 .. versionadded:: 3.5.0
     Custom LogEntry model configuration via ``AUDITLOG_LOGENTRY_MODEL``
 
+**AUDITLOG_USE_FK_STRING_REPRESENTATION**
+
+Determines how changes to foreign key fields are recorded in log entries.
+
+When `True`, changes to foreign key fields are stored using the string representation of related objects.
+When `False` (default), the primary key of the related objects is stored instead.
+
+Before version 2.2.0, foreign key changes were stored using the string representation of the related objects.
+Starting from version 2.2.0, the default behavior was updated to store the primary key of the related objects instead.
+
+Before:
+.. code-block:: json
+    { "foreign_key_field": ["foo", "bar"] }
+
+
+After:
+.. code-block:: json
+    { "foreign_key_field": [1, 2] }
+
+You can use this option to enable the legacy behavior.
+
+.. versionadded:: 3.5.0
+
 Actors
 ------