How to Submit and Publish a Plugin to the WordPress Plugin Directory

If you are reading this, chances are you already have a WordPress plugin idea or maybe you have built one and now want to share it with the world. I did research before publishing my first plugin, and I can tell you this upfront: publishing a plugin to the WordPress Plugin Directory is not hard, but it is very detail oriented.

I am telling you this because I have gone through it myself multiple times. From planning and coding to fixing reviewer feedback and pushing updates via SVN, I am showing you exactly how to do this the right way, based on real experience.

This guide is written to help you publish a WordPress plugin, avoid common mistakes, and understand how WordPress expects things to be done.

Introduction to the WordPress Plugin Directory

The WordPress Plugin Directory is the official marketplace for free WordPress plugins. When you submit a plugin to WordPress.org, it becomes accessible to millions of WordPress users directly from their dashboards.

From my experience, publishing your plugin here gives you:

• Instant credibility and trust
• Massive organic exposure
• Community feedback and contributions
• Long-term growth opportunities

We know how strict the WordPress review team can be, but that strictness is exactly why users trust plugins from the directory.

Why the WordPress Plugin Directory Matters

Before we dive into the how, let’s talk about the why. The WordPress Plugin Directory isn’t just a download site. It’s the heart of the WordPress ecosystem. Having your plugin here means instant credibility, access to millions of users, and the benefit of automatic updates for your users.

It’s a mark of trust. Users know plugins in the directory meet basic security and quality standards, are 100% GPL-licensed, and have been vetted by the volunteer review team. For you, it’s free distribution and a direct line to your user base. Skipping it means asking users to manually install files, which is a huge barrier. Trust me, you want to be in the directory.

What You Need Before Publishing a WordPress Plugin

Before you submit a plugin to WordPress.org, make sure you have the basics covered.

1. A WordPress.org Account: This is different from your WordPress.com account. Go to wordpress.org and create one. This account will be your plugin’s home.
2. A Solid, Unique Plugin Idea: I did research before publishing my first plugin, and you should too. Does a similar plugin already exist? Can you do it better, safer, or with a unique feature? Don’t reinvent the wheel unless your wheel is significantly better.
3. Basic Proficiency in PHP, JavaScript, and WordPress Hooks: This guide assumes you can code a basic plugin. If you’re still learning, that’s okay but get comfortable with actions and filters first.
4. A Local Development Environment: Tools like Local WP, DevKinsta, or a MAMP/WAMP stack. You must test extensively on a local site, not a live server.
5. Familiarity with Subversion (SVN): This is the big one that trips people up. The Plugin Directory uses SVN for version control, not Git. Don’t panic; I’ll show you exactly how to handle it.

Planning Your Plugin (Research, Idea Validation, Naming, Scope)

Before I write a single line of code, I always start with research.

Plugin Idea Validation

• Search the WordPress Plugin Directory
• Identify gaps or missing features
• Avoid cloning existing plugins with no added value

I did research before publishing this plugin because reviewers will reject duplicates.

Plugin Name & Slug

• Must be unique
• No trademarks
• No keyword stuffing

I recommend choosing a simple, brand-safe name that reflects the plugin’s purpose.

Creating the Plugin (File Structure and Core Files)

Every WordPress plugin starts with a proper structure.

Basic Plugin Structure

your-unique-plugin-name/
├── your-unique-plugin-name.php (Main plugin file)
├── readme.txt (The all-important submission file)
├── includes/
│   ├── class-admin.php
│   └── class-public.php
├── admin/
│   ├── css/
│   └── js/
├── public/
│   ├── css/
│   └── js/
├── assets/
│   └── icon-128x128.png (Plugin icon)
│   └── icon-256x256.png
└── uninstall.php (Cleanup script)

Main Plugin File

Your main plugin file must include:

• Plugin name
• Description
• Version
• Author
• License

This is not optional. WordPress uses this header to identify your plugin. This is how WordPress identifies your plugin. Every single field matters. Here’s a template I’ve used successfully:

