How to Submit Plugins to WordPress.org Repository (Complete Guide)

By Krasen Slavov WordPress Plugin Development Guide

Submitting your plugin to the WordPress.org repository gives you access to millions of potential users, automatic updates, and community support. This comprehensive guide walks you through the entire submission process from preparation to approval and beyond.

Benefits of WordPress.org Hosting

The official WordPress plugin directory offers significant advantages over self-hosting:

Visibility: Your plugin appears in the WordPress admin plugin installer, reaching millions of users searching for solutions.

Trust: Users trust plugins from the official directory more than unknown sources.

Updates: Automatic update notifications keep users on the latest version.

Statistics: Track active installations, downloads, and version adoption.

Support: Built-in support forums connect you with users.

Free Hosting: WordPress.org provides free SVN hosting and bandwidth.

Plugin Review Guidelines Overview

Before submitting, understand WordPress.org’s requirements:

  • GPL Compatible: Your plugin must use GPL or compatible license
  • Security: No vulnerabilities, malicious code, or obfuscation
  • Original Code: Don’t copy other plugins without attribution
  • Unique Functionality: Provide genuine value, not just a settings wrapper
  • Working Code: Plugin must function without errors
  • Proper Naming: No trademarks or confusing names
  • Data Privacy: Respect user data and comply with privacy laws

Review the complete guidelines at: https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/

Preparing Your Plugin for Submission

1. Choose a Unique Name

Search existing plugins to ensure your name isn’t taken:

https://wordpress.org/plugins/search/your-plugin-name/

Avoid names that:

  • Infringe on trademarks
  • Are too generic (“SEO Plugin”, “Contact Form”)
  • Mislead users about functionality
  • Contain “WordPress” or “Plugin” unnecessarily

2. Verify GPL Compatibility

Add GPL license to your main plugin file:

/**
 * Plugin Name: My Awesome Plugin
 * Description: A brief description
 * Version: 1.0.0
 * Author: Your Name
 * Author URI: https://yoursite.com
 * License: GPL v2 or later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: my-awesome-plugin
 */

Include LICENSE.txt file in your plugin directory containing the full GPL text.

3. Follow WordPress Coding Standards

Install and run PHP_CodeSniffer with WordPress rules:

composer require --dev wp-coding-standards/wpcs
phpcs --standard=WordPress my-plugin.php

Fix any errors and warnings before submission.

4. Security Review

Common security issues that cause rejection:

// BAD: Direct file access without WordPress context
<?php
// Missing this check
if (!defined('ABSPATH')) {
    exit;
}

// BAD: Unsanitized database queries
$wpdb->query("SELECT * FROM $wpdb->posts WHERE post_title = '{$_GET['title']}'");

// GOOD: Use prepared statements
$wpdb->get_results($wpdb->prepare(
    "SELECT * FROM $wpdb->posts WHERE post_title = %s",
    sanitize_text_field($_GET['title'])
));

// BAD: Nonces not verified
if (isset($_POST['my_action'])) {
    // Process without checking nonce
}

// GOOD: Verify nonces
if (isset($_POST['my_action']) && wp_verify_nonce($_POST['nonce'], 'my_action')) {
    // Safe to process
}

5. Remove Development Code

Delete or comment out:

  • var_dump() and print_r() statements
  • Console.log() calls
  • Debug flags
  • Test code and sample data
  • Commented-out code blocks

Creating readme.txt

The readme.txt file is crucial for your plugin listing. Use the standard format:

=== My Awesome Plugin ===
Contributors: yourusername
Donate link: https://yoursite.com/donate
Tags: seo, analytics, optimization, performance
Requires at least: 5.8
Tested up to: 6.4
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Short description of your plugin (max 150 characters).

== Description ==

Detailed description of your plugin's features and benefits.

= Features =

* Feature one
* Feature two
* Feature three

= Why Choose This Plugin? =

