Things to consider when using underscores

I use underscores as a base for my WordPress themes, and many -if not most -themes submitted to the WordPress.org’s theme directory are based on it as well.

But there are some typical mistakes that we see frequently in underscores based themes:

Using old versions
Don’t use old versions of underscores, since they may contain references and fall backs for older functions. Always use a fresh copy.

Forgetting to update the readme files
Underscores comes with two readme files, one .txt and one markdown.
Depending on where you downloaded it from and whether or not you used the advanced option on underscores.me, you need to update these files.
Otherwise your readme files will not be about your theme, and they will read something like:
Contributors: automattic
_s
===
Hi. I'm a starter theme called `_s`, or `underscores`, if you like. I'm a theme meant for hacking so don't use me as a Parent Theme. Instead try turning me into the next, most awesome, WordPress theme out there. That's what I'm here for.

Imagine the users surprise when they open the readme and find instrutction on how to
1. Search for `'_s'` (inside single quotations) to capture the text domain.

Removing the credit
Some authors remove the credit that says that the theme is based on underscores. Please keep this in the theme. Be fair to other theme authors who has shared their work with you.
Theme name is based on Underscores http://underscores.me/, (C) 2012-2016 Automattic, Inc.
Underscores is distributed under the terms of the GNU GPL v2 or later.

and
== Credits ==
* Based on Underscores http://underscores.me/, (C) 2012-2017 Automattic, Inc., [GPLv2 or later](https://www.gnu.org/licenses/gpl-2.0.html)
* normalize.css http://necolas.github.io/normalize.css/, (C) 2012-2016 Nicolas Gallagher and Jonathan Neal, [MIT](http://opensource.org/licenses/MIT)

Forgetting to update the theme and author URI
I can only imagine that the author was in a bit of a hurry here, but it is not uncommon that authors forget to update the links in style.css and in the footer credit.

Forgetting to update the language file
Authors often add new text strings to their theme but forget to update the language file.
Besides updating the strings, you also need to update the following file information:

# Copyright (C) 2017 Automattic
# This file is distributed under the GNU General Public License v2 or later.
"Project-Id-Version: _s 1.0.0\n"
"Report-Msgid-Bugs-To: https://wordpress.org/tags/_s\n"

-If you also choose to include an .mo file, make sure to rename it to the locale.
https://developer.wordpress.org/themes/functionality/localization/

Forgetting to update the text domain or prefix
Sometimes authors who use the search and replace method to change the text domain and prefix of the theme misses a couple of places.

 

 

How to get your theme live faster

When authors submit themes to the WordPress.org theme directory they are sometimes surprised that they might need to wait up to 8 weeks for a review.
One of the resons to why it can take this long is that many authors submit themes that are incomplete.

By checking these four things you can greatly reduce the time it takes to review your theme:

  • License
  • Code Errors
  • Security
  • Translation

Back to basics

The list of requirements is long and we as reviewers understand if authors miss some of them. In fact very few themes are set live in the theme directory without changes.
However, I feel strongly that theme authors, –especially those who sell themes -at least should get the basics right.

License

WordPress themes need to be 100% compatible with GPLv2 or later.
The theme directory cannot redistribute your theme if you use items that have a license that limits redistribution or commercial use.
I expect authors to understand the difference between copyright and license. I expect them to include information about both in the theme.
If a theme has a commercial version,  that version also needs to be 100% compatible with GPL.

How to check:
Open style.css. Make sure that your stylesheets file header has a license statement.

Examples:
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
or:
License: GNU General Public License v2 or later
License URI: LICENSE
Where license.txt is included and contains a copy of the license.

Open the readme file.  Make sure that you have included a copyright notice for the theme.

Example:
Twenty Seventeen WordPress Theme, Copyright 2016 WordPress.org

Make sure that you have listed the names, source, copyright and license information for all resources like third party scripts, styles and images, including images used in the screenshot, since the screenshot is part of the theme.

Code

