Snippet `ManyToManyField` fields not handled properly by `RevisionMixin` and `DraftStateMixin`

Issue Summary

Changes to a snippet’s ManyToManyField selections are ignored by RevisionMixin. If DraftStateMixin is also used, those changes are lost when saving.

Steps to Reproduce

With the following models, do the following in the Wagtail admin:

1. Create some Category objects
2. Create a TestSnippet object
3. Edit the created TestSnippet, and change its Category selections
4. Open the snippet again, and verify the changes have been saved
5. View the revision history and compare the edited version to the original one
6. Expected output: category changes. Actual output: “There are no differences between these two versions”.

Now, also add in DraftStateMixin, migrate, and then:

1. Edit the snippet’s categories
2. Press Publish or Save draft
3. Open the snippet again
4. Expected outcome: the changes were saved. Actual outcome: the changes have disappeared.

@register_snippet
class Category(models.Model):
    name = models.CharField(max_length=255)

    panels = [FieldPanel('name')]


@register_snippet
class TestSnippet(RevisionMixin, models.Model):
    title = models.CharField(max_length=255)
    categories = models.ManyToManyField('app.Category', blank=True)
    _revisions = GenericRelation('wagtailcore.Revision', related_query_name='test_snippet')

    panels = [
        FieldPanel('title'),
        FieldPanel('categories', widget=forms.CheckboxSelectMultiple),
    ]

    @property
    def revisions(self):
        return self._revisions

Technical details

Django 4.1.3 Python 3.9.9 wagtail 4.1.1.final.1

[laymonage]

Thank you @mikaraunio! Pretty sure that ParentalKey and ParentalManyToManyField only changes the application-level representation of the fields, (i.e. the database representation is the same as that of ForeignKey and ManyToManyField), so there should be no data loss (as you confirmed).

For slightly more technical details, the RevisionMixin relies on the serializable_data() and from_serializable_data() methods to serialize/deserialize the fields (including relations) of the model instance. By default, it tries to call those methods from the superclass, and fall back to get_serializable_data_for_fields() and model_from_serializable_data() functions from django-modelcluster if none of the superclasses have the method:

https://github.com/wagtail/wagtail/blob/119f288a3cf91775687aafffe19ac4c92bb45e0a/wagtail/models/__init__.py#L278-L291

In django-modelcluster’s ClusterableModel, the methods are defined to handle the relations, and this is “where the magic happens” to make relations stored in the revisions correctly:

https://github.com/wagtail/django-modelcluster/blob/8666f16eaf23ca98afc160b0a4729864411c0563/modelcluster/models.py#L209-L273

So, yes, I believe this is the officially supported way. PR for documentation up at #9691.

[mikaraunio]

Confirm that switching from Model to ClusterableModel seems to make everything work here.

Also, have now switched over all my existing snippets to ParentalManyToManyField and migrated, and not seeing any data loss or oddities.

Would be good to have official confirmation that this is the way to go, and agree the docs should then be updated.

For others who might be facing this, here’s the “works for me” snippet:

@register_snippet
class Category(models.Model):
    name = models.CharField(max_length=255)

    panels = [FieldPanel('name')]


@register_snippet
class TestSnippet(DraftStateMixin, RevisionMixin, ClusterableModel):
    title = models.CharField(max_length=255)
    categories = ParentalManyToManyField('app.Category', blank=True)
    _revisions = GenericRelation('wagtailcore.Revision', related_query_name='test_snippet')

    panels = [
        FieldPanel('title'),
        FieldPanel('categories', widget=forms.CheckboxSelectMultiple),
    ]

    @property
    def revisions(self):
        return self._revisions