The WordPress.org Plugin Repository is the canonical location to find plugins for WordPress. There are many good reasons to add your plugin to this repository–the primary being that the built-in “Add New Plugin” search capabilities are linked directly to the WordPress.org repository. If your plugin is not in the WordPress.org repository, it will not be easily found by the majority of users, and with WordPress powering over 23% of the internet, you will be missing out on a large audience of potential users.
Below, I provide an overview of the WordPress.org Plugin Repository, how you can start leveraging it with your own plugins, and, as a result, dramatically increase the potential reach of your audience.
What to know before you submit
WordPress.org has some guidelines on what can and cannot be in a plugin to get it approved. As long as those guidelines are followed plugins are typically approved withing a few days.
- All plugins must have a license compatible with the GNU General Public License v2 (GPLv2) or a later version. If a plugin does not include a specific license, it will automatically fall under the parent project GPL license. If third-party libraries are included in the plugin they must also be compatible.
- The WordPress.org repository uses Subversion for adding and updating plugins.
- Plugins that require encoded elements to work, such as payment systems, are allowed but intentionally obfuscated code is not. All code must be readable by the plugin reviewer and community at large.
- Paid plugins are not allowed. All plugins in the repository are freely available to install and use all the features of. Up-selling to a pro version with additional features not in the WordPress.org hosted plugin is allowed.
- Plugins may not create any external connections, such as utilizing a service you provide or collecting data, without the express consent of the user.
- Plugins are not allowed to perform any illegal actions.
- Plugins may not post a link back to the plugin homepage or service without express user consent.
- Plugins may not use the term “WordPress” in their title.
These guidelines are subject to change by the WordPress.org Foundation and it is a good idea to periodically review the guidelines here.
Submission process
The WordPress.org plugin team has worked hard to make adding a plugin to the repository as painless as possible. Every plugin submitted is fully reviewed by the WordPress.org plugin review team, and to make their job easier there are a couple simple steps you need to take to ready your plugin:
Readme
In order for details about your plugin to show on your plugin page, a readme.txt file is required. This file contains (at a minimum) the basic information about your plugin, and may contain additional details such as a FAQ, screenshots, or even user-defined sections.
Proper formatting and a fully loaded example can be found here.
The most minimally allowed readme.txt file will look similar to the following:
=== Plugin Name ===
Contributors: (this should be a list of wordpress.org userid's)
Requires at least: 3.0.1
Tested up to: 3.4
Stable tag: 4.3
Tags: (comma seperated list)
Here is a short description of the plugin--this should be no more than 150 characters. No markup here.
== Description ==
This is the long description. No limit, and you can use markdown
Here is a breakdown of the readme.txt header elements:
- Contributors – WordPress.org usernames of all contributing members of the plugin
- Requires at least – Minimum WordPress version number for the plugin to work reliably
- Tested up to – Latest version of WordPress the plugin has been tested for and is known to reliably work with
- Stable tag – Latest version of the plugin the sites should be using
- Tags – Comma separated list of tags to help categorize the plugin for discovery
After creating the readme.txt file it should be passed through the readme.txt validator. If the readme.txt file is not valid, the plugin will be immediately rejected.
The readme.txt validator can be found here!
Have the completed plugin ready to go
Every line of your plugin will be reviewed by a human and run through an automated code tester. Do not worry! You will not be graded on your development skills. This process is to help capture plugins that do not meet the basic guideline requirements, have potential security vulnerabilities, or are not performant on a default WordPress installation.
The review process happens before space on the repository is created for your plugin, so you will need to have a complete plugin at this point. Provide the full URL to your plugin (that has been contained in a zip file).
Submit the plugin!
Congratulations! You have reached the point where you may submit your plugin to the WordPress.org Plugin Repository!
To view the new plugin submission form, you must be logged in to WordPress.org with the account that you desire to be the initial plugin admin. Additional users may be granted access to update the code after the plugin is accepted.
Before filling in the form, you will need three pieces of information:
- Plugin Name – Choose carefully here. Whatever name is entered in this box will become the plugin slug for the repository. It will be part of the URL to the plugin and cannot be changed. The initial name that creates the slug does not have to be the same name as is contained in the readme.txt file.
- Plugin Description – The description can be copied out of the readme.txt file verbatim or a new description written here. This box should have information the plugin reviewer will use when testing the plugin.
- Plugin URL – This is a link to the zip file containing the completed plugin, not to the plugin homepage. The zip file must include the completed readme.txt file.
After you have gathered those items you will be ready to fill in the submission form!
Using the repository
Great! Your plugin has been approved and you have access to the repository to upload you plugin and any updates in the future…now what do you do?
The WordPress.org repository was built on top of the Subversion version control system (VCS) and has a very specific structure for releasing and updating your plugin.
Repository layout
When you recieve access to add your plugin to the repository, you will be presented with the following layout:
assets/
branches/
tags/
trunk/
assets/
This contains assets for the plugin’s WordPress.org page such as screenshots, icon, and banner.
branches/
This folder can be useful for creating new branches of the plugin for upcoming features and hotfixes. In practice, however, this folder is not used, and development is done directly in trunk or on an external VCS such as Github that provides true, light-weight, inexpensive, branching.
tags/
Tags are released versions of the plugin, such as 1.0, 2.6, 3.0.5, etc. The repository does not care what versioning scheme is used in your plugin. As long as the readme.txt file contains the current release tag, users will always get the correct install or update. Using tags allows your plugin to maintain history among a varied set of version installs and allows patching specific versions if a vulnerability or bug is ever found and necessitates a fix.
trunk/
Trunk is generally the workspace for upcoming versions. Think of is akin to the master branch in git. Though some plugin authors do keep the official release in trunk this can be a bad practice as trunk is design to allow for future development versions and therefore inherently may have bugs, incomplete features, or stability issues in it.
Committing your plugin
Your plugin has been successfully submitted and approved. The Subversion repository on WordPress.org is setup and waiting for its first version of your plugin and a potential audience is keyed up as a user base. All you need to do is add the files and commit them back to the repository.
Check out your plugin repository
To kick things off, you will need to create a checkout of the WordPress.org repository for your plugin. This repository is where you will be adding the new files to upload.
There are several GUI tools, such as TortoiseSVN, that help ease your interactions with the repository however I am going to fall back to the simplest tool of all: the terminal. These commands will have an equivalent in whatever client you choose to use.
svn co http://plugins.svn.wordpress.org/YOUR-PLUGIN-SLUG
Add the plugin files
You should now have a folder in the directory called YOUR-PLUGIN-SLUG. Open this folder and you will see the folder structure mentioned above. Copy your plugin files to the trunk and appropriate tags folders.
Subversion does not know about any newly added files until you explicitly tell it about the files. The following command will tell it to find all new files in the trunk and tags folders.
svn add trunk/*
svn add tags/*
Commit the plugin files
This is the point you have been waiting for! After committing the plugin, the plugin will be live on the WordPress.org Plugin Repository for all to find.
Committing sends the files back to the repository server. After running the commit command, an editor will open and allow you to input text describing the purpose of the commit.
svn ci
Congratulations! You have now released your plugin to the world on the WordPress.org Plugin Repository!