So, you get an email like this one every time WordPress publishes a new release. 4.2 just went out, so I got this email a few days ago. I’m not a serious plugin developer like most out there. They aren’t premium plugins; I just share my code because it’s helpful and it’s nice to know people use my stuff to help them do things. So, usually, I update my plugins after the release. Serious plugin developers are going to test their plugin before the release. For this tutorial, we’ll be updating it post release.
It’s good to let users know what version your plugin works on. When I looked at this list, I thought a lot of these plugins should work in 4.2, but people are probably not trying them because they are so outdated. This is not uncommon, especially if you’re just starting out or have that usual nine-to-five. I just got this email, so it totally sparked this post! Let’s get these updated!
In this tutorial you will learn how to:
- Use WordPress on Git to easily switch back and forth between versions for testing
- Update your plugin’s ‘Tested up to’
- Publish your changes to WordPress.org quickly
So, some pre-requisites.
- You have a local development setup and Git installed
- You have a plugin on WordPress.org that needs to be updated
- You developed your plugin using Git (we’ll be using Github here)
Let’s get started!
WordPress.org plugins (and WordPress itself) are hosted using SVN, but like a good amount of people building plugins, I develop my plugin primarily with Git and update my plugin on WordPress.org using a shell script. Some people don’t know that WordPress is actually on Github and you can clone it down, work on it, and even submit patches to it using Git!
So it’s nice to have WordPress on Github. It’s also nice to know that for each release of WordPress (e.g. 4.2) there is a release branch in the repo for that release (e.g. 4.2-branch). This makes it easy for us to switch versions of WordPress very quickly and easily.
Note: For security and hotfix releases such as 4.2.1, it lives in the 4.2-branch. Justin, another WDSer, tells me you can also check out specific releases using tags! But, know the 4.2-branch release branch is up to date with the latest 4.2.x.
As you can see, some of these plugins date back to version 3.3 [this email did spark this blog] of WordPress, most of them need to be updated. But some of these plugins don’t actually work with WordPress anymore, such as Google Destination URL. With the changes to Tiny MCE in WordPress 4.0, I couldn’t get the plugin to work the same as it had before. The last version it actually worked with was 3.9, and so I probably won’t be updating that since it doesn’t work in anything beyond 3.9 at the moment. So there are reasons not to update.
The plugin I’ll be updating today is one of my latest plugins, WP NoteUp. The last version I tested it in was version WordPres 4.1, so we’re going to test it in WordPress 4.2, and get it updated in no time.
First, get your localhost fired up
There are lots of different ways to do this, but you probably already have that set up for yourself. If not, check out Getting Started with Vagrant & VVV For Local Development for a great way to get started. Get a site setup that you can access locally, such as http://localhost/ or http://wordpress-tests.dev (as I have) and find the folder of the files for that site, that’s where we’re going to need to download WordPress from Github.
Clone WordPress from Github into that folder (here I’m using the command line, but a GUI would work too). Use what you like to use.
As you can see, I’ve cloned down WordPress from Github to my local environment to a folder I can access using http://wordpress-tests.dev. I’ll have to setup a database and install WordPress of course.
Git WordPress 4.2 (See what I did there?)
Now that we have WordPress setup for testing, let’s look at the repository we have cloned down locally. Having a look, we start off on the master branch, and if we use git branch -a we can see all the different release branches, let’s check out 4.2 (4.2-branch) using: git checkout 4.2-branch.
Let’s clone down our plugin
Now that we’re using WordPress 4.2, in a jiffy we can switch versions easily using Git. Let’s clone down our plugin now. Below, I will be cloning down my plugin from Github, but you might host your code somewhere else (this tutorial is Git dependent, not Github dependent). There are even ways to do this with the SVN version of your plugin with a few symlinks, but I won’t cover those here. All you need to end up with is your plugin in the plugins folder so it shows up in the plugins list.
Note: You might be asked to update your WordPress database when you switch–this is perfectly normal when switching versions. Also, I keep the latest stable version of my plugin on the master branch, but you might do something different. Make sure and check out the latest version of your code that was released to WordPress.org.
Now to actually test our plugin
Activate it and start testing things! For my plugin, I made sure things were working as normal. It’s a small plugin, so I just did a few small tests. Try to break it–try the new stuff added to the release and see if it breaks there. After trying to break WP Noteup, I was happy to see my plugin didn’t need any updates and worked great in 4.2. Your plugin might need updates, so code those and be prepared to release a new version of your plugin.
The last step is to make sure we tell WordPress.org that our plugin has been tested and works on version 4.2. You do this by updating your readme.txt file header that says Tested up to: and the version you tested it up to next to that. Edit your file, save, commit your change, and you’re ready to go!
Push to WordPress.org
I just updated my Github repo, but now I need to update WordPress.org via SVN. But we won’t be using SVN to push our changes (wut?!). We can use a single shell script to quickly update WordPress.org without having to mess with SVN (though I do recommend you learn how to). The script method only works on Mac/Unix (sorry my Windows friends, check out this on how to do it without the deploy script).
Use the script…
Note: The current readme on the script itself recommends you add it to your plugin’s code via subtree. This is optional, and I won’t be using that method for the rest of the tutorial.
First, I download the script and put it in my plugin’s directory.
Once the script is there, its usage is as follows: sh deploy.wordpress.org.sh [plugin_file_with_header.php] [WordPress.org Username] [Update Readme Only: true|false]
So what I want to type is: sh deploy.wordpress.org.sh wp-noteup.php aubreypwd true
This tells WordPress to deploy the plugin (sh deploy.wordpress.org.sh), find the plugin information (plugin header) in wp-noteup.php (sh deploy.wordpress.org.sh wp-noteup.php), my username on WordPress.org is aubreypwd (sh deploy.wordpress.org.sh wp-noteup.php aubreypwd), and just update the readme.txt file since we aren’t releasing another version (sh deploy.wordpress.org.sh wp-noteup.php aubreypwd true).
Note: In the case of someone releasing a new version of a plugin, you would set the last parameter from true to false. Make sure and update the Version section in the plugin header to the new version of your plugin before you do.
Let’s push our Tested up to changes to WordPress.org!
The deploy script sent everything to WordPress.org auto-magically! It probably saved me about 10 minutes worth of work. Shortly after I got an email from WordPress.org showing my changes (commits) were received!
Sometimes it can take up to fifteen minutes for the change on WordPress.org to take effect. But once it updated, the plugin’s page went from (see Compatible up to):
-to-
Though going through the tutorial the first time might be somewhat time-consuming, once you get the hang of it, this is a quick way to get the job done. Got another plugin? Clone it down, rinse, and repeat (make sure to deactivate other plugins). Now I’m off to go finish the rest of these off!
…before I leave.
I just wanted to point out one more awesome thing about using Git to test your plugins. Let’s just say we’re in a hypothetical situation where I need to test my plugin in WordPress 2.7 (just for fun)! Using Git it’s easy!
I just switch to it using: git checkout 2.7-branch
And now I’m running 2.7! Now I can test my plugin for that version as well, which does not work by the way:
Happy coding!
Resources
- WordPress is on Github
- Submit patches to it using Git
- WordPress.org Plugin deployment shell script
- Getting started with Vagrant & VVV for local development
- Updating your plugin using SVN (Windows Friends)
- Releasing Plugin Updates and Handling Security Vulnerabilities
If you have any suggestions, tips, or tricks up your sleeves, please leave them in the comment section.