Thoughts on Version Control for Block Themes

How do we handle version control for ongoing development of a block-based website? I’m not actually sure, but I’m outlining a few thoughts/goals as I think about the workflow here. My hope is to get some feedback from the wider developer community, to find out what’s been working and what tools are missing.

Keeping Templates in the Theme

Obviously the goal of Full Site Editing is to be able to edit the markup of your site in the site editor – but what if I want those changes tracked in a git repository (rather than relying on the revisions feature in WordPress)? Traditionally, we tracked layout and design updates in the theme.

For example, if I update my header or an archive layout, can those updates be stored in the theme so that I can commit them via git, track them visually, sync them between environments, deploy them and revert them quickly? And is this even the most desirable approach?

I understand that the editor’s Revisions feature is getting more robust, but I’m probably not alone in preferring to have a git-based version control workflow as well. The area where we’re seeing the most traction towards this is in the create-block-theme plugin, a tool that can manually export your templates and theme.json into a theme folder for distribution (though with a few caveats).

But.. in the era of block themes, what even are templates, layouts, patterns, etc? Why are they even different things?

Everything is a Pattern

From what I can tell, the trajectory that the site editor is taking is that everything can be a pattern. Reusable blocks became patterns. Template parts are becoming patterns. Partially-synced patterns are becoming a reality. Even create-block-theme turns the templates you built in the editor into patterns in your theme folder.

Think about that: create-block-theme converts templates you make in the editor (like your single.html) into a separate block pattern, then imports that pattern into the HTML template file via the Pattern block. Which is great! I like that a lot. But if you make actual patterns in the editor, for some reason they don’t get exported into your theme.

Pattern Manager from WP Engine handled this really well. You would build patterns in the editor, and they get stored in your theme as PHP files. Pattern Manager was even smart enough to let you edit patterns that you added to your theme manually: it was not storing even these patterns in the database, it was storing them in the theme. The theme becomes the one source of truth. Why is this important?

If you’ve ever used Advanced Custom Fields with multiple environments and multiple developers, you know that it can get tricky really fast. You’re constantly making sure everything is synced properly before making any edits because there might be two sources of truth: the filesystem and the database. ACF-JSON is great at attempting to solve that problem, but there are always some weird edge cases.

I believe the site editor needs to solve this problem by offering a comprehensive solution for managing template files in your theme, while still being able to edit them in the block editor. It needs to be intuitive and simple, reliable and well-supported.

My ideal approach (and should I work on making this a reality?)

I want the best of all worlds. In broad strokes

• I want the ability to store as much as possible as a pattern and use the (partially?) synced pattern block where ever appropriate. The general flow for design should be blocks 👉 patterns 👉 templates. Put individual blocks together to make a pattern, put a few patterns together to make the full page template. In that sense, the “pattern” as a concept should basically replace template_parts in WordPress.
• I want the ability to use the filesystem as the primary source of truth for block patterns, templates, and theme.json. Currently patterns added to a theme are not editable in the site editor. And patterns added via the site editor are not added to your theme with create-block-theme.
• When I save a change to a pattern or template (assuming I have ‘theme’ development mode enabled) that change is immediately reflected in my theme’s filesystem, not the database. No need to run a separate manual export process, I just want changes to what I consider the ‘theme’ to be saved in the ‘theme’ when my development mode is set to ‘theme’. Then I could use git to manage and deploy those theme changes across multiple environments.

I’m not saying I want this for everybody, but I feel like it would drastically improve the developer experience for block themes, especially in managed sites with a lot of ongoing development. I’m currently getting close to this by mixing create-block-theme and Pattern Manager, but it feels like we could get completely there with one solid tool. I’ve even considered pulling the best parts of those two tools and putting them together for this very specific use case.

If this were combined with partially-synced patterns and the Block Binding API, I think we’d have a really solid answer to the concerns around building your site completely in the site editor.

What are your thoughts? Would you want to be able to have all of your patterns, templates, and theme.json changes automatically synced to your filesystem so you could manage it with Git? Is there a better way?

Update: There’s now an official discussion on the Gutenberg repository for this: 59480

Update 2: Here’s another post worth checking out, Git going with FSE and Block Theme Development, by Claudio Rimann.

Update 3: Via BPH, the WordPress team hosted a hallway hangout to demo a process that involved Playground, Create-block theme plugin and GitHub for version control.