How to Upload Your Plugin to WordPress.org

WordPress is one of the best platforms for web development. All right, maybe it doesn’t use the newest technologies and its architecture isn’t perfect (let’s not forget that it’s a project that was born in 2003 and, therefore, there’s some legacy code and decisions), but the project is progressing at a good pace and is being modernized in each new iteration. An example of this modernization can be found in Gutenberg, the new WordPress editor implemented on React.js that promises to revolutionize the way we work with WordPress.

How come WordPress is so awesome? Because it has an extremely active community that you can learn from and contribute to and because it is the engine that drives 29% of the web. WordPress is a winning horse, so you can bet on it. That’s what we did a few years ago and, well, here we are, making out a living out of WordPress.

One of the questions I get the most from developers who want to get started on WordPress is: how can I create my first WordPress plugin and upload it to WordPress.org for anyone to use? We’ve already discussed the first part of the question in our blog, when I explained how to create a plugin in WordPress. In fact, we even saw a simple example of how to create a plugin with customizations without modifying your theme’s functions.php file. So let’s focus on the second part: how to upload your first plugin to WordPress.org.

Before Considering to Upload Your Plugin…

The first thing you need to upload a plugin to WordPress.org is the plugin itself. Duh! But even if you already have one, there’s a few tips you should take into account before uploading it:

1. What is an MVP and how to decide the basic functionality in WordPress. If you’re about to start a new project, it’s paramount to determine as soon as possible whether it’ll be successful or not―there’s no point in devoting a lot of resources to something that’s likely to fail. In this post I explain what the minimum viable product is and how you can use it to get started with your new plugin.
2. WordPress Coding Standards. WordPress is a huge project that relies on a community of volunteers. In other words, there are a lot of people who contribute to the project. In this post we see what style guides you should follow when programming code for this platform.
3. When WordPress freedom kills your business. When programming plugins for WordPress, you should always keep in mind that you won’t be alone and that your plugin will probably end up running alongside many others. Be organized and make sure your plugin doesn’t perform unnecessary tasks or adds unnecessary scripts and styles where it’s not supposed to.
4. Top 6 Secrets to Successful Internationalization. If you are going to create a plugin for WordPress, you should keep in mind that the target audience is people from all over the world and therefore your plugin should be ready to be internationalized. This post explains how to do this.

I hope these resources will help you create a better plugin ? So, let’s move to what you’re really interested in: how to upload the plugin to WordPress.org.

How to Upload a Plugin for the First Time

Publishing your plugin in WordPress.org for the first time is super easy: just send a zip file with your plugin using this form. Once sent, your plugin will go through a manual revision that will decide its faith. Reviewers check some basic stuff, like “does the plugin follow WordPress coding standards?” or “is all input sanitized?” The plugin review process usually takes a few days, so make sure to follow the tips I mentioned earlier.

Some other things you should double-check when sending a plugin include:

• Make sure the plugin has a valid README.txt file. This file is very important, because its content is the one that appears in the WordPress plugin directory. In other words, the different sections of the file cannot be anything you want, but have to follow a “standard”. For example, our Nelio Content plugin has this README.txt, which results in the following page. You can use this tool to validate the format of your README.txt.
• Make sure all classes and functions have a prefix that makes them unique. For example, do not create a class called Post_Ajax_API for the callbacks of your plugin‘s AJAX calls or a function called has_subscription to check if the user is subscribed to your service or not. Instead, add a prefix to those names: Nelio_Content_Post_Ajax_API and nelio_content_has_subscription. This way, we avoid conflicts with other plugins that might want to use a similar class or function. Alternatively, you could use PHP namespaces.
• Make sure that all text strings printed on screen are properly escaped with the esc_html and esc_attr functions. In the same way, and as I said before, make sure to apply sanitize functions to any data given by the user. If you don’t, you risk creating security holes in your plugin.
• Check that all the JavaScript and CSS resources you add to your plugin are in the plugin itself (and are not pulled from third-party servers).
• Finally, be careful with the name you have given to your plugin. As indicated in the documentation, you can’t call your plugin using a trademark you don’t own (and yes, this includes the word “WordPress“). If you include the name of a registered trademark to imply that your plugin is an extension of what they offer, you must do so in such a way that it’s clear it’s an extension, and that you have nothing to do with the trademark. In short, put a name that does not lead to confusion to the end use.

