majiayu000 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.