<?php
/**
 * Plugin Name:       Your Plugin Name
 * Plugin URI:        https://yourwebsite.com/plugin-name
 * Description:       A clear, one-sentence description of what your plugin does. This is your sales pitch.
 * Version:           1.0.0
 * Requires at least: 5.6
 * Requires PHP:      7.4
 * Author:            Your Name
 * Author URI:        https://yourwebsite.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       your-plugin-slug
 * Domain Path:       /languages
 */

Required Files for WordPress Plugin Submission

From my experience, missing files cause unnecessary delays.

Mandatory Files

• my-plugin.php
• readme.txt

Strongly Recommended

• license.txt
• uninstall.php
• /assets folder for banners and icons

I am telling you this because reviewers often request these files even if they are technically optional.

How to Write a Proper readme.txt File

Your readme.txt file is not just documentation it’s your plugin’s landing page.

Key Sections

• Description
• Installation
• FAQ
• Screenshots
• Changelog

We know users judge plugins quickly, so write clearly and honestly. Avoid exaggerated claims this improves trust and helps with approvals. I added an example here:

=== Plugin Name ===
Contributors: your_svn_username
Tags: tag1, tag2, tag3 (be relevant!)
Requires at least: 5.6
Tested up to: [Current WordPress version]
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

== Description ==
This is your full pitch. Start with a short paragraph. Then use == Subheading == for features, FAQs, and more. Use bullet points. Be thorough.

== Installation ==
1. Upload the plugin files to `/wp-content/plugins/your-plugin-slug`.
2. Activate the plugin through the 'Plugins' screen.
3. Go to Settings > Your Plugin to configure.

Be explicit. Assume the user is a beginner.

== Frequently Asked Questions ==
= A question? =
The answer goes here.

= Another question? =
Another answer.

== Screenshots ==
1. Description of screenshot-1.png
2. Description of screenshot-2.png
(Place .png files in a `/assets/` folder. Name them `screenshot-1.png`, etc.)

== Changelog ==
= 1.0.0 =
* Initial public release.

== Upgrade Notice ==
= 1.0.0 =
Initial public release.

Testing Your Plugin Before Submission

Never submit a plugin without testing it thoroughly.

What I Personally Test

• Latest WordPress version
• Older WordPress versions
• PHP 7.x and 8.x
• Debug mode enabled

I am showing you exactly how to avoid rejection here: use the Plugin Check tool. It catches most issues reviewers flag.

Plugin Submission Process

Alright, your plugin is coded, tested, and documented. Let’s submit it.

1. Login & Add Your Plugin: Go to wordpress.org/plugins/developers/add/ while logged into your WordPress.org account.
2. Enter the Plugin Slug: This is the unique identifier you chose (e.g., my-super-plugin). It will become wordpress.org/plugins/my-super-plugin/. Check availability.
3. Confirm Licensing: You must affirm your plugin is GPLv2+ compatible. All code in the directory must be GPL. This is non-negotiable and philosophical to WordPress.
4. The Waiting Game: You’ll get an email with your SVN repository URL: https://plugins.svn.wordpress.org/your-plugin-slug/. But your plugin is not live yet. It’s in a pre-queue for review.

WordPress Plugin Review Process and Rejection Reasons

The review queue can take anywhere from a few days to several weeks. Be patient. They are volunteers ensuring a safe ecosystem.

Common rejection reasons I’ve seen or faced:

• Code Quality: PHP/JS errors, use of deprecated functions, poor code structure.
• Security Issues: Lack of sanitization, escaping, nonce verification, or capability checks. This is the biggest one.
• Readme.txt Issues: Missing sections, incorrect formatting, or unclear descriptions.
• Naming/Trademark Issues: Using a brand name (like “YouTube Feed” without permission) or a too-generic name.
• Function Prefixing: Your functions, classes, and variables must be uniquely named to avoid conflicts. Use a prefix related to your plugin slug (e.g., msp_, MySuperPlugin_).
• Plugin Does Too Much/Too Little: Is it just a code snippet? Is it massive and should be multiple plugins?

If you get feedback, don’t argue. Thank the reviewer, fix the issues precisely, and resubmit. They are there to help.

Using SVN to Upload and Manage Your Plugin

You got the approval email! Now you need to populate your SVN repository. This is the most technical part. I use the command line, but GUI tools like SmartSVN or SlikSVN work too.

