feat: back-compat for collection 'key'/'collection_code' in backup/restore

Backup now writes both 'key' and 'collection_code' to collection TOML files,
so older software (which only knows 'key') can still read new archives.
Restore accepts either field, preferring 'collection_code' and falling back
to the legacy 'key'.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kdmccormick

src/openedx_content/applets/backup_restore/serializers.py

@@ -156,10 +156,24 @@ class CollectionSerializer(serializers.Serializer):  # pylint: disable=abstract-
     Serializer for collections.
     """
     title = serializers.CharField(required=True)
-    key = serializers.CharField(required=True, source="collection_code")
+    # 'collection_code' is the current field name; 'key' is the old name kept for
+    # back-compat with archives written before the rename.  At least one must be present.
+    collection_code = serializers.CharField(required=False)
+    key = serializers.CharField(required=False)
     description = serializers.CharField(required=True, allow_blank=True)
     entities = serializers.ListField(
         child=serializers.CharField(),
         required=True,
         allow_empty=True,
     )
+
+    def validate(self, attrs):
+        # Prefer 'collection_code'; fall back to legacy 'key'.  Always remove
+        # both so only the normalised 'collection_code' key reaches the caller.
+        code = attrs.pop("collection_code", None)
+        legacy_key = attrs.pop("key", None)
+        code = code or legacy_key
+        if not code:
+            raise serializers.ValidationError("Either 'collection_code' or 'key' is required.")
+        attrs["collection_code"] = code
+        return attrs

src/openedx_content/applets/backup_restore/toml.py

@@ -220,7 +220,10 @@ def toml_collection(collection: Collection, entity_keys: list[str]) -> str:
 
     collection_table = tomlkit.table()
     collection_table.add("title", collection.title)
+    # Write both names so that older software (which reads 'key') stays compatible
+    # with archives produced after the Collection.key -> Collection.collection_code rename.
     collection_table.add("key", collection.collection_code)
+    collection_table.add("collection_code", collection.collection_code)
     collection_table.add("description", collection.description)
     collection_table.add("created", collection.created)
     collection_table.add("entities", entities_array)

tests/openedx_content/applets/backup_restore/test_backup.py

@@ -276,6 +276,17 @@ def test_lp_dump_command(self):
             for file_path, expected_content in expected_files.items():
                 self.check_toml_file(zip_path, Path(file_path), expected_content)
 
+            # Verify that collection TOMLs include both 'key' (legacy) and 'collection_code'
+            # (new name), so older software can still read archives produced after the rename.
+            self.check_toml_file(
+                zip_path,
+                Path("collections/col1.toml"),
+                [
+                    'key = "COL1"',
+                    'collection_code = "COL1"',
+                ]
+            )
+
             # Check the output message
             message = f'{lp_key} written to {file_name}'
             self.assertIn(message, out.getvalue())

tests/openedx_content/applets/backup_restore/test_restore.py

@@ -8,6 +8,7 @@
 from django.core.management import call_command
 from django.test import TestCase
 
+from openedx_content.applets.backup_restore.serializers import CollectionSerializer
 from openedx_content.applets.backup_restore.zipper import LearningPackageUnzipper, generate_staged_lp_key
 from openedx_content.applets.collections import api as collections_api
 from openedx_content.applets.components import api as components_api
@@ -353,6 +354,52 @@ def test_success_metadata_using_user_context(self):
         assert metadata == expected_metadata
 
 
+class CollectionSerializerTest(TestCase):
+    """
+    Unit tests for CollectionSerializer's back-compat handling of 'key' vs 'collection_code'.
+    """
+
+    BASE_DATA = {
+        "title": "My Collection",
+        "description": "",
+        "entities": [],
+    }
+
+    def _serialize(self, extra):
+        data = {**self.BASE_DATA, **extra}
+        s = CollectionSerializer(data=data)
+        s.is_valid()
+        return s
+
+    def test_legacy_key_field(self):
+        """Archives written before the rename use 'key'; restore must accept it."""
+        s = self._serialize({"key": "my-col"})
+        assert s.is_valid(), s.errors
+        assert s.validated_data["collection_code"] == "my-col"
+        assert "key" not in s.validated_data
+
+    def test_new_collection_code_field(self):
+        """Archives written after the rename use 'collection_code'."""
+        s = self._serialize({"collection_code": "my-col"})
+        assert s.is_valid(), s.errors
+        assert s.validated_data["collection_code"] == "my-col"
+        assert "key" not in s.validated_data
+
+    def test_both_fields_collection_code_wins(self):
+        """When both fields are present (new archives include both for back-compat),
+        'collection_code' takes precedence over 'key'."""
+        s = self._serialize({"key": "old-value", "collection_code": "new-value"})
+        assert s.is_valid(), s.errors
+        assert s.validated_data["collection_code"] == "new-value"
+        assert "key" not in s.validated_data
+
+    def test_neither_field_is_an_error(self):
+        """Missing both 'key' and 'collection_code' must fail validation."""
+        s = self._serialize({})
+        assert not s.is_valid()
+        assert "non_field_errors" in s.errors
+
+
 class RestoreUtilitiesTest(TestCase):
     """Tests for utility functions used in the restore process."""