Do not include code that you don’t understand. This might seem obvious,  but many authors copy and paste code from others without understanding what the code does. Keep your code simple. Comment and document your custom code. The reviewer might need to ask questions about your code, and more advanced code takes longer to review.

Do not include code, files or folders that are not used in the theme. Asking us to review code that is not even used will delay your review further. It’s a waste of our time.

Test your theme on different PHP versions. Test all your custom page templates, options, and custom widgets. Check for JS errors and missing files. Do not rely on the reviewer to do this for you. The reviewer is not your tester, we expect you to check this before you submit the theme.

Security

We understand that security can be the hardest part. But there are some simple rules that you can use when developing and checking your theme.

  • Don’t trust any data.
  • Escaping and sanitizing:  You can’t have one, you can’t have none, you can’t have one without the other.
  • Don’t include external files. All scripts, styles and images should be included in the theme. The exception is google fonts.

Untrusted data needs to be validated and/or sanitized before saving, and escaped as late as possible before output. Theme options are not considered safe.

By far the most common problem that we see in themes is missing escaping, or using the wrong function.
Untrusted links should be escaped using esc_url().
esc_attr()  -Attr stands for attribute. This should only be used inside actual html attributes like title, alt, width, height, placeholder and similar. It should not be used between html tags.
esc_html() This should only be used between html tags. It should not be used inside html attributes.

The customizer has a range of different control types, and authors can also add custom controls.  We often find that authors use sanitize_text_field() for all their control types, even controls that are not text fields.
Use a sanitize_callback that is suitable for your control type.

How to check:
Search your theme files for: sanitize_callbackesc_attr, esc_html and echo get_theme_mod.

Make sure that all text strings are translatable

There is no shortcut for this. The best way to make sure that all your texts are translation ready is to add the translation functions when you build the theme, instead of trying to add them afterwards. Finding text strings that are missing translation functions is a very time consuming job, where both the reviewer and the theme author needs to manually open all files -including JS files, to find these text strings.
You can understand why this slows the review process down for everyone, and why this increases the waiting time.

 

 

Help the reviewers and your fellow theme authors to reduce the queue time for everyone by only submitting complete, tested themes.
By checking these four things before you submit your theme, you have also reduced the risk of having your theme closed as not approved.

The Theme Review Team is open to everyone, and you can help out by reviewing submitted themes for these issues. With the help of more reviewers, the waiting time will be shortened.

Become a Reviewer

My theme review process

Updated September 2017.

The Theme Review Team on WordPress.org encourages reviewers to find their own flow and tools that work for them. There is no right or wrong way to review a theme, as long as the requirements are checked and the author receives useful feedback.

My personal review process require a lot of manual effort. I know that some of the things that I do manually can be replaced by the new Theme Sniffer plugin, and I will eventually adjust to that.

Tools:

I use VVV (on Windows 10) but also have a live install available in case I need to show the author something.

I use Sublime Text code editor with the PHP Code Sniffer installed.
I like to use Poedit to check translation files, but Sublime Text can also read the pot files.
To create GIFS (for example to illustrate a broken menu), I use GifCam.
The theme unit test data: https://codex.wordpress.org/Theme_Unit_Test
A .txt document with my  standard review text.

Plugins:

The new developer version of the Theme Sniffer.

Preparations:

I always import the Theme unit test and I keep the requirements page and the WordPress developer reference open.

Process:

Normally it takes me 5-10 minutes to see if a regular sized (or underscore based) theme needs to be closed because there are 5 distinct issues, or if the review can continue.
But summarizing the findings and adding references, explanations and images to help the author fix the issues takes longer, from 20 mins and up.

I try to consider whom I am writing the review for:
-Do I need to add references?
-Do I need to help them find a solution, or is it enough if I mention the issue?

Not all steps are performed on all themes, it depends how the theme is built.
I also split large themes over several reviews, because I don’t always have enough time to check several hundred files in one go.
If I quickly find 5 distinct issues I may close the theme as not approved without doing a full review.

First I check if the screenshot in the ticket is reasonable and not a logo or mockup.
Then I check the Theme and author URI before I download the zip file.

