I recently wrote this quick guide on best practices for version control for our internal team. Because we work fully remotely and will often have multiple people working on the same project at the same time, these habits are especially important for us.
I’m sharing this guide on our blog because it can easily apply to your own projects, whether you’re working solo or as part of a team. The guide focuses on how we manage and store our custom child themes specifically, but the general rules can be applied more broadly.
A lot of these steps will add extra time early on in a project, but they completely make up for it when we get closer to the launch phase. These might feel unnecessary when we’re working solo in our local environment, but once it’s time to collaborate or share an environment with a teammate or client, these practices do pay off in saved time and fewer headaches.
At the very beginning of your project, start a new repository on Bitbucket for your theme
This repo should hold your child theme and be named the same as your child theme directory. Try to give your child themes a name specific to the project (i.e. dpp-child-theme or mykidney-understrap-child) so that everyone can easily identify what it is. Avoid more generic names (like understrap-child) that aren’t specific to the project.
Note: If you’ve started the child theme from the child starter theme then you’ll already have a proper .gitignore file in place.
Commit your changes (and push them to Bitbucket) often
It should never be a mystery where our code “lives”. I try to commit after every major feature or new design element I’ve built out. Most importantly, I like to commit and push to Bitbucket when I’m going to be “done” for the day or plan on stepping away from the project (unless something is so half-finished that the current code is non-functional, then I’ll just push the commits I have).
There’s a number of reasons for getting in this habit:
- It keeps a backup of the code offsite. In case your computer crashes, you’ll have a nice backup of your latest code handy.
- It keeps track of work you’ve done. It’s very helpful to have a record of all code changes, especially if you break something! This includes anything you deleted, but might want back later. I often go back through old commits when I realize I want to use some code I didn’t think I’d need.
- It makes collaboration easier. If you need help, you can easily point to a spot in your code by sharing a link to Bitbucket. If another developer needs to jump in, you can both work on the code at the same time. If you need to step away from work for a personal emergency or hand the project off to someone, it ensures that a new dev can pick up where you left off without tracking down your code.
- It helps you improve your time management. Paying attention to each commit helps you think about your project as distinct ‘tasks’ instead of one giant THING. One of the hardest parts of being a developer is estimating how long something will take. We all tend to underestimate how long it will take to build a feature. The more that you break your work into smaller parts and see how long they take, the better you can get at predicting your own time. Think about each commit before you start coding, try to guess how long it will take you, and see how close you were.
You should be committing your code at least daily, but ideally more often throughout the day.
Use acf-json/ for your ACF Fields
Did you know that you can simply add an ./acf-json/ directory to your theme folder and all of your ACF fields will be synced to your theme when you save them locally? Then you can just click the ‘sync’ button on the dev or live site and the ACF fields will update themselves to match your local environment. This saves a TON of time in copying/exporting/duplicating field groups, which can lead to weird bugs. Learn More
How to push code from local to the dev site
This is the hardest part because there’s still no perfect way to handle this. The general rule of development is that “code” can be pushed UP (from local to dev to live) but the “database” should only be pulled down (from live to dev to local).
I’m sure most of us are using the app Local because it integrates so nicely with our WPEngine dev sites. The downside is that when we’re building out a new site, we’re often writing code AND creating new content in the database. This is where it gets tricky.
So at first, building the site locally and pushing the whole thing from local to dev is the quickest way to get started. This is normal for the early stages, but once we get further along in development, this process may no longer work.
I think a good rule of thumb looks like this:
- If you’re the ONLY person working on a site (no other devs, the clients haven’t seen it yet), it’s probably fine to push your whole Local instance up to a dev site on WPEngine. Just make sure not to include your node_modules folder.
- Once there’s more than one person involved, though, you’ll want to stop pushing anything through Local. What tends to happen is one person makes a change, then someone else pushes something else up and overwrites that change.
Working solo — continue to use local for pushing stuff up
To reiterate, it’s probably fine to just push everything up from local to dev when no one else is touching the site. Just remember to keep committing those code changes and pushing them to Bitbucket.
Collaborating — we’re only pushing code up with Git/WP Pusher
If we’re collaborating on the code, since we have everything managed with Git, we can let someone else contribute and there’s a nice easy process for merging our code together.
As for changes to content, once you’ve made it this far, you should plan to make all database changes on the dev site and pull them back down to your local. Or if it’s a small change, make it in both places just to keep things moving.
This is when we want to set up our theme’s repository to deploy automatically to the site using WP Pusher. (We’ll do a full write-up on WP Pusher later.)
More Resources
- ACF JSON
- This lesson in the Understrap Course
- Local PRO is free