How to get your theme published on WordPress.org

Press Publish

Earlier this month, we managed to get our first theme approved on WordPress.org. This was an exciting moment for us, putting our code in front of millions of WordPress users.

During the nine months it took for our theme to go live, we learned a lot about the WordPress.org theme approval process. In this guide, I’m going to show you how to navigate the approval process so, hopefully, you’ll get your theme approved more quickly.

How does the theme approval process work?

Once you’ve designed your theme, there are four steps to get your design approved on WordPress.org.

  1. Test your theme carefully against the WordPress.org theme requirements.
  2. Log in to WordPress.org and upload your theme.
  3. WordPress.org volunteers will review your theme to make sure the code is secure and meets WordPress standards.
  4. After code approval, a WordPress.org admin will approve your theme.
  5. Your theme goes live on WordPress.org!

Step No. 1: Check your theme

Before you start, carefully check the WordPress.org Theme Requirements. That list covers a wide variety of topics. Code guidelines you’ll need to meet include:

  • No PHP or Javascript errors.
  • All theme text strings must be translatable.
  • No minification of scripts or files unless you also provide the original files.
  • Prefix functions and classes.
  • Don’t include favicon, CSS or Javascript directly in the header. They must be loaded from functions.php instead.

There also are licensing and branding guidelines, including:

  • The theme must be 100-percent GPL and/or 100-percent GPL-compatible licensed, including any images.
  • Theme names must not use: WordPress, Theme.
  • Spell “WordPress” correctly in all public-facing text.

And there are usability guidelines like these:

  • No disabling of the admin toolbar.
  • No pay wall restricting any WordPress feature.
  • The theme must not configure non-theme site options or site functionality.

Once you’ve checked your theme against the requirements, you can use the Theme Check plugin to review your theme’s code. You can install Theme Check from the WordPress Plugin Directory, but I’d recommend that you use the Github repository version, which is always the latest release.

In your WordPress admin area, go to Appearance, then Theme Check. The plugin will run all the same automated testing tools on your theme that WordPress.org uses.

green-box-screenshot

Step No. 2: Upload your theme

Log in at WordPress, or create a new account if you haven’t done so already.

Go to https://wordpress.org/themes/upload/ and you can upload your theme. This upload process will run a series of automatic checks to make sure your theme passes a series of tests, such as having a style.css file and having a unique name.

theme-directory-screenshot

Step No. 3: Theme review

Once uploaded, your theme will wait for a reviewer to claim it and start the review process. The WordPress.org theme reviewers are all volunteers and they are really, really busy. Don’t be surprised if it takes a while for your theme to be reviewed and published.

If you don’t receive any updates from your reviewer, I’d recommend joining the WordPress Slack platform using these instructions: https://make.wordpress.org/chat/. The Theme Review team has their own channel inside Slack, and this is where many of the most active reviewers hang out. The people in this channel were enormously helpful when we had newbie questions, or when our theme became stuck in the review process.

slack-screenshot

You can see some sample reviews at http://themes.trac.wordpress.org.

Many themes are published in a few weeks or months, but if you’re not proactive with your review, it can take longer. Our approval process took nine months — and some themes have been in the process for more than a year.

Before submitting any update, fully test your theme in local, from installing to customizing widgets, menus, etc.

Become your end user and try to break the theme to detect bugs.

 

Import the Theme Unit Test Data.

Download the XML by right-clicking and saving the information from here. Import it into your WordPress test site through Tools > Import.

Step No. 4: Theme approval

After your theme has passed the initial review, it will be passed onto a theme admin for approval. The admins are the people who do much of the behind-the-screen work for the Theme Review Team: https://make.wordpress.org/themes/handbook/the-team/members/.

There might be several dozen themes waiting in this admin review queue. You can see the current list at https://themes.trac.wordpress.org.

detailed-grid

Step No. 5: Approval!

If you successfully complete the review process, you’ll get an email like this:

wp-themes-screenshot

Now, a huge percentage of Internet users will be able to log in to their WordPress dashboard, click Appearance and install your theme. Here’s OSTraining Breeze inside the Themes area:

theme-in-customizer-screenshot

After your theme goes live, you will probably get a good number of downloads immediately. We had over 100 downloads every day during the first two weeks, and that was with zero promotion.

bar-graph

Some themes from popular designers might get far more. “Himalayas” from ThemeGrill (which has 10 themes on WordPress.org), had an average of 400 downloads during its first two weeks.

bar-graph2

So, although it can be a long process, it’s absolutely worth spending the time to get your theme published in WordPress.org. As a coder or designer, you get the satisfaction of making your work easily available to millions of people. If you’re a business, you gain access to a large base of potential customers.

You can see our theme, OSTraining Breeze, is now live on WordPress.org. I wish all the best in getting your theme approved, too!

ostraining-screenshot

Image by: ramseybuckeye via Compfight cc

Steve Burge
Steve is from Portsmouth in southern England and now lives in Sarasota, Fla. He runs OSTraining.com, which teaches people how to build websites. OSTraining clients include more than 40,000 individuals, plus large organizations such as Apple, Pfizer and the U.S. Departments of Energy, Education and Commerce. Steve has written three books: “Joomla Explained,” “Joomla 3 Explained” and “Drupal 7 Explained.” Those books were the best-selling books for their platforms, so he's busy writing more. Look for “WordPress Explained” and “Drupal 8 Explained” to be published soon.