Exploring version control and Git workflows in block themes (Site Editor)

[ndiego]

This is an open discussion about how developers can approach using block themes, and specifically the Site Editor, if their workflows/projects require templates (and perhaps even content) to be version-controlled.

The Site Editor can get tricky. We want users to be able to use the Site Editor to make modifications to their site easily. But as soon as they do so, any version-controlled templates are overridden.

Version control and Git workflows have been a common discussion point, and it recently came up in the Hallway Hangout on overlapping problems in the Site Editor, which continued in WordPress Slack.

I know this has been a challenge that the Meta team (cc @ryelle, @adamwoodnz, @StevenDufresne, @renintw) has been tackling with WordPress.org when converting large sections of the site to block themes.

If you have a current process you are using, please share. If you have ideas on how WordPress could be improved to better support these types of workflows, share that as well. Let's get the ideas flowing! 💪

[ndiego]

This is not directly related to version control, but I do think more work around user management in the Site Editor could alleviate some of the challenges developers face. I recently opened a few issues about improving how user capabilities are handled in the Site Editor. I could also see a whole set of new capabilities specifically created for Site Editor interactions. (#56299, #56300)

For example, what if you could prevent specific users from editing theme templates entirely? They could create new ones, but the theme templates are locked (and presumably under version control).

[bacoords]

Here's a link to a blog post (Thoughts on Version Control for Block Themes) I wrote about this a while back, which has some comments from community members as well.

I summarized the big picture in a comment reply which I'll quote here:

I think if I were to boil down the major process gaps underneath this, I would have to say:

– version control broadly (getting templates/patterns into your theme more seamlessly, keeping them locked there)
– navigation block bringing back menu locations that aren’t tied to a post type
– content/access locking (more granular controls for both block locking as well as feature locking)
– truly synced patterns, where you can actually lock/control them in your theme but allow users to change minor aspects of content/design

The best tool currently is Create Block Theme, but the main issues are

1. Lack of pattern management (Add block pattern management create-block-theme#287)
2. Ability to have changes sync to the filesystem automatically, rather than manually (no issue, maybe I should open one)

I'll also note that Pattern Manager was another tool in this arsenal, but that repo is officially archived.

[mtias]

Create block theme is a great place to introduce dev tools that routes all changes done in the editor (templates, styles, patterns) through the filesystem and commits instead of hitting the db.

[fabiankaegy]

Thanks for creating this discussion!

I think that #59272 may have a large potential to improve some of these flows.

[gaambo]

Great discussion to have!

One thing that's common on sites I build: Archive pages (be it for posts or custom post types) often have some content before and after the query loop. For example before there may be a title, some text and after the posts there may be some banners like featured posts, featured categories, a contact banner, ...

Now I want editors/users to change the content around the query loop, but of course not the layout of the template or the query loop itself.

I could create a template, lock every block in it - except the parts that the user can modify (e.g. set them to contentOnly locking, so they can't remove them). But that means, even if the user wants to change something, they have to enter the site editor and edit the template. Typically, I don't give users/editors access to the site editor, since these are highly custom themes and I also don't want to explain to them the whole concept of the site editor (because that may be a burden on them). But also, as soon as the user would change some text, the template is stored in the database and I can't update it in the theme files / version control anymore - or actually I can, but it doesn't change/update the template.
There could be some workarounds for this with synced patterns maybe - where each editable part is a synced pattern. But that still means opening the site editor.

But what I do now, mostly, is creating "fake" archives by creating a page called "blog" or "events" with locking set up. The user can edit the page like any other page. But of course, I can't change the query loop / template from the file system/version control.
In my experience, for users it's easier to go edit a page than tell them to: "You can edit the about us page under pages, but the blog page is in the site editor with a completely different user interface and more options that you shouldn't touch". Because to them, it's just the same (it's a menu item which displays a page when clicked). But that's kind of off-topic.

Just wanted to share how I approach that problem. In the end, it often boils down to changing posts/pages by hand or writing migration-scripts in PHP which update post_content.

[ironnysh]

I hope I’m not breaking any rules by sharing a link to Shopify’s approach to this problem 🫣

I haven’t done any digging into the specifics, so not sure if there’s anything that could be relevant to WordPress. I can say that their GitHub integration was a game changer, and made my life as a theme developer much easier.

[ndiego]

Very interesting, thanks for sharing!

[skorasaurus]

I've had to just resort to always remind myself to make changes in the GUI site editor and then export but I'd love an alternative.
I made #22469 a while back to also spur discussion on this.

[crimann]

Hope it's ok to post this link here. I wrote a litte bit about our current approach to developing block themes, versioning and the pain points and adjustments we made to our workflow:
https://claudiorimann.com/git-going-with-fse-and-block-theme-development/

[unscripted]

This is a great post @crimann! It's almost exactly what we're doing.

Most of our team uses Tower as a GUI for Git and we recently discovered you can select the individual lines of a file you want to commit. This way when we overwrite the theme using the create block plugin, we aren't having to commit all of the changes in the file.

[onetrev]

Another thing I think to overcome in this area is bi-directional editing (Site Editor and code editor) of Patterns IF you have PHP in them. If code editor created patterns were allowed to be edited and exported for git purposes this wouldn't work right now I believe.

Adding Patterns via code is great so that you can have version control, but if you have PHP in your pattern (so image URLs work across domains, so the date is added dynamically, etc.), then the Site Editor will reject this code when you try to edit it (by copying and pasting in your pattern code). This is currently a pain point because it's much easier and faster to edit block code in the Site Editor than by hand.

[flexseth]

There isn't much documentation on how using Git can help with block development, either.

Not sure if Git is even much mentioned anywhere in the end-user or developer docs AFAIK.

This information could have a lot of crossover value in the Theme, Plugin, and Block Development handbooks.

I've been working on a notebook full of starting points, best practices, etiquette, and simple "How To's" that is an ongoing WIP.
Even linking to some tickets that show how someone really followed instructions, how managing code review works, etc.

The goal was to share this on the DevHub (developer.wordpress.org) for people who want to build blocks but don't have much experience with version control. Thinking about all the folks who are coming out of React code bootcamps and such, that could be a great asset to the WordPress Community.

+1 agree @ndiego! Having finally gotten version control mostly under my belt, it's saved a lot of time and heartache.

[LukaszJaro]

It looks like wordpress.com has launched github deployments, looks really good, if anything good example for .org.

https://wordpress.com/blog/2024/03/18/github-deployments/

[askdesign]

So happy to see this crucial topic being discussed! I'm a web designer on a Mac. This is my work-around:

Custom CSS

• create a Child Theme of 2024 (using the Create Block Theme plugin)

• clone the "style.css" and name it "style-additional.css"
  NOTE: I haven't yet figured out how to enable the "style.css", so I use this workaround instead.

• use the Additional CSS section in the site editor for any custom CSS.
  NOTE: I think the UI for the Additional CSS is horrible, so I copy all of my code into my file named "style-additional.css"

Theme Templates, Patterns, and Global Styles

• save changes to the theme using Create Block Theme plugin
• export the theme using Create Block Theme plugin

Github repo

• create a project repo on Github
• use Github Desktop to push the commits to the Github repo
  the changes include the "style-additional.css" file, as well as the exported theme