Our goal when building your website is to ensure it’s flexible enough for a non-technical person to maintain over the long-term, so you shouldn’t need to make code changes. But if you want to make some changes to the styling or functionality if your website, we recommend you follow the approach outlined below.
When building your site, we used git to version control our custom code – the theme and core functionality plugin. We highliy recommend you continue using the git repository we have set up for you.
You can of course maintain the website in any manner you choose, but if you make non-version-controlled code changes (ex: direct editing files on the server), make sure you tell us before requesting us to make changes so that we don’t accidentally overwrite your changes.
What is git / version control?
Version control allows you to maintain a history of code changes. Instead of just having the current version of files (like on your server) we can see every version of those files, who made edits and when. If there’s an issue, we can easily see what changed and revert it.
Multiple developers can work on your website at once, without worry about overwriting each other’s changes. We can easily deploy changes to different environments (ex: staging vs production).
Using git with WPEngine
Setup local development environment
Note: items in brackets needs to be updated to match your specific needs.
- Install WordPress locally. You can use MAMP, Local, or other tools. I also recommend you setup wp cli.
- In the My WPEngine, go to Backup Points, select the most recent backup, and click “Download Zip”. You could download a full backup (and skip the steps below for sourcing media from production), but for large sites I like doing a partial backup excluding media. Select “Partial Backup” and check everything but “Media Uploads”. Set the email address to your own and you’ll be emailed a zip file.
- Copy over the appropriate files to your local WP install (themes, plugins). Do not include the mu-plugins directory; that contains WPEngine specific code.
- Import the database locally, using phpMyAdmin, direct SQL query, or Migrate DB Pro (pulling from production or staging).
- Update the URLs in the local database. Using wp cli:
wp search-replace $(wp option get siteurl) http://wp.dev/mywebsite, where the last URL is your local site’s URL. If you don’t have wp cli, try Search Replace DB.
- Delete the theme
wp-content/themes/[theme_name]and the plugin
- At the top level of the site, in terminal run
git remote add origin email@example.com:billerickson/[repo_name].git
git pull origin masterThis will pull down the version controlled theme and plugin.
- Add the staging and production remotes, for pushing updates:
git remote add staging firstname.lastname@example.org:staging/[wpe_name].git
git remote add production email@example.com:production/[wpe_name].git
If sourcing media from production
- Install BE Media from Production in the
- Create a local-settings.php file in
wp-content/mu-plugins. Update the URL to match the source of media (ex: live site URL).
You should now have a fully functional copy of the site running locally.
Small Change Workflow
This approach can be used for small changes that need to go live immediately.
- Make sure you have an up-to-date copy of the repo locally (
git pull origin master)
- Make your small change directly to the master branch
- Push to GitHub (
git push origin master)
- Push to staging environment so others can review (
git push staging master)
- Once approved, push to production environment (
git push production master)
Feature Contribution Workflow
For larger features that will take time to implement, require extensive review, and/or have multiple people working on it, it’s highly recommended you make your code changes in a separate branch. Once approved, this branch can be merged into master.
- Create an issue for your bug/feature if one doesn’t already exist
- Make sure you have an up-to-date copy of the master branch locally.
git pull origin master
- Create a branch from master with the name matching the issue number. For instance, for issue #30 we would run
git branch issue/30. Then checkout the branch:
git checkout issue/30
- Make your code changes to this branch
- Submit a pull request describing the change and citing the original issue number.
- If any changes are needed to your patch, make them to your branch and push up (
git push origin issue/30). They will automatically appear in the pull request
- Once the pull request is approved, the code will be merged into master. You may safely delete your branch.