How to publish your first WordPress plugin
In a recent post, I shared details on How to build your first WordPress plugin, and it received some rave reviews and ton of shares. A key to that post was that I didn’t get into the weeds of learning PHP, the WordPress API, or all of the possibilities when it comes to developing a plugin. While that made people who were just learning happy, I’m sure it made some professional developers cringe.
In all honesty, that’s how I started, though. I didn’t like learning a language professionally, understanding enterprise infrastructure theory, user experience training and everything else that goes with great development. That came later with a couple decades of making some awful mistakes and having to redevelop platforms from the ground up. Most of us just need something that works.
So, you’ve developed a great WordPress plugin that conforms to the WordPress.org plugin guidelines, and you’ve decided that you wish to share it with the world! There’s nothing more exciting than publishing a plugin and having it be found and shared from the WordPress repository — accessed by millions of WordPress users!
Why publish your WordPress plugin?
Outside of your plugin being found and instantly downloaded, the other advantages of publishing your WordPress plugin in the WordPress Repository are:
- Version control — you can maintain a history of every version of your WordPress Plugin and collaborate on it with other developers using Subversion, a version control software deployed on the WordPress Repository servers.
- Update alerts — Alert users of updates so they can automatically update your plugin as you fix bugs and add features.
- Provide support — The Repository allows registered WordPress users to review and rate plugins as well as request support through the interface. That means you don’t have to worry about managing support externally.
About Subversion version control
Subversion commands are executed from the command line on OSX, where it’s installed natively. You can also download Subclipse, a Subversion plugin for Eclipse, or TortoiseSVN, a popular Windows Subversion client.
I am no master of Subversion, often making a ton of really dumb syntax errors. That said, I’m just here to share the basics of getting started. This is not a full tutorial on all the amazing things you can do with Subversion. You can find those details in the Subversion book for free online.
Some Subversion vocabulary
Let’s get versed in the language of Subversion …
- Repository — the central platform where developers store and retrieve their work. By storing changes in the repository, those changes are made available to other developers. In the case of WordPress, the WordPress repository is integrated directly into the plugin and theme update and publishing processes. Pretty cool!
- Trunk — a directory where active development occurs.
- Tags — a directory with every version of your plugin. I tend to number my versions with three digits, like 1.0.0, with the first digit being a major rewrite, the second digit a feature update, and the third digit a bug fix.
- Check out — the process where you check out the plugin for development and all changes or updates are copied locally. If you’ve never checked out a plugin before, it will copy all the assets, tags and trunk locally.
- Commit — after you’ve tested updates to your plugin, you commit the change. This is typically pushing a new version via an updated tag, which then publishes to the repository. If the tag number of your update in your readme.txt file is greater than what’s in the plugin version on a client’s installation, it will alert them that a new plugin is ready to install.
Register and request plugin distribution with WordPress
A first step to using the repository is registering with WordPress. The next step is to submit your plugin for distribution in the WordPress Repository. The team will also let you know how many new plugins are in the review queue. You only have to make the request once, and then the team will review your plugin and approve it for inclusion (as long as you don’t have any glaring issues).
Pro tip: Keep your plugin name short and sweet and verify it’s not already in use by searching the plugin directory.
Once your plugin is approved, you’ll receive an acceptance email. Here’s an example we received for a new plugin we published, TweetThis Shortcode.
Set up your Subversion environment locally
On my local Mac, I have a Subversion directory in my root directory, with all of my plugins in subdirectories under it. This is much easier to manage than having files and plugins all over the place. Whenever I check out or commit the plugin, it’s always from this working directory.
If you work in multiple directories, you’ll find that each time you check out your plugin, all the assets, tags and trunk are copied locally. By maintaining the single directory, only changed files are updated locally.
How to check out your WordPress plugin
All right, deep breath! Open Terminal on OSX (or your Subversion client) and let’s get started.
1. Change directories locally to your Subversion directory.
2. Check out your plugin.
You will be prompted for the username and password that you used to register with WordPress. Your plugin and directories will be added locally if they already do not exist.
svn co http://svn.wp-plugins.org/tweetthis-shortcode
Note: Any folders or files you add manually within your trunk directory must be registered via Subversion.
Example of adding your icon.svg file to the assets directory:
svn add tweetthis-shortcode/assets/icon.svg
svn rm tweetthis-shortcode/assets/icon.svg
3. Add plugin files to new tag directory.
Once you’ve added all of your directories and files for your plugin within the trunk directory, you’ll then want to add them to a new tag directory with the new version as the folder name.
svn copy tweetthis-shortcode/trunk/* tweetthis-shortcode/tags/1.0.0
4. Check in the plugin.
svn ci -m "Version 1.0.0"
All files are transferred to the repository, and a successful message is provided if you’re plugin is checked in. Additionally, you’ll also receive an email notification that details the check-in. It even provides a color-coded detailed copy of your edits, adds and removals.
Once you see the plugin in the repository at the URL that was provided, be sure to add a review (disclosing that you’re the author) and that it works on the latest versions of the plugin and of WordPress. Be sure to keep track of the support forums and observe download stats so you can see how well the community appreciates your submission!
In a nutshell, here’s what you’re going to do to publish your new WordPress plugin:
- Navigate to your local Subversion directory.
- Check out your plugin.
- Make any edits to your plugin in your trunk directory. Be sure to update your readme.txt and plugin versions each time you’re updating the plugin.
- Register any file or folder additions or deletions with Subversion.
- Check in your plugin.