New code is released for Ashford when there are new features, bug fixes or new WordPress requirements. Some releases explicitly state that if you are not careful, it will break your site.
While, the basic instructions for upgrading to the newest release of Ashford are simple. This post will lead you step by step on how to upgrade a custom child theme:
- Organize your code
- Identify and track your changes
- Get the right software
- Save your code
- Test your changes
- Commit your changes to production
The point of going through this process is to successfully identify your changes and migrate them to the new release. This way you get all the benefits of the new release while maintaining your customizations.
Organize your code
The first thing is to organize your code. I have a two folders: release and production. The release folder is an archive of the released code as you download it from me. While production is the code as you find it on your servers. The code may be exactly the same if you never modified the child theme. If that is the case, then you can just follow the simplified upgrading instructions. This post assumes you made changes (even small ones) to the child theme.
The preferred way to modify your theme is to only make changes to the child theme but to leave the parent theme alone. If you have questions, please read the Dev Child Theme documents.
So the first step in upgrading to the new release:
- Download your existing production version of Ashford and Pro themes and save them to your production folder
- Download the newest releases of Ashford and Pro and save them to your release
Identify and track your changes
With the code now saved you are ready to figure out what has changed between the official released code and your production code. The first thing is to identify and track your customizations to Ashford and your child theme. Admittedly this requires discipline that I do not always possess. I do my best to track my changes:
- Add PHP documentation when you modify your child theme files
- Add comments in for CSS and JavaScript
- Summarize the changes in the readme.txt file and save to your child theme
If did not do this when you created your child theme, it may be difficult unless you have an unmodified copy of Ashford and Pro. This may be obvious, but to find your changes, compare your production code against the official release of the SAME version.
For example, I am writing this post as I update a v2.0 custom theme to v2.2. To figure out what I modified, I am comparing my production code: ashford to ashford and ashford_pro to my_custom_theme.
Find the right tools
To make documenting your changes easier, you will need some software that will help you create a “diff”. A diff is a file that shows the differences between files. So this software will help you identify and track your changes. I highly recommend WinMerge for Windows (Sorry I do not have a great Mac recommendation. Please add to comments if you do).
WinMerge allows you to diff a single file or an entire folder. When I am doing this work, I compare the released code against my production code folders. For example, if I am running Ashford and Pro v2.0 — I will first compare my production code against the v2.0 release.
WinMerge produces a list of all the files it finds. I sort by “comparison result”. So I get all the identical and different files grouped together. The other thing it will do is identify files that exist in one or the other folders. It will do PHP, HTML, CSS and JavaScript files.
- Click on the different files and review the diff
- When I find a difference, I make sure it is commented
- Then I note it the readme.txt file
At the end of this process, I should know exactly what files (including images) I have modified and why.
For example, I know that my child theme modified the functions.php, style.css and several page templates. It also add several images. I documented these changes in the files themselves — then created a readme.tx file in my child theme folder which summarized these changes.
Now I have well a documented child theme that is ready to compare to the newest release.
Migrate your changes to the new release
So now, you have identified and documented all your changes by comparing your child theme against the official release. Now you need to migrate those changes to the new release which will result in the new release with your custom code.
- Clone the current release of Ashford Pro
- Rename it according to your child theme
- Run a diff between your production child theme and Pro
- You only need to be concerned with migrating the changes you identified in the previous step
- You might want to review each changed file line by line just to bullet proof your migration but this is not necessary
This does not mean that your new theme will not break. Keep in mind that there may be lots of changes to sort out, yours plus those made by me and some may conflict. There will be times that you will need to do more than just copy and paste.
The place where I have the most problems is with style.css but if you are patent you can fix any bugs introduced by the release.
Test your changes
It is recommended that you test your new theme in a stagging environment rather than production. Even if you can not duplicate your site (content), you can easily run a “test” site running “test” content. Apply your theme in that environment to see if their are problems.
The Ashford test site runs with content downloaded from the WordPress Theme Unit Test page.
Commit your changes to production
- Recheck that you have properly saved your production code in case your changes need to be reverted.
- Delete BOTH the ashford and child theme folders off your server
- Upload BOTH the ashford and child theme folders to your server
I prefer to do this manually rather than using steps outlined on our upgrading page. You will know you are successful when your site looks exactly the same, yet is running your new theme.
I have been writing this post over many weeks and a couple “upgrades” to custom themes. Let me know if I’m missing anything or if there is a way to improve it.