We had a nice open session this afternoon at PyCon US, organized by Sean Harrison from Caktus Group. There were about 15 people in the room. The session agenda was generally to discuss improving Wagtail for developers.
Adding fields or blocks won't cause problems as long as you don't rename or removing anything.
Sean presented a nice multi-step approach that he recommends when migrating StreamFields. This way you can run each step independently and verify that it worked correctly.
- First add the new field or block (example).
- Make a migration that copies the data from old fields to new fields, but don't remove anything yet (example).
- You need to iterate over all pages and all revisions of those pages.
- It helps to use
page.to_json()and process both page and revision JSON in the same way. - Wagtail documentation currently doesn't really cover how to do this.
- Attendees agreed that it would be convenient if the Wagtail codebase included some utility functions to help with this, for example something like this from Sean's example.
- CFPB has implemented a very similar approach to Caktus, documented here.
- We mentioned the currently open Wagtail PR #4755 which is an attempt to add programmatic support for StreamField migrations.
- Let editors review migrated pages to verify that everything looks good, before removing anything.
- Delete old fields (example).
Vince Salvino from CodeRed CMS talked a bit about some problems with the large migration files that can be generated when StreamFields are changed.
We mentioned Wagtail issue #4298 which discusses some ways of reducing migration file size. It's also interesting to consider whether StreamField block structure really needs to be persisted to the migration files.
Sean discussed his fork of wagtail-import-export.
He has an open PR that adds support for exporting/importing of images and snippets along with pages. It's a tricky problem to re-map IDs when importing. Caktus uses page URLs as the identifier for pages, and we talked about how since 2.2 Wagtail has file_hash that can be used for documents and images.
We briefly discussed that the current StreamField documentation is overdue for a rewrite:
It's a single giant page, and hard to find the information you need. It doesn't cover all use cases, for example migrations as mentioned above. It would be nice to refactor this into several different pages.