Initial Upload (The “Trunk”):

# 1. Checkout your empty SVN repo to a local folder
svn co https://plugins.svn.wordpress.org/your-plugin-slug/ local-plugin-folder

# 2. Navigate into the folder. You'll see trunk/, tags/, branches/.
cd local-plugin-folder

# 3. Copy ALL your plugin files into the `trunk/` directory.

# 4. Add your files to SVN control
svn add trunk/*

# 5. Commit with a message
svn ci -m "Adding initial plugin version 1.0.0"

You’ll be prompted for your WordPress.org username and application password (not your account password! Generate one in your WordPress.org profile).

Making Your First Version Live: The stable tag in your readme.txt points to the version. For 1.0.0, you must copy trunk to a new tags/1.0.0 directory.

bash

# From inside your local SVN folder (local-plugin-folder)
svn cp trunk tags/1.0.0
svn ci -m "Tagging version 1.0.0"

Once this commit is done, the directory will recognize the stable tag and list your plugin. It can take 15-30 minutes to propagate.

Managing Plugin Updates and Releases

Every update should include:

• Version bump
• Updated changelog
• Tagged release

From my experience, clean versioning builds user trust and reduces support issues.

WordPress Plugin Security Best Practices

Publishing isn’t the end. It’s a commitment.

• Security: Follow the WordPress Plugin Security Checklist. Always assume input is malicious. Use prepared statements for database queries ($wpdb->prepare()). Never store plaintext passwords.
• Performance: Use transients for expensive queries, but don’t over-cache. Hook into actions and filters efficiently. Load your admin assets only on your admin pages: if ( strpos( $hook, 'my-plugin-page' ) ) { ... }.

Read More: WordPress Security Audit: 15+ Best Audit Practice [Checklists]

Performance Optimization for Plugins

Performance matters more than you think.

Optimization Tips

• Load scripts only when needed
• Avoid unnecessary database queries
• Use WordPress APIs instead of custom code

We know slow plugins get bad reviews and bad reviews hurt rankings.

Promoting Your Plugin Ethically

Once your plugin is live:

• Write documentation
• Share it on your blog
• Engage with users in support forums

Avoid fake reviews or misleading claims. This is part of being a responsible plugin author.

Maintaining and Supporting Your Plugin

Publishing is just the beginning.

From my experience, successful plugins require:

• Regular updates
• Quick bug fixes
• Active support responses

This builds long-term authority and trust.

Common Mistakes to Avoid

• Submitting Too Early: That “it works on my machine” feeling is a trap. Test exhaustively.
• Ignoring the uninstall.php: Leaving database clutter is poor form.
• Forgetting to Prefix Everything: A function called add_custom_field() will conflict with another plugin. Use msp_add_custom_field().
• Not Planning for Translation: Hardcoding text strings is a rookie mistake. Use __() from day one.
• Neglecting the Support Forums: Silence speaks volumes. It says you’ve abandoned your users.

FAQs

Q: Is it really free?
A: Yes. 100%. Hosting, distribution, and updates are free. You cannot charge for listing.

Q: Can I sell a “Pro” version?
A: Absolutely. Many developers offer a free version in the directory with a “Pro” upgrade on their site. The free version must be truly useful, not just a demo.

Q: How long does review take?
A: It varies. Typically 2-10 business days. Be patient and use the time for extra testing.

Q: Can I use JavaScript frameworks like React or Vue?
A: Yes, but you must enqueue them properly and be mindful of conflicts. Often, using the WordPress REST API with vanilla JS or the bundled React (@wordpress/element) is safer.

Q: My plugin was rejected. What now?
A: Carefully read the reviewer’s notes. Fix every issue they mention. Ask for clarification politely if needed, then resubmit.

Conclusion

Publishing to the WordPress Plugin Directory is one of the best ways to contribute to the WordPress ecosystem. I did research before publishing my plugins, followed best practices, and learned from rejections and that’s exactly why I am confident sharing this guide with you.

If you take one thing away from this article, let it be this: follow the guidelines, write clean code, respect users, and think long-term.

If you do that, you won’t just publish a WordPress plugin you’ll build something people trust and use.

Good luck, and welcome to the WordPress developer community.