WordPress.org Plugin Compliance Guidelines

Ensures WordPress.org compliance for plugin directory guidelines, particularly around free vs premium code and upselling practices.

When to Use This Skill

Trigger scenarios:

• Adding new features that might have premium versions

• Implementing upselling or upgrade prompts

• Creating "teasers" for premium features

• Reviewing code for WordPress.org compliance

• Preparing plugin updates for WordPress.org submission

• Adding license key validation or premium checks

Core Rule: No Locked Code

WordPress.org Golden Rule: No premium/locked code in wp.org plugins. All hosted code must be free and fully functional.

This means:

• Every feature in the free plugin must work completely without a license key

• No "trial periods" or usage limits

• No features that require payment to unlock

• No functionality restricted behind a paywall

Quick Reference

❌ NOT Allowed

• Trial periods or time limits

• Usage quotas or artificial limits

• License keys for local features

• Disabled features requiring payment

• Crippled functionality in free version

• Intrusive nag screens

✅ Allowed

• Informational upselling (non-intrusive)

• Separate premium plugin from your site

• Feature detection (not restriction)

• External SaaS integrations

• Comparison tables

• Premium feature teasers

• Disabled form teasers for premium-only features (high conversion)

Key Patterns

❌ Wrong: Feature Restriction

// Blocks functionality without license if ( ! $this->is_premium() ) { echo 'Premium required'; return; }

✅ Correct: Feature Detection

// Free version works fully $this->show_basic_export();

// Premium can enhance if ( $this->has_premium_addon() ) { do_action( 'sh_premium_export_options' ); }

❌ Wrong: Artificial Limits

// Artificially limits free version $limit = $this->is_premium() ? 10000 : 100;

✅ Correct: No Artificial Limits

// Free version has reasonable limit $limit = 10000;

// Premium can extend $limit = apply_filters( 'sh_event_limit', $limit );

Recommended Freemium Model

Free Plugin (WordPress.org)

• Core functionality fully working

• Basic features complete

• All UI features accessible

• No artificial limitations

Premium Plugin (Your Site)

• Extended features (not unlocked basics)

• Premium integrations

• Advanced functionality

• Priority support

Installation Options

Add-on Style (Recommended):

• Free: Standalone and functional

• Premium: Installs alongside, extends free

• Both active together

Replacement Style:

• Free: Standalone and functional

• Premium: Replaces free with more features

• User deactivates free when installing premium

Upselling Best Practices

✅ Good Upselling

// Subtle, informational function render_premium_note() { ?> <p class="sh-premium-note"> <small> 💡 Premium: Export to JSON, XML, or PDF formats. <a href="https://example.com/premium/">Learn more</a> </small> </p> <?php }

✅ High-Converting: Disabled Form Pattern

For premium-only features, show a disabled form that previews the UI:

// Shows what premium feature looks like (greyed out, non-functional) // CTA box remains clickable - converts 3-4x better than info box <div class="sh-PremiumTeaser-disabledForm" style="opacity: 0.6; pointer-events: none;"> <table class="form-table"> <tr><th>Setting</th><td><select disabled>...</select></td></tr> </table> <div style="pointer-events: auto; opacity: 1;"> <?php echo Helpers::get_premium_feature_teaser(...); ?> </div> </div>

See examples.md for full implementation details.

❌ Bad Upselling

// Blocks functionality if ( ! $this->is_premium() ) { echo '<div class="error">Upgrade required!</div>'; return; }

Compliance Checklist

Before submitting updates to WordPress.org:

• All features work without license key

• No trial periods or time limits

• No usage quotas or restrictions

• No features disabled for free users

• Upselling is informational, not obstructive

• Premium features are separate addon

• No "locked" UI elements

• Free version provides real value

Code Review Questions

For each feature, ask yourself:

• Does it work completely without premium?

• Am I checking for a license key to enable functionality?

• Would a free user be frustrated by this?

• Is the upselling helpful or annoying?

• Does the free version provide real value?

Common Violations

Violation 1: Nag Screens

❌ Don't show constant popups asking users to upgrade

Violation 2: Crippled Features

❌ Don't make features "work badly" in free to force upgrades

Violation 3: Expired Trials

❌ Don't stop working after X days

Violation 4: Usage Limits

❌ Don't impose artificial quotas

Violation 5: License Validation for Local Features

❌ Don't require license key for features that run locally

Detailed Information

For comprehensive examples and testing procedures:

• See examples.md for detailed code examples of allowed and forbidden patterns

• See testing.md for complete testing procedures, code review checklists, and pre-submission verification

Resources

• Official Guidelines: https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/#5-trialware-is-not-permitted

• WordPress.org Plugin Directory: https://wordpress.org/plugins/

• Plugin Review Team: For questions about compliance

Summary

The Simple Rule: If it's in the WordPress.org version, it must work completely without payment.

The Philosophy: Win users over with quality, not restrictions. Make them want premium, not need it.

The Test: Would you be happy using the free version? If not, you're doing freemium wrong.