feat: publishing dependencies and state tracking (#369)

This commit introduces the idea of dependencies to the publishing app.
Dependencies are a generalization of unpinned container children that
we plan to later use for things like course files & uploads, grading
policies, and other things where a change in one publishable entity
affects the state of another publishable entity, even if they do not
share a direct parent/child relationship.

Dependencies do not *replace* container children, but they offer a
simpler model that allows the publishing app to quickly calculate
things like, "Do any of the transitive dependencies of this entity
have unpublished changes?". It also means that we can efficiently
implement "publish this entity and all its dependencies at the same
time" without having to use any callbacks to other apps that might
implement different kinds of dependency relationships (e.g. grading
policy). As long as those other apps declare their dependencies when
calling create_publishable_entity_version(), the publishing app will
have enough information to do these types of queries.

It's worth noting that we never really wanted to put container logic
directly in the publishing app, but we were forced to because the
process of publishing is so coupled to parent/child relationships.
This shift to thinking about dependencies rather than children will
make it possible for us shift container logic out of publishing and
into its own app.

This commit also creates the PublishSideEffect as the publishing
equivalent to DraftSideEffect. We've come to the tentative decision
that we should probably try to unify some of these parallel draft/
published models, but that will be a bigger undertaking.

This commit also introduces a dependencies_hash_digest field to
DraftChangeLogRecord and PublishLogRecord in order to track the state
of all live (current draft/published) dependencies. Tracking this has
allowed us to optimize contains_unpublished_changes() to be a single
query.

Finally, this commit adds Django admin functionality for this new
data. This admin interface is still rudimentary though, and could use
a lot of work.
---------

Co-authored-by: Kyle McCormick <[email protected]>

Author: ormsbee

openedx_learning/__init__.py

@@ -2,4 +2,4 @@
 Open edX Learning ("Learning Core").
 """
 
-__version__ = "0.29.1"
+__version__ = "0.30.0"

openedx_learning/apps/authoring/publishing/admin.py

@@ -6,7 +6,7 @@
 import functools
 
 from django.contrib import admin
-from django.db.models import Count
+from django.db.models import Count, F
 from django.utils.html import format_html
 from django.utils.safestring import SafeText
 
@@ -21,6 +21,7 @@
     EntityListRow,
     LearningPackage,
     PublishableEntity,
+    PublishableEntityVersion,
     PublishLog,
     PublishLogRecord,
 )
@@ -48,6 +49,7 @@ class PublishLogRecordTabularInline(admin.TabularInline):
         "title",
         "old_version_num",
         "new_version_num",
+        "dependencies_hash_digest",
     )
     readonly_fields = fields
 
@@ -89,28 +91,89 @@ class PublishLogAdmin(ReadOnlyModelAdmin):
     list_filter = ["learning_package"]
 
 
+class PublishableEntityVersionTabularInline(admin.TabularInline):
+    """
+    Tabular inline for a single Draft change.
+    """
+    model = PublishableEntityVersion
+
+    fields = (
+        "version_num",
+        "title",
+        "created",
+        "created_by",
+        "dependencies_list",
+    )
+    readonly_fields = fields
+
+    def dependencies_list(self, version: PublishableEntityVersion):
+        identifiers = sorted(
+            [str(dep.key) for dep in version.dependencies.all()]
+        )
+        return "\n".join(identifiers)
+
+    def get_queryset(self, request):
+        queryset = super().get_queryset(request)
+        return (
+            queryset
+            .order_by('-version_num')
+            .select_related('created_by', 'entity')
+            .prefetch_related('dependencies')
+        )
+
+
+class PublishStatusFilter(admin.SimpleListFilter):
+    """
+    Custom filter for entities that have unpublished changes.
+    """
+    title = "publish status"
+    parameter_name = "publish_status"
+
+    def lookups(self, request, model_admin):
+        return [
+            ("unpublished_changes", "Has unpublished changes"),
+        ]
+
+    def queryset(self, request, queryset):
+        if self.value() == "unpublished_changes":
+            return (
+                queryset
+                .exclude(
+                    published__version__isnull=True,
+                    draft__version__isnull=True,
+                )
+                .exclude(
+                    published__version=F("draft__version"),
+                    published__dependencies_hash_digest=F("draft__dependencies_hash_digest")
+                )
+            )
+        return queryset
+
+
 @admin.register(PublishableEntity)
 class PublishableEntityAdmin(ReadOnlyModelAdmin):
     """
     Read-only admin view for Publishable Entities
     """
+    inlines = [PublishableEntityVersionTabularInline]
+
     list_display = [
         "key",
-        "draft_version",
         "published_version",
+        "draft_version",
         "uuid",
         "learning_package",
         "created",
         "created_by",
         "can_stand_alone",
     ]
-    list_filter = ["learning_package"]
+    list_filter = ["learning_package", PublishStatusFilter]
     search_fields = ["key", "uuid"]
 
     fields = [
         "key",
-        "draft_version",
         "published_version",
+        "draft_version",
         "uuid",
         "learning_package",
         "created",
@@ -120,8 +183,8 @@ class PublishableEntityAdmin(ReadOnlyModelAdmin):
     ]
     readonly_fields = [
         "key",
-        "draft_version",
         "published_version",
+        "draft_version",
         "uuid",
         "learning_package",
         "created",
@@ -130,21 +193,55 @@ class PublishableEntityAdmin(ReadOnlyModelAdmin):
         "can_stand_alone",
     ]
 
-    def draft_version(self, entity: PublishableEntity):
-        return entity.draft.version.version_num if entity.draft.version else None
-
-    def published_version(self, entity: PublishableEntity):
-        return entity.published.version.version_num if entity.published and entity.published.version else None
-
     def get_queryset(self, request):
         queryset = super().get_queryset(request)
         return queryset.select_related(
-            "learning_package", "published__version",
+            "learning_package", "published__version", "draft__version", "created_by"
         )
 
     def see_also(self, entity):
         return one_to_one_related_model_html(entity)
 
+    def draft_version(self, entity: PublishableEntity):
+        """
+        Version num + dependency hash if applicable, e.g. "5" or "5 (825064c2)"
+
+        If the version info is different from the published version, we
+        italicize the text for emphasis.
+        """
+        if hasattr(entity, "draft") and entity.draft.version:
+            draft_log_record = entity.draft.draft_log_record
+            if draft_log_record and draft_log_record.dependencies_hash_digest:
+                version_str = (
+                    f"{entity.draft.version.version_num} "
+                    f"({draft_log_record.dependencies_hash_digest})"
+                )
+            else:
+                version_str = str(entity.draft.version.version_num)
+
+            if version_str == self.published_version(entity):
+                return version_str
+            else:
+                return format_html("<em>{}</em>", version_str)
+
+        return None
+
+    def published_version(self, entity: PublishableEntity):
+        """
+        Version num + dependency hash if applicable, e.g. "5" or "5 (825064c2)"
+        """
+        if hasattr(entity, "published") and entity.published.version:
+            publish_log_record = entity.published.publish_log_record
+            if publish_log_record.dependencies_hash_digest:
+                return (
+                    f"{entity.published.version.version_num} "
+                    f"({publish_log_record.dependencies_hash_digest})"
+                )
+            else:
+                return str(entity.published.version.version_num)
+
+        return None
+
 
 @admin.register(Published)
 class PublishedAdmin(ReadOnlyModelAdmin):
@@ -197,6 +294,7 @@ class DraftChangeLogRecordTabularInline(admin.TabularInline):
         "title",
         "old_version_num",
         "new_version_num",
+        "dependencies_hash_digest",
     )
     readonly_fields = fields