[RFC 3/3] models: Add 'Series' model and related models

[Finucane, Stephen]

On 08 Apr 14:50, Andy Doan wrote:
> On 04/01/2016 11:14 AM, Stephen Finucane wrote:
> >Add a series model. This model is intentionally very minimal to allow
> >as much dynaminism as possible. It is expected that patches will be
> >migrated between series as new data is provided.
> >
> >Signed-off-by: Stephen Finucane <stephen.finucane at intel.com>
> >---
> 
> >diff --git a/patchwork/models.py b/patchwork/models.py
> 
> >+ at python_2_unicode_compatible
> >+class Series(models.Model):
> >+
> >+    group = models.ForeignKey(SeriesGroup, related_name='revisions',
> >+                              related_query_name='revision', null=True,
> >+                              blank=True)
> >+    date = models.DateTimeField()
> >+    submitter = models.ForeignKey(Person)
> 
> Given this is a 1-to-1 with a CoverLetter, date and submitter become
> duplicate data. date is just series.cover_letter.date.

This is true...assuming (a) we have a cover letter for the given series
and, (b) if there is a cover letter, we have actually received it
before receiving any other patch in the series. We can't rely on either
of these, thus the duplication. I've documented the same.

> >+ at python_2_unicode_compatible
> >+class SeriesReference(models.Model):
> >+    """A reference found in a series.
> >+
> >+    Message IDs should be created for all patches in a series,
> >+    including those of patches that have not yet been received. This is
> >+    required to handle the case whereby one or more patches are
> >+    received before the cover letter.
> >+    """
> >+    series = models.ForeignKey(Series, related_name='references',
> >+                               related_query_name='reference')
> >+    msgid = models.CharField(max_length=255, unique=True)
> >+
> >+    def __str__(self):
> >+        return self.msgid
> 
> Having a little trouble envisioning how this gets used. I'm sure
> you've thought this out, but would it be possible to create some
> kind of "incomplete" or "future" Series object instead of needing
> this type of object?

The approach I'd originally envisioned was to use the message-id of the
cover letter (cached on series, like 'date' and 'submitter' above). The
problem with this is figuring out what this message-id is. There are a
couple of different scenarios that we could find ourselves in:

1. Shallow threaded series

The most common format to receive patches (though by no means the only
one, and not even the default in older versions of Git). Each patch is
a reply to the cover letter (or the first patch, if no cover letter).

    [PATCH 0/3] A cover letter
      [PATCH 1/3] The first patch
      [PATCH 2/3] The second patch
      [PATCH 3/3] The third patch

2. Deep threaded series

Less common today, but available in Git and the default in older
versions of Git. Each patch is a reply to the previous patch (or the
cover letter, if it's the first patch).

    [PATCH 0/3] A cover letter
      [PATCH 1/3] The first patch
        [PATCH 2/3] The second patch
          [PATCH 3/3] The third patch

3. Shallow threaded series follow-up

Same as (1), but a vN+1 in reply to a vN series.

    [PATCH 0/3] A cover letter
      [PATCH 1/3] The first patch
      ...
      [PATCH v2 0/3] A cover letter
        [PATCH v2 1/3] The first patch
        ...

4. Deep threaded series follow-up

Same as (2), but a vN+1 in reply to a vN series.

    [PATCH 0/3] A cover letter
      [PATCH 1/3] The first patch
        [PATCH 2/3] The second patch
          [PATCH 3/3] The third patch
      [PATCH v2 0/3] A cover letter
        [PATCH v2 1/3] The first patch
          [PATCH v2 2/3] The second patch
            [PATCH v2 3/3] The third patch

NOTE: v2 could be sent in-reply-to any patch in the series, really.

There are more options that the above, but this is good enough: finding
a message-id that all series can reference is hell. The solution I have
is to store all found references and link them to a given series. That
way, I can traverse the references looking for matches. If I find one,
I have my series. If not, I need to create a new series.

Does that help,
Stephen