How to publish your first WordPress plugin

How to publish your first WordPress plugin

Trevan Hetzel's Layout avatar

Releasing a WordPress plugin always appeared to me as a daunting task that only super talented PHP developers were capable of. Most of my WordPress experience lies in custom theme development, so venturing off into plugin development seemed imposturous and frightening. But I bring good news! I’ve recently released two plugins that are available on the WordPress plugin directory and, guess what? It wasn’t as scary as you may believe! It was actually a fairly pleasant experience publishing it to once the development was done.

This article won’t necessarily go into the details of creating plugins, rather it will cover the steps needed to actually get your plugin launched and available on the directory and every WordPress site in the world. For reference though, I used the WordPress Plugin Boilerplate as a starting point for my plugins and open sourced it all on GitHub (definitely recommended).

Note: This article is a snippet of the free ebook, Programming, publishing, and promoting your WordPress plugin. Get the full story by downloading the guide today!


The first thing you need to have in order for WordPress to accept your plugin is a Readme.txt file. It contains all of the information related to your plugin and is what WordPress uses to generate pages for your plugin on the directory (like the Description, Installation, and Screenshots tabs).

The format for the Readme looks like this:

=== Plugin Name ===

Contributors: yourname

Donate link:

Tags: business, directory

Requires at least: 4.3

Tested up to: 4.3

Stable tag: 4.3

License: GPLv2 or later

License URI:
A simple description
== Description ==
A longer description with a
- list

- of

- features
== Installation ==
This section describes how to install the plugin and get it working.
1. Upload [`plugin-name`]( to the `/wp-content/plugins/` directory

2. Activate the plugin through the 'Plugins' menu in WordPress
== Frequently Asked Questions ==
= Is this a cool plugin? =
== Screenshots ==
1. Desktop view
2. Mobile view
== Changelog ==
= v1.0.0 =

* Initial release

A full example can be found here. A handy validator is also available to check if your Readme is up to par.

Changelog and versioning

It’s important to keep the version number of your plugin up to date so, if nothing else, users can be notified when there are updates to it. Updating the changelog is as simple as adding a new entry to the changelog section in the Readme. There are a few different outlooks on versioning and what should constitute as a major or minor release; I like to consult the Semantic Versioning 2.0.0 site for reference on that.

As an example, let’s say you ship your plugin at version 1.0.0. Then the next day you fix a little bug or add a little functionality that you forgot when you first published the plugin. Before you’d deploy the plugin to the WordPress directory (more on how to do that later), you’d update the changelog section in the Readme to something like this:

== Changelog ==
= v1.0.1 =

* Fix a thing that allows users to do a thing
= v1.0.0 =

* Initial release

Then (this is important), you need to update the version number in the plugin bootstrap file. You should be familiar with the bootstrap file if you’re writing a plugin, but for reference it’s the file that gives WordPress information about the entire plugin via the comment block at the top.

publish-wordpress-plugin-version The comment block of the plugin bootstrap file.

Submit to

With a Readme in place and extensive testing done, you’re ready to submit the plugin to WordPress! This is the easiest part of the whole process. Simply go to, log in with your WordPress account (or create one), and fill out the short form.

Be careful that you don’t use the name “WordPress” in the name of the plugin. They will reject the plugin if you do so. They will also reject the plugin if you include the name of a trademarked product or if your plugin starts with the name of another plugin. I found that out the hard way with a plugin I tried to submit that extends Ninja Forms and got this response in an email:

We’re no longer accepting plugins that include a trademarked product name or term as the name or slug of a plugin. Nor are we accepting plugins that include the name of another plugin at the beginning of the name/slug.

Make sure you take the time to write a lovely description and then drop the link to your plugin in a ZIP file in the last field. Using GitHub for plugin development makes it really easy to have a publicly available ZIP.

publish-wordpress-plugin-github Copy the URL of the “Download ZIP” plugin from your GitHub repo.

Once you submit the plugin, sit back and wait! Both of my plugins were accepted within about two days. You’ll get an email with information on the new SVN repository if it’s accepted. Which brings us to the next step – deploying!

Deploy with SVN

Once the plugin is accepted, it’s still not live yet. You have to actually upload the files to the SVN repository WordPress provides you with. I had never used SVN before this, but their article walks you through getting logged in through the terminal pretty quickly. Basically, you create a folder on your computer, check out the SVN repo, copy your plugin files into the newly created /trunk folder, and push it back up.

You could do this through the terminal each time you need to deploy a change, or you could use a handy tool called Ship. I’ve used Ship for every deployment I’ve done and it works like a charm, automatically deploying to the SVN repo whenever you tag a new release in GitHub. If you’re using GitHub (which, again, you should be) I highly recommend this free service.

For the best deployment process and maintainability, it’s important to use releases or tags whenever you deploy. Just as you update the version number in your plugin file and changelog, you should also be issuing new releases in GitHub. It’s actually required to do this in order to use Ship.

Finally, once you get signed up with Ship and select your repo to hook up to it, you can deploy your first release (make sure the name matches the release name in GitHub). After that, as long as you fill in the form under the WordPress Details heading, Ship will just deploy whenever a new release is issued in GitHub.

publish-wordpress-plugin-ship Ship’s repository settings UI.

Screenshots and banner images

Displaying screenshots of your plugin is super important to help people visually see what it looks like and to give them an idea of how it works. These screenshots will show up on the plugin directory page (here’s my calendar plugin’s screenshot page, for example) and when a user adds a plugin on their site through the Plugins page.

Banner images aren’t as important as screenshots, but they make your plugin look a little more impressionable. The banner image is the big image that’s shown at the top of the plugin directory page.

publish-wordpress-plugin-banner The dark blue gradient here is the banner.

To get these images to show, you have to place them in the /assets directory of your SVN repo. Unfortunately, you can’t use Ship for this as it only deploys the /trunk folder, so you’ll have to consult this article again to get logged in to your SVN repo.

To keep things simple, stick to naming your screenshots screenshot-#.png (where `#` is the number). Doing it this way allows you to easily reference the images in the Readme to give them a description.

== Screenshots ==
1. Desktop view
2. Mobile view

For example, the description “Desktop view” from the Screenshot section in the Readme will match up to screenshot-1.png in the /assets folder.
For the banner, you actually need two versions of the same image – one for normal screens and one for retina screens. The names of the banner images should be banner-1544x500.png and banner-772x250.png.

The end

That’s it! If you followed along, I hope your plugin was accepted and you’re ready to start getting the word out about your awesome new plugin. Just remember to always update the Readme, changelog, and issue releases whenever you update the plugin.

Now that your plugin is live, it’s time to tell people about it! Follow this simple guide for WordPress developers to market your product and get your plugin’s name out there.

Comments ( 0 )

Join the discussion