How to Submit Your Plugin to The WordPress Plugin Repository – A Complete Guide

Today we’ll discuss how to upload/add/submit plugin to the WordPress plugin repository/directory located in wordpress.org

This process considerably not a simple task, as we have to pass several steps that for some people would be confusing for the first time, in addition, there are some important things that need some attention.

Table of contents:

I. Consider Some Important Things Before We Submit a Plugin to The WordPress Repository

There are several important things to note before uploading a plugin to wordpress.org plugin directory. This is important to speed up the process of moderation that would be conducted by the WordPress team later.

  1. Ensure that we already give all of our code a unique prefix, for example,  aph_get_post(), in the case I use aph_ as a prefix
  2. Avoid using the shorthand <?= . Because not all servers support this shorthand by default, in addition, the use of this shorthand will also make us get a warning from the WordPresss team.
  3. Make sure our file names and codes meet the WordPresss standards, for example: if a file name consists more than one word, separate it using dash (aph-prism-highlighter.php), furthermore, the folder structure should look like the following:

    Folder Structure

    This is not the must, we are free to choose a plugin file name and free to use other standards (such as PSR), but in order to easy to understand by other WordPress developer, it recommended that our codes meet the WordPress standards.

    Note that once we define the plugin file name, in mine, aph-prism-highlighter.php and submit it to wordpress.org, we will not be able to change it anymore, so be careful with it

    For more guidance, visit WordPress Plugin Developer Handbook

Prepare the readme.txt file and plugin-name.php file

Pay attention to the structure of readme.txt file and plugin’s file name, in this example aph-prism-highlighter.php

This is important because WordPress will use and publish the information in those files both in the WordPress plugin directory or in the Admin Plugins Page.

readme.txt file

We can find the structure of the readme.txt file on the official WordPress sites: completed readme.txt, or you can see an example of readme.txt file that I use.

WordPress will display the content of readme.txt file on wordpress.org plugin page, for example:

Plugin Details

Plugin details in readme.txt file

The result appears on https://wordpress.org/plugins/search.php?q=APH+PRISM or in The WordPress Admin Page, open Plugins » Add New menu and then search APH PRISM

Plugin Details in WordPress.org Page

Plugin Description

Plugin Descriptions in readme.txt File

The result: https://wordpress.org/plugins/aph-prism-highlighter/

Plugin Descriptions in The WordPress Plugin Page

Screenshots

It needs quite long explanation, so We’ll discuss it later

plugin-name.php File

Comment block in this file, in mine, aph-prism-highlighter.php will be displayed in the Admin Plugins Page (Plugins » Installed Plugins) and our plugin page in the wordpress.org

aph-prism-highlighter.php File

Plugin Descriptions in The Plugin File Name

Plugins Admin page (Plugins » Installed Plugins)

Plugin Descriptions in The Plugins Admin Page

Plugin page on wordpress.org: https://wordpress.org/plugins/aph-prism-highlighter/

Plugin Descriptions in The WordPress.org

II. Submit Plugin to WordPress.org for Validation

After the preparation is completed, then we register the plugin to wordpress.org through the page: Requests – WordPress Plugins, fill in all of the fields and then click Send Post

An example as shown below:

Submit a Plugin to WordPress.org

Explanation:

  1. Plugin Name (required). Fill in the name of the plugin you want to register, for example, APH Prism Highlighter. Later, this name will be used as our plugin directory name, in mine https://wordpress.org/plugins/aph-prism-highlighter/ and https://plugins.svn.wordpress.org/aph-prism-highlighter/
  2. Plugin Description (required). Fill in the description of the plugin, we can take it from the readme.txt file in the == description == section
  3. Plugin URL. Compress our plugin files into a zip file and upload it to a certain place so that the WordPress team can download it for review, in this example, I uploaded it to http://webdevzoom.com/aph-prism-highlighter.zip

Once finished, click Send Post.

The WordPress team will review our plugin, if there is a problem then they will notify us via email, and if the approve our plugin, then they will also notify us via email too.

THEREFORE, stay tuned to our email.

The review process can take a while between 1 to 3 days, an average is 2 days, so just wait.

III. Install a Subversion (SVN) Client

If our plugin was approved, then it can not immediately appear on the wordpres.org directory. A .zip file that we have uploaded was only used for the review purpose only.

To be able to appear in the wordpress.org plugin repository, we need to upload the plugin files to a specific directory in wordpress.org

The URL address of the directory are notified via email once the plugin is approved, usually corresponds to the name of our plugins, in this example, I got the svn address: https://plugins.svn.wordpress.org/aph-prism-highlighter/

Apache Subversion

WordPress use version control to manage all of their plugins. It uses Apache’s subversion as the version control system.

To be able to use this subversion, we need to install Apache Subversion client. There are many subversion clients out there, the most popular is TortoiseSVN, you can download it here, then install it by simply following the wizard.

IV. Make Sure For Writing a Meaningful Message When Running SVN Commit

After successfully installing TortoiseSVN, in the future, we will always use this software to synchronize files between our local directory and our SVN directories in the wordpress.org.

One is sync/update the SVN directory to match with the local directory, while the commands to use is SVN Commit.

When we run this command, then we have to leave a note/message regarding the changes that occur, such as: “adding plugin files for the first time to the trunk directory”, “add screenshots”, etc.

Well, keep in mind that all of these messages will be recorded and displayed in our user profile pages at wordpress.org. This means everyone can read it. Therefore, always create a meaningful message so others can understand what we do

Commit Messages in The Profile PageCommit Messages in The Profile Page

V. Upload Plugin Files to SVN Directory Using TortoiseSVN

Next, we need to create a directory on the local computer. we will ALWAYS use this directory to synchronize files with our svn directory at wordpress.org

1 Create a plugin directory

In order to easy to organize, create a specific folder that contains our plugin files, in mine, it is in E:\WordPress\Plugin Projects\aph-prism-highlighter

Why don’t we just use our plugin directory in the local WordPress installation? (wp-content\plugins\aph-prism-highlighter) ?

We did not do this because when using SVN, many new directories will be created, so it will mess or even break our plugins, so we need to create a new directory.

2 Sync our local directory to SVN directory

Next, synchronize the directory with our plugin directory in wordpress.org:

  1. Right-click on the directory and select SVN Checkout. This will download all files and folders from the SVN Server to local directory

    Copy SVN Directory to Local Directory Using SVN Checkout

    Whenever we want to copy all the contents of our svn directory on wordpress.org to our local directory, use SVN Checkout
  2. Next, in the Checkout window, on the”URL of Repository” field, enter URL that we have received from WordPress team via email, in mine, it is https://plugins.svn.wordpress.org/aph-prism-highlighter/

    Fill URL of Repository Field in CVN Checkout Window

    Click OK to continue.

  3. Once successful, we’ll see new directories which exactly same as in the SVN directory

    On SVN Server

    SVN Directories on WordPress.org

    On Local Directory

    SVN on Local Directory

  4. After this, any changes to our local directory will be recorded by TortoiseSVN. This making us easier to manage files: adding, editing, or deleting files/directories as well as reverting it back to the original state.

3 Copy the plugin files to the trunk directory and run SVN Commit

Finally, we’ll display our plugin on wordpress.org plugin directory so that other user can download and use it.

To do so, we need to make a tag. This tag is commonly used in the version control. This is used to mark the release version of a program such as (1.0, 2.2, 4.3, etc …)

Because this is the first time, so we’ll create a tag of 1.0, which means our plugin version is 1.0.

The steps are:

  1. Right-click on the trunk directory and select TortoiseSVN » Branch/Tag …
  2. In the “To Path” field, add tags/1.0. In mine, that field value become aph-prism-highlighter/tags/1.0, notice that the destination URL is also changed.

    Add - Upload - Submit Plugin to The WordPress Directory - Version 1.0

    In this step, we’ll send all files in the trunk directory to the tags/1.0 directory both on the SVN Server, which means our plugin will start to appear in the wordpress.org plugin repository.

  3. As stated before, don’t forget to write comments/message of the changes.
    IMPORTANT !!! to note that when we’ve run this process, then we can no longer (not recommended) to make any changes to the files in the tags/1.0 directory.

    If we want to make some changes, then we need to create a new version, e.g. 1.0.1, except in non-significant part such as changing the readme.txt file.

    If we ignore this, then the possibility is user will download the same version, but with different scripts, so we can not be sure that all users use the latest version of our plugin

    So,before publishing a new version, we need to ensure that our plugin ready to be published.

  4. Next, click OK to continue, wait a while until the confirmation message appears, tell that the copy process was successful.

    Usually, there is a warning that we are still in the working copy of the previous path (trunk), and we asked to move it to the tags/1.0. We do not need it, so we can simply ignore the warning.

Done..

5. Update tags on local directory

In the previous process, we just copy files from trunk directory located on the SVN Server to the tags/1.0 directory which also located on the SVN server.

So, in order to match to the tag directory on the SVN Server, we need to update our local tags directory. To do so, right-click on the tags directory, and select SVN Update.

Once successful, the tags directory will contain a new directory named 1.0, the content is the same as the trunk directory.

VI. How to Upload Screenshot to WordPress.org Plugin Repository

In the readme.txt file there is a section called == Screenshots ==, this section will show us a screenshot of our plugin at wordpress.org, for example:

Screenshot Description in readme.txt File

The result as appeared on https://wordpress.org/plugins/aph-prism-highlighter/screenshots/

Screenshot Description on WordPress.org

The above example is straightforward, the screenshot file name uses a pattern screenshot-[number].[file-type], for example screenshot-1.png.

The description of these screenshots is written according to the number of the screenshots.

Uploading the plugin screenshot

There are two methods to upload screenshots:

  • Combining the screenshot files with the plugin files. The file structure will look likes the following:

    Screenshot Files in The Plugin Directory

    Using this method, we have to include the screenshot files to each version of our plugin. This is not efficient.

  • The second method is uploading the files to the assets directory,  by separating the locations, the plugin files become more clear and efficient.
    [Aph_info]Always use this method, because it is recommended by wordpress[/ aph_info]

To run the above methods, simply copy-paste the screenshot files to the desired directory (plugin/assets)

For example, we place the files to the assets directory:

  1. Copy files to the assets directory. in mine, E:\Wordpress\Plugin Projects\aph-prism-highlighter\assets
  2. Back to aph-prism-highlighter directory, right-click on the assets directory, then select SVN Commit…

    How to Upload Screenshots to The WordPress.org Plugin Page

  3. Give an appropriate message and click Ok Button to continue the process

Done…

VII. Publish A New Version of The Plugin

Further, we want to add some features to our plugin we have published earlier, and we gave it a new version e.g. version 1.1, to make users notified the new version, we need to update our tags

  1. Copy the new version of the plugin files to the trunk directory (overwrite the old ones)

    Change the “Stable tag” in the readme.txt file to 1.1. This version differences will bring up a notification to the user that there is a new version of the plugin.

    IMPORTANT Don’t forget to change the plugin version in the plugin file (aph-prism-highlighter.php) to 1.1, otherwise, WordPress will still display version 1.0 in our plugin page in the wordpress.org. In Addition, even though the user has updated the plugin, the version will still appear 1.0

  2. Upload/Synchronize files in the local trunk directory to the trunk directory in the SVN server by right-clicking the local trunk directory and select “SVN Commit”.
  3. Create a new tag, right click on the trunk directory and select TortoiseSVN » Branch/Tags…

    Add the “To Path” field with tags/1.1. In mine, the “To Path” value become aph-prism-highlighter/tags/1.1

  4. Click OK to run the process
    After the plugin update, users will not immediately receive a notification of new versions. This new version will be checked every 7 hours. So, don’t be surprised if right after updating the version, the notification of the new version does not show up.[/ Aph_info]
  5. Update our local tags directory by right-clicking on the tags directory and select SVN Update.

That’s all.

Related Post

Leave a comment

Like Us

Social