I look through the theme files before I install the theme.
I normally start by opening functions.php, header.php and footer.php:

  • Are there hard coded scripts?
  • Is there text that is not translation ready?
  • Is everything escaped?
  • If there is a footer credit link does it match theme or author URI?
  • Are the functions in functions.php prefixed and are scripts and styles enqueued correctly?
  • Are menus, widget areas and theme support added correctly?

Then I check if there are folders named js, css, dist, assets or similar, and if there are minified files. I also check if there are any plugins, demo files or similar included in the theme folders.

  • If there are minified files, is the non-minified version included as well?

Then I open style.css, readme and license files and make sure that the license and copyright information for the theme and the assets have been added.

This is when I start making notes and adding items to the review.
I already have texts written for common errors that I can add and adapt for the specific theme.

Run Theme Check

  • Are there any errors reported?
  • Check any warnings manually.

Then, depending on the theme, I use my code editor to search the entire theme folder for the following:

  • get_theme_mod -This helps me find theme mods that are not escaped.
  • remove -This helps me see if the author has removed any customizer settings or non-presentational hooks.
  • function, -This gives me a handy list to help me check prefixes and whether custom functionality is used in place of WordPress functionality.
  • script -This helps me find hard coded scripts.
  • alt=, title=, placeholder= -This will help me find translated texts in attributes and make sure the texts are escaped.
  • add_theme_support – This helps me check if the author has added support for title (required), custom logo (instead of using their own) etc.
  • If there are multiple post formats and templates I might also search for wp_link_pages, query and reset.

Then I install and activate the theme to make sure that:

  • There are no php or js errors.
  • There is no redirect on activation.
  • Notices are not global and can be dismissed.
  • Plugins are not required, only recommended.

I don’t spend more than a few minutes on testing the theme layout, more effort is put into testing any custom options.

  • Is the correct number of posts displayed?
  • Are comments displayed correctly?
  • Are there any php or js errors?
  • Perform a search.
  • Test the 404 page.
  • Test the navigation.
  • Set up a menu, is it working? Test the menu in a smaller window, is it working? Make sure that it is not overlapping or in other ways disturbing the admin bar.
  • Test custom widgets and make sure there are no php notices, warnings or errors.
  • Make sure that there is only minor content creation.

When I go to the customizer and test the options, I also open the customizer.php or related files in my editor and make sure the options are sanitized and set up correctly.

  • Check to see if there is demo content, content creation or plugin territory functionality.
  • Is the upsell reasonable and is it added with the customizer API?

Go to the post editor and double check if any meta fields has been added, and that they are for presentation, not content.
Test the meta options.
Repeat for pages.
Test page- and post templates.

If there is starter content, reset the install to fresh and test it.

Is there any functionality or special items that should be granted an exception from the requirements?
Does the theme match the tags and description in style.css?

Whether I find issues or not, I still open each file in the theme folder manually and review them quickly, including minified files.
This is still the fastest way for me to check for untranslated texts and anything that stands out.

When the review is finished, I save it as a .txt file and then cut and paste the text in the Trac ticket.

By saving the reviews, I have built up a library of texts that I can re-use for other themes with similar problems.

Tips

The more themes you review, the easier it will be for you to find things that stand out, and your reviews will be faster.
Read the WordPress code, read more themes and also read other peoples reviews.
Read the theme developer handbook and get familiar with the developer code references.
Learn Underscores.
Share your knowledge with other reviewers, and accept that you can’t know everything, -ask questions when you are not sure about something.

 

You don’t need searchform.php

Searchform.php is only needed if you are actually making changes to the default search form.

While reviewing themes submitted to WordPress.org, I often notice that authors are including searchform.php without making any changes compared to the default form.

Other authors are using

add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption' ) );

But replacing the search form with a non html5 form. This is unneccesary.

The Developer Code reference on WordPress.org explains how get_search_form() first attempts to locate the searchform.php file in either the child or the parent theme, then load it. If it doesn’t exist, then the default search form will be displayed.

get_search_form()