Comply with these rules and I’m quite sure your plugin will be accepted right away ?.

How to Use SVN to Upload Plugin Updates

Once your plugin has been accepted, you’ll receive an email in your mailbox similar to this one:

Your plugin hosting request has been approved.

Within one hour, you will have access to your SVN repository at
https://plugins.svn.wordpress.org/nelio-content/
with your WordPress.org username and password (the same one you use on the forums).

(…)

Enjoy!

In other words, you’ll soon have an SVN repository where you can manage the source code of your plugin and the different versions your users will be able to download. If you’ve never used SVN and don’t know where to start, don’t worry, it’s similar to Git and quite easy to use. Today I’m going to walk you through the most basic concepts you need to know.

Nelio Content

I’m so happy about Nelio Content that I will sound like a payed advocate… but here’s why you’ll love it: it works as promised, its auto-scheduling feature is top-notch, Nelio’s value for money is unmatched, and the support team feels like your own.

Panozk

WordPress.org

View Plans

Set Up Your SVN Repository Locally

When you’ve finally been given access to the SVN repository, the first thing you’ll have to do is “clone” it on your local computer. Using SVN terminology, what you are going to do is checkout the project. To do this, execute the following command:

svn checkout https://plugins.svn.wordpress.org/plugin-name/

This will create the plugin-name folder with the cloned project. There’s a shorter version of this command, where you replace the keyword checkout:

svn co https://plugins.svn.wordpress.org/plugin-name/

If you take a look inside this folder, you’ll see that it has a few directories you probably don’t know about. Let’s see what they are and what they’re used for:

1. trunk. This is the directory where development takes place. The code here shouldn’t be used in production environments, but it’s probably quite stable.
2. assets. This directory includes the different files that the WordPress.org uses to list your plugin. That is, the icon of your plugin, the header image, and the screenshots. In the WordPress documentation they explain you exactly what sizes the banners should have, how many different icons (and of what sizes) you should generate, and how to name the screenshots.
3. tags. In this folder we will add the different stable versions that we are publishing. We’ll talk about this in detail later on.
4. branches. This last directory is where you can create the different development branches of your plugin. If you’re interested in the topic, you can read the SVN documentation on how to create branches and how to merge code.

How to Update Your Local Copy with Server’s Information

If your local copy of the repository is behind what’s on the server, all you have to do is update it. In Git, this is done with the pull command. In SVN, you do this with the checkout command we saw before. Assuming you’re in the project directory, just run this:

svn co

and you’re done!

How to Commit Your Changes to the Server

In Git there are two commands to save the changes you have made in a project: commit and push. The former commits the changes locally and the latter uploads them to the server. In SVN this is much simpler: after editing your code, just commit it and it’ll be automatically uploaded to your server:

svn commit

or using a shorter version:

svn ci

How to Create a New Stable Version of Your Plugin

Last, but not least, we have to talk about creating new versions of your plugin. For example, suppose the code you have right now in trunk should become version 2.1.0 of the plugin. All you have to do is create a folder with the same name in tags and copy the content from trunk as follows:

svn copy trunk tags/2.1.0

or its shorter version:

svn cp trunk tags/2.1.0

And that’s it! We’ve already create a new tag that, once committed, our users can download. However, how do we tell WordPress that version 2.1.0 is the stable one?

If you take a closer look at README.txtin trunk, yo’ll see that there is an attribute in the header called Stable tag. Well, all you have to do is modify its value so that it “points” to the version you want it to be stable. In our example, this is how it’s supposed to look like:

Stable tag: 2.1.0

and we can now commit our code and make it stable!

But I’d Rather Use Git to Manage my Code…

So do we! The source code of our plugins is managed in a Git repository in Bitbucket. When we want to release a new version, we copy all the changes from the Git directory to the trunk directory of the SVN project and create the new stable tag as I just explained. In fact, this step is so common that we even created a script to automate the process ?

So Now What?

Now you have all the tools and knowledge you need! Just upload the plugin and get ready to help your users. Step by step, you’ll increase your customer base and your plugin will be a success. Just tell us how it’s working in the comments section below ?

Featured Image by Ash Edmonds on Unsplash.