How to upgrade your Museum Theme to the most current version after you’ve made changes to the files

Our themes are released under the GPL. That means that you are free to take them, change them, and even redistribute them under the terms of the GNU Public Licence. We’ve seen what a couple of you have done with our themes and we couldn’t be happier to see you taking our code and bending it to fit your site.

But what happens when there’s a new version and you want to upgrade?

The first things you’ll want to do to keep your customizations and also keep the core code up-to-date is to create your own “fork” of the theme. This is a lot less complicated than it sounds, and all it means at this point is to rename the folder that holds the theme files (so if you’re using Museum zine, you could change the folder name from AP-Museum_zine to YourDomain-Museum_zine or YourDomain_zine or just YourDomain — whatever you want as long as it makes sense to you) and to make some minor edits to the main stylesheet (style.css).

Why do you need to edit the stylesheet if you’re not making any CSS changes? Well, WordPress checks the style.css to grab some basic information that’s used on the Appearance → Themes page. All of that stuff is located above all the code, so if we’re looking at zine again, you’d see this:

/*
Theme Name: AP-Museum zine
Theme URI: http://www.arcanepalette.com
Description: AP Museum zine is a set of grungy, magazine-style themes inspired by the underground fanzine movement
Version: 1.1
Author: Arcane Palette Creative Design
Author URI: http://www.arcanepalette.com
*/

If you have two themes with the same name in the Themes page, both will display, but it gets confusing (for the record, WordPress tells you the location of the files underneath the description, where it says All of this theme’s files are located in /themes/AP-Museum_zine so even if you skip this step, you can still sort of tell which is which). So what you may want to do is change the Theme Name so it appears as something different on the Themes page. All you need to do is change AP-Museum zine next to Theme Name: to something else of your choosing.

Congratulations, you’re now officially a theme developer and have made your own version of a WordPress theme! (If you wanted to distribute it to others at this point, there’s a few more things you’re required to do by the GPL before you’re good to go on that point, and “forks”, in particular, have some special rules. It’s a good idea to be familiar with the terms of the GPLv3 — which is what our themes are released under — before actually releasing your own theme. For the most part, however, you probably don’t have any intention of redistributing your theme, so you don’t need to worry about GPL guidelines or restrictions — the GPL only affects you in that sense when you choose to distribute your theme — customizing your theme for your own personal use is fair game.)

Nothing we’ve done so far has actually changed anything. In reality, you’ve already changed the theme, so all we’re doing is changing the name and the directory to reflect that. (As such, any of the other things in the style.css you want to change, like the version or the author, you’re free to do also.) Now we’ll concentrate on incorporating the new code into your theme (or vice-versa: your customized code into the new version). To do that, you first need to know what files you’ve changed. Every time a piece of GPL software is modified, the new version is required to include some form of documentation saying what you changed and when. This is primarily to keep developers accountable for their code, so that if you fork a piece of software, someone else can come along and figure out where the software was forked from the original source and what things were added or changed. But even more than that, keeping this kind of documentation — which can be in the form of a Changelog — keeps you honest, and provides important reference notes for when you need to make future updates. All our themes include a changelog.txt file in the theme folder which includes all the changes up to that date. You may want to check this before you start so you know what we updated in the new version. It might save you some work if you’ve modified a file that we didn’t make any changes to this time around — in that case, you could just keep your version rather than copying your code into the version of the file included in the theme zip package.

Let’s say you’ve edited the header (header.php), the sidebar (sidebar.php) and the single post template (single.php). The first thing you’ll want to do is put those files aside — create a temp directory within your theme and copy those files in, or just copy them to the desktop. For that matter, it’s probably a good idea to back up your whole theme, just in case there’s anything you might have forgotten about. Once you’ve gotten your customized files out of the way — including the style.css that you just modified — copy the contents of the updated theme into your theme folder. This will most likely involve extracting the zip somewhere on your computer, then navigating to that folder, selecting all the files inside and copying/pasting them into your theme.

Occasionally, we reference specifically in the changelog what files we’ve created or modified, and moving forward we’ll be doing a better job of being more specific in this regard. If it doesn’t look like we’ve made any changes to any of the files you’ve modified, you can just copy your customized versions into the theme folder and be done. However, if we (explicitly or implicitly) reference in the changelog that we updated any of the files you’ve customized (including changes to style.css, which should be fairly rare in most cases), you’ll need to go into your version and copy your customizations into the code of the updated version. Presumably you remember (or at least have a general idea) of what you did last time, and if all the code surrounding yours remained the same (which it should), it will be fairly easy to do a stare-and-compare with the two files and figure out what you need to do.

If you’ve been making the changes live on your site, everything should be ready to check and make sure it worked at this point. If you’ve been editing the files offline (recommended), you should be good to upload them and see if anything else needs to be tweaked. Now’s when you’ll find out if your customizations were actually limited to the files you updated in the new version, or if there were other modifications that slipped your mind. However, if you have a backup of the original theme, you can always go back, find what you added, and copy that into the new version of that file, too.

That’s it. Now you’ve got all the benefits of the new version of the software with your own customizations. If you have any questions along the way, feel free to let us know in the Support Forums. If you’re using a modified version of our Museum Themes, we’d love to see links posted in the comments!