Publishing to the plugin directory: a step-by-step guide

Getting your plugin in front of millions

Publishing to the WordPress plugin directory is one of the most effective ways to reach a massive audience and establish credibility in the community. Once your plugin lands in the directory, it becomes discoverable to millions of WordPress site owners searching for solutions to their problems. This guide walks you through the practical steps we've learned from releasing multiple plugins over the years, covering everything from pre-submission preparation to ongoing maintenance.

Follow the plugin guidelines

Before submitting anything, spend time reading the WordPress Plugin Security and Design Best Practices documentation. The directory has specific requirements that go beyond just functionality. Your plugin must not include anything that phones home without permission, collect data without consent, or bundle third-party libraries without clear attribution.

Security is non-negotiable. You need to implement nonces for all forms, escape all output, and sanitize all input. Here's a practical example of a properly secured form:

<?php
// In your admin page or settings
wp_nonce_field( 'my_plugin_save_settings', 'my_plugin_nonce' );

// In your form handler
if ( ! isset( $_POST['my_plugin_nonce'] ) || 
     ! wp_verify_nonce( $_POST['my_plugin_nonce'], 'my_plugin_save_settings' ) ) {
    wp_die( 'Security check failed' );
}

$user_input = isset( $_POST['user_setting'] ) ? sanitize_text_field( $_POST['user_setting'] ) : '';
echo esc_html( $user_input );
?>

Also check the specific guidelines around admin notices, database queries, and performance. The directory reviewers will test your plugin on a fresh WordPress install and look for common issues like excessive database queries on every page load or adding unnecessary admin pages without clear value.

One thing we've learned: your plugin should have a single, clear purpose. Trying to be everything to everyone makes your plugin larger, harder to maintain, and more likely to conflict with other plugins. If you've built something with multiple distinct features, consider breaking it into separate plugins that work together.

Write a clear readme.txt

The readme.txt file is your plugin's front door. It's parsed by the directory to generate your plugin's landing page, so getting it right matters. This file uses a specific format that's different from standard Markdown.

Here's what a solid structure looks like:

=== My Awesome Plugin ===
Contributors: your_wordpress_username
Tags: forms, contact, email
Requires at least: 5.8
Tested up to: 6.4
Stable tag: 1.0.0
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A one-line description of what your plugin does.

== Description ==

Longer explanation here. What problem does it solve? Who should use it?

Features:
* Feature one
* Feature two
* Feature three

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/my-plugin/`
2. Activate the plugin through the Plugins screen
3. Go to Settings > My Plugin to configure

== Frequently Asked Questions ==

= How do I use this? =
Clear answer here.

= Does it work with X theme? =
Answer addressing compatibility.

== Changelog ==

= 1.0.0 =
* Initial release

== Screenshots ==

1. This is the first screenshot
2. This is the second screenshot

The description section is where you tell your story. Explain the problem, show the solution, and be honest about what the plugin does and doesn't do. If there are known limitations, mention them upfront. Users appreciate transparency.

Screenshots are worth including. Take clear images of your plugin in action, and number them in order. The directory displays them on your plugin's main page, and they're often the deciding factor for whether someone installs your plugin.

Keep your documentation in the readme up to date. When you release version 1.1.0, update the changelog immediately. When you test against WordPress 6.5, update the "Tested up to" field. This ongoing maintenance signals to users that your plugin is actively maintained.

Use SVN for releases

The WordPress plugin directory uses Subversion (SVN) for version control, not Git. This is different from what many modern developers are used to, but it's how the directory infrastructure works. You'll need SVN client installed on your machine.

First, set up your local SVN repository structure. After your plugin is approved, you'll get SVN access. Here's the typical workflow:

// Check out the plugin repo
svn checkout https://plugins.svn.wordpress.org/my-plugin/ ./my-plugin

// Your directory structure should be:
// my-plugin/
// ├── branches/
// ├── tags/
// └── trunk/

// Copy your plugin files to trunk/
cp -r ./my-plugin-source/* ./my-plugin/trunk/

// Check status
svn status

// Add new files
svn add trunk/my-new-file.php

// Commit
svn commit -m "Initial version 1.0.0"

For each release, create a tag. When you're ready to release version 1.1.0, you tag the current trunk state:

// Create a tag from current trunk
svn copy https://plugins.svn.wordpress.org/my-plugin/trunk \
         https://plugins.svn.wordpress.org/my-plugin/tags/1.1.0 \
         -m "Version 1.1.0"

// Update the stable tag in readme.txt
svn commit -m "Stable tag is now 1.1.0"

The stable tag tells the directory which version to recommend to users. If you're still in development, point it to a release candidate. Once you're confident in a version, update it accordingly.

We always keep a clear separation: trunk is for development, and tags are immutable snapshots of releases. Never modify a tag after creating it. If you find a bug in version 1.1.0, release 1.1.1 as a new tag instead.

Respond to support threads

Once your plugin is live, users will post questions and issues in the support forum. Your responsiveness here directly affects your plugin's rating and download count. We treat support threads as seriously as we treat bug reports in our main codebase.

Set up notifications so you see support posts quickly. When someone reports an issue, respond within 24 hours if possible. Even if you don't have a solution yet, acknowledge the problem and set expectations for when they'll hear back.

Here's the kind of response that builds trust:

Thanks for reporting this. I can reproduce the issue on my end with version 1.0.5. It looks like a conflict with the WooCommerce template loader. I'm working on a fix and will have a patch in the next day or two. In the meantime, you can work around it by disabling the plugin and using X approach instead.

Be specific, be honest, and provide workarounds when possible. If someone finds a legitimate bug, fix it in a patch release. If the issue is caused by their specific setup, explain the root cause and help them troubleshoot.

When you release a fix, follow up in the support thread to let them know it's available. This kind of engagement shows that you care about your users' success, not just download numbers.

Common mistakes

We've seen plugins rejected for some avoidable reasons. Your plugin should not phone home to your server without explicit user permission or clear disclosure. It shouldn't inject tracking code, modify core files, or require activation of premium versions for basic functionality. Auto-updates should be optional, not forced. Database tables should be created during plugin activation with proper WordPress APIs, and cleaned up during deactivation.

Also, don't assume users understand technical language. If your plugin has settings, explain each option in plain English. Don't require payment upfront for basic functionality then sell "premium" versions that unlock core features—that's considered deceptive.

Finally, test on actual WordPress installs, not just your development machine. Conflicts with popular plugins matter. Slow database queries matter. Uninstallation that leaves orphaned data matters. The directory reviewers will check these things, and so should you before submission.

Key takeaways

• Read and follow WordPress plugin directory guidelines before writing a single line of code—security and best practices aren't optional
• Invest time in your readme.txt file since it's your plugin's landing page and how the directory indexes your work
• Use SVN correctly with a clear separation between trunk for development and tags for immutable releases
• Respond to support threads promptly and provide genuine help—your reputation depends on it
• Keep your plugin maintained and update compatibility tags regularly to stay visible in the directory