Explain what makes your plugin unique and valuable.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/my-awesome-plugin`
2. Activate through the 'Plugins' screen in WordPress
3. Use Settings->Plugin Name to configure

== Frequently Asked Questions ==

= How do I configure the plugin? =

Navigate to Settings > My Awesome Plugin and...

= Does it work with theme X? =

Yes, this plugin is compatible with all themes.

== Screenshots ==

1. Main settings page
2. Frontend display example
3. Analytics dashboard

== Changelog ==

= 1.0.0 =
* Initial release
* Added core functionality
* Implemented settings page

== Upgrade Notice ==

= 1.0.0 =
First stable release.

Generate a valid readme using the official tool: https://generatewp.com/plugin-readme/

Preparing Assets

Create banner and icon images for your plugin page:

Plugin Icon:

  • icon-128x128.png (required)
  • icon-256x256.png (2x retina)

Plugin Banner:

  • banner-772x250.png (required)
  • banner-1544x500.png (2x retina)

These go in an assets/ directory in SVN (not in your plugin folder).

Submitting Your Plugin

Step 1: Create WordPress.org Account

Register at: https://login.wordpress.org/register

Step 2: Submit Plugin

Go to: https://wordpress.org/plugins/developers/add/

Upload your plugin as a ZIP file. The review team will:

  • Check compliance with guidelines
  • Test basic functionality
  • Review code for security issues
  • Verify GPL compatibility

Step 3: Wait for Review

Review typically takes 1-15 days. You’ll receive an email when:

  • Your plugin is approved
  • Issues need fixing
  • Plugin is rejected

Common Rejection Reasons

1. Security Vulnerabilities

  • SQL injection possibilities
  • XSS vulnerabilities
  • Missing capability checks
  • Unverified nonces

2. Guideline Violations

  • Non-GPL code or unclear licensing
  • Including external libraries without proper licensing
  • Trademark violations
  • Malicious or obfuscated code

3. Functionality Issues

  • Plugin doesn’t work as described
  • Fatal errors on activation
  • Conflicts with WordPress core

4. Code Quality

  • Using deprecated functions
  • Direct database queries without $wpdb
  • Hardcoded database table names
  • Not using WordPress APIs

After Approval: SVN Repository

Once approved, you’ll receive SVN repository access. Your repo structure:

my-awesome-plugin/
├── trunk/
│   ├── my-awesome-plugin.php
│   ├── readme.txt
│   ├── includes/
│   └── ...
├── tags/
│   ├── 1.0.0/
│   ├── 1.0.1/
│   └── ...
├── assets/
│   ├── banner-772x250.png
│   ├── banner-1544x500.png
│   ├── icon-128x128.png
│   └── icon-256x256.png
└── branches/

Working with SVN

Initial Checkout:

svn co https://plugins.svn.wordpress.org/my-awesome-plugin
cd my-awesome-plugin

Add Your Files to Trunk:

cp -r /path/to/your/plugin/* trunk/
svn add trunk/*
svn commit -m "Initial commit of version 1.0.0"

Add Assets:

cp /path/to/images/* assets/
svn add assets/*
svn commit -m "Adding plugin assets"

Create a Release Tag:

svn cp trunk tags/1.0.0
svn commit -m "Tagging version 1.0.0"

Update readme.txt Stable Tag:

Stable tag: 1.0.0

The stable tag in readme.txt tells WordPress which tagged version to serve to users.

Releasing Updates

1. Update Code in Trunk:

# Modify files in trunk/
svn stat  # Check what changed
svn diff  # Review changes
svn commit -m "Update: Added new feature"

2. Update Version Numbers:

  • Plugin header version
  • readme.txt stable tag
  • Changelog in readme.txt

3. Create New Tag:

svn cp trunk tags/1.1.0
svn commit -m "Tagging version 1.1.0"

4. Update Stable Tag:

Edit trunk/readme.txt:

Stable tag: 1.1.0

Then commit:

svn commit -m "Updating stable tag to 1.1.0"

Managing Support Forum

WordPress.org provides support forums for your plugin. Best practices:

Response Time: Aim to respond within 24-48 hours

Be Helpful: Even for basic questions or user errors

Documentation: Link to documentation for common questions

Bug Reports: Ask for WordPress version, PHP version, error logs

Feature Requests: Thank users and consider for future versions

Mark resolved threads as resolved to keep the forum organized.

Handling User Reviews

Users can rate and review your plugin. Handle reviews professionally:

Positive Reviews: Thank users genuinely

Negative Reviews: Respond constructively, offer solutions

Unfair Reviews: Contact plugin review team if review violates guidelines

Feature Requests in Reviews: Acknowledge and point to feature request system

Never argue with users publicly or request review removal without valid reason.

Plugin Statistics

Monitor your plugin’s success through WordPress.org stats:

  • Active installations
  • Downloads per day/week
  • Version adoption rates
  • WordPress version compatibility
  • PHP version usage

Access stats at: https://wordpress.org/plugins/your-plugin/advanced/

Use this data to:

  • Decide which WordPress/PHP versions to support
  • Measure feature adoption
  • Identify usage trends

Maintaining Your Plugin

Regular Updates:

  • Test with new WordPress releases
  • Update “Tested up to” field in readme.txt
  • Fix reported bugs promptly
  • Add requested features when appropriate

Compatibility:

  • Support at least the last two major WordPress versions
  • Maintain PHP 7.4+ compatibility minimum
  • Test on common hosting environments

Communication:

  • Announce major changes on forums
  • Provide upgrade paths for breaking changes
  • Document deprecated features

Security:

  • Respond to security reports within 24 hours
  • Release patches quickly
  • Coordinate with security team if needed

Best Practices for Success

Quality Over Features: A simple, well-executed plugin beats a feature-packed buggy one.

Clear Documentation: Provide excellent docs, screenshots, and FAQs.

Active Support: Respond to support threads promptly and helpfully.

Regular Updates: Keep your plugin compatible with latest WordPress.

Listen to Users: User feedback drives valuable improvements.

Respect Guidelines: Stay compliant with WordPress.org policies.

Submitting to WordPress.org is just the beginning. Successful plugins require ongoing maintenance, support, and improvement. Treat your users well, and they’ll reward you with positive reviews, recommendations, and loyalty.

  • Benefits of hosting plugins on WordPress.org
  • WordPress.org plugin directory requirements
  • Plugin review guidelines overview
  • Preparing your plugin for submission
  • Code quality and WordPress coding standards
  • Security requirements and best practices
  • GPL-compatible licensing requirement
  • Creating a unique plugin name
  • Writing effective plugin descriptions
  • Screenshots and assets preparation
  • Banner images (772×250 and 1544×500)
  • Plugin icons (128×128 and 256×256)
  • Creating readme.txt file
  • Readme.txt format and sections
  • Stable tag vs trunk
  • Changelog formatting
  • FAQ section best practices
  • Submitting your plugin
  • Creating WordPress.org account
  • Plugin submission form
  • What happens during review
  • Plugin review team process
  • Common rejection reasons
  • Addressing reviewer feedback
  • Security issues to fix
  • Malicious code patterns
  • Obfuscated code prohibition
  • Service API guidelines
  • Including libraries properly
  • Trademark and naming issues
  • Handling plugin approval
  • Receiving SVN repository access
  • Understanding SVN version control
  • Trunk vs tags directory structure
  • Committing code to SVN
  • svn checkout, commit, and tag commands
  • Creating release tags
  • Uploading assets directory
  • Testing before release
  • After approval: next steps
  • Plugin page optimization
  • Support forum participation
  • Responding to user reviews
  • Plugin statistics and metrics
  • Updating your plugin
  • Version number increments
  • Testing updates thoroughly
  • Maintaining compatibility
  • Handling support requests
  • Documentation requirements
  • Plugin closure reasons
  • Avoiding guideline violations
  • Best practices for continued success

Includes submission checklists, readme.txt templates, SVN commands, and strategies for successful WordPress.org plugin approval and maintenance.

  1. WordPress Plugin Directory
  2. Plugin Handbook
  3. Plugin Review Team
  4. Detailed Plugin Guidelines
  5. SVN Tutorial

Call to Action

Supercharge your development! ACF Copilot Pro generates ACF field groups with AI, exports to PHP, and accelerates custom field workflows—try it free!

Related Articles