reviewers/models.py

@@ -58,6 +58,16 @@ class ApprovalActivity(CreatedModifiedMixin, RecordDeletionMixin, models.Model):
 
     @property
     def queue_sortkey(self):
+        """Sorting by moderation status and latest status change timestamp.
+
+        The queue is ordered by status: first "awaiting review', then "awaiting changes", then
+        "approved".
+        Within each group items with most recent status change are sorted to the top.
+
+        Integer timestamp representation takes 4 bytes, the resulting bigint is composed of
+        0x000000SSTTTTTTTT, where SS byte represents the status change type, and TT bytes represent
+        timestamp bytes.
+        """
         timestamp = int(self.date_created.timestamp())
         return (self.STATUS_CHANGE_TYPES[self.type] << 32) | timestamp