Describe role of Grouping and how it relates to Issue

third time's a charm (5e5b53abed, 48307daa0f)

ingest/views.py

@@ -228,7 +228,8 @@ class BaseIngestAPIView(View):
                 Max("digest_order"))["digest_order__max"]
             issue_digest_order = max_current + 1 if max_current is not None else 1
 
-            # if the grouping doesn't exist, the issue doesn't exist either (because a grouping implies an issue).
+            # at this point in the code, "new grouper" implies "new issue", because manual information ("this grouper is
+            # actually part of some other issue") can by definition not yet have been specified.
             issue = Issue.objects.create(
                 digest_order=issue_digest_order,
                 project_id=event_metadata["project_id"],

issues/models.py

@@ -121,8 +121,12 @@ class Issue(models.Model):
 
 
 class Grouping(models.Model):
-    """A Grouping models an automatically calculated grouping key (from the event data, with a key role for the SDK-side
-    fingerprint).
+    """
+    Grouping models the automatic part of Events should be grouped into Issues. In particular: an automatically
+    calculated grouping key (from the event data, with a key role for the SDK-side fingerprint).
+
+    They are separated out into a separate model to allow for manually merging (after the fact) multiple such groupings
+    into a single issue. (such manual merging is not yet implemented, but the data-model is already prepared for it)
     """
     project = models.ForeignKey(
         "projects.Project", blank=False, null=True, on_delete=models.SET_NULL)  # SET_NULL: cleanup 'later'