Recently I submitted WP Coupons and Deals plugin to the plugin repository. It’s a plugin to show coupons and deals on your posts, pages with a simple shortcode.
This is the second plugin I have submitted.
Since it was my second one, things were pretty easier. But the first time, there were lots of confusions.
I got all confused with terms like Sub version, tags, trunk etc.
Hence, I decided to do a tutorial on submitting your first WordPress plugin.
I hope this tutorial will make it at least a little bit easier for you to go through the process.
Plugin Best Practices and Guidelines
Before submitting your plugin, there are few things you should definitely know. If you don’t follow the rules, there’s a chance that your plugin won’t be approved in the plugin repository. Check out the following:
Whether you’re done building your plugin or not, you need to know these best practices and guidelines. If you haven’t started yet, that’s good, make sure you follow these when you are building your plugin.
If you are done building your plugin, that’s great. Now make sure your plugin is in compliance with the guidelines. This should save you lots of time in the future.
In general, Plugin Developer Handbook has in depth tutorials on different aspects of plugin development. I myself am new at this. So, I read and learned a lot from the handbook. If you are like me, new at this, you should read the handbook too.
Also, if you do a little search on Google you can find hundreds of great articles on plugin development. I try to read as much as possible. I always learn at least one new thing about plugin development from these articles.
You must have a readme.txt file in your plugin. If you don’t have one in your plugin zip file, your zip file will not be accepted.
So what is this readme.txt and why is this so important?
readme.txt file contains all sorts of information about your plugin. When you visit any plugin page in plugin repository, you can see plugin description, installation, other things like that.
Well, the repository parses and draws these information from the readme.txt file. That’s why this is required.
Here’s a tutorial on readme.txt from the plugin developer handbook.
You can check out the readme.txt file from my plugin.
If you want a good looking and helpful plugin page for the users, you should try to utilize this file as good as possible.
Here’s another in depth tutorial on the readme.txt file.
Before submitting your plugin zip file, don’t forget to validate your readme.txt file with Readme Validator.
Uploading The Zip File
Now that you have your plugin and the readme.txt file ready, it’s time to make a zip with all this and submit it.
Go to Add your Plugin page.
Select the zip file from your computer and click on Upload.
If there’s nothing wrong with your zip file and it has uploaded correctly you’ll see upload confirmation message like the following.
As the message says, you’ll get an email from WordPress verifying that they have received the plugin.
Now it’s time for you to wait for the approval of the plugin. Approval can take anywhere from 6 hours to 6 days, be patient!
If your plugin is approved, you’ll get an email from WordPress with a link to your SVN(Subversion) repository. This is where all your plugin files and other assets are stored.
You’ll know in a while what SVN and these other assets are.
WordPress uses Subversion version control system to manage the plugin repository. Subversion allows you to track all changes you have made to your code. This is very useful you want to check older version of your codes.
Before using the repository we need to know the structure. What it contains and how they work.
So, your SVN repository comes with four folders.
Assets folder stores the plugin screenshots, header banner, icons.
Plugin assets have to named correctly, like: screenshot-1.png, banner-772×250.png, icon-128×128.png etc.
The details from Screenshot section in readme.txt file will be used as the caption for the screenshots in your plugin page.
That means, if you have ‘Plugin Settings’ as the number 1 on Screenshot section in your readme.txt file then screenshot-1.png will be shown with that title.
This is used to create branches of the plugin for upcoming releases. But most of the times it’s not used.
Most of the developments is either done or trunk or any other external version control systems.
Releases go in tags folder. Which means it will have sub folders like 1.0, 1.1 – however you version your plugin.
Make sure your readme.txt file contains correct release tag.
I have seen many plugins don’t use this folder. Instead they use the trunk folder for plugin files, but I think using this is a better way to manage and keep track of different version of the plugin.
When I released my plugin, I released it as 1.0 and I had 1.0 subfolder in tags folder where all my plugin files are stored.
Also when you’re releasing a new version make sure your readme.txt stable tag and version tag in main plugin files are the same.
All development work belongs in trunk.
Which means it is generally the workspace for upcoming versions.
But as I said earlier you can keep your main release in the trunk but that is not a good practice.
Using SVN Repository To Upload The Plugin
Now, it’s time to use the SVN repository to upload your awesome plugin.
We can access and use SVN in few ways. There are few tools.
- Tortoise SVN
- Provides Windows users with a GUI for subversion
- Provides Mac users with a GUI for subversion
You can also do access and use it from the Command Line Interface. Since, I’m on a Windows computer, I will show you how to do it with Tortoise SVN.
Download Tortoise SVN and install it.
Now, pick a directory where you want SVN track your plugin files and changes. I have a folder named WordPress Project. That is where I store my plugins to use with SVN.
I have created a new folder ‘wp-coupon-deals’. This is the one I will be using to upload my plugin.
Checking out SVN Repository
Once you have the directory you want to use, right click on that. You can see the ‘SVN Checkout’ Option.
Click on that.
A new window appears. Here, you can set the URL of repository, this is the URL you have gotten in your plugin approval email. This is your plugin’s SVN repository.
Put it correctly. Checkout directory is the folder on your computer SVN uses to track your plugin.
Because you started the checkout process by right clicking that folder in the first place, this should be set correctly.
Leave the other settings as shown and click OK.
Your SVN repository will now be checked out to your computer. If you have checked out successfully, this is how your folder should look now.
Uploading the Files
You have checked out the repository successfully. Now it’s time to upload the files. Make sure you have the correct readme.txt file.
Put all your plugin files along with the readme.txt file in the trunk folder. Put all assets(banners, icons) in the assets folder. Make sure you have the names correctly.
Now right click on the checked out directory, where all folders are stored and click on ‘SVN Commit’. A new window will appear.
Put a commit message, check all the files and click on OK. Now your files will be uploaded to the SVN repository.
Creating a Tag
Now, since we are ready for the public to use our plugin now, we need to tag a version to set aside and leave alone.
Let’s see how we can create a tag.
Right click on the trunk folder and click on ‘SVN Branch/tag’. A new window appears.
In the ‘To Path’ field, we are putting where we want our tag to be created. Since I want to have version 1.0 of my plugin, I am setting it to 1.0 folder under tags folder.
Click on OK. SVN will now create a copy of what’s found in trunk folder on SVN server. It’s creating that copy in a subdirectory called 1.0 under the tags subdirectory.
That newly tagged version was created on the SVN server. We need to pull those changes down to our computer.
Right click on the project folder and click on ‘SVN Update’.
This will pull any changes from the SVN server that are not reflected on our local copy of the project folder.
Finishing It Up
We’re almost done.
Make sure plugin version in the main plugin file and ‘stable tag’ in the readme.txt file is 1.0.
Now click on the main plugin project folder and click on ‘SVN Commit’ and commit your changes with a message.
And you’re done! Within few minutes your plugin will be live for the public to use it.
Over To You
Are you still confused about submitting your first WordPress plugin? Don’t hesitate to ask any questions through the comments.
Have you already published your WordPress plugin? Share it with us.
I hope this tutorial helped you understand the process. If you have any further queries, ask them through comments.