Theme Review Requirements and Documentation

Some time ago, the Theme Review Guidelines underwent a major revision, with focus on Theme Review Requirements, and moving of the official version of those Requirements from the Codex to the Theme Review Handbook. During that change, several requirements were omitted from the previous iteration. Those omissions, along with the apparent spread of documentation locations, has led to considerable confusion for admins, reviewers, and developers alike.

Let’s sort that out, and clean it up.

Documentation

Documentation Sources

Handbook

The only and official Theme Review documentation is the Theme Review Handbook. Within that handbook are the Theme Review Requirements.

The Requirements page in the Handbook is deprecated. It should be removed. Until just a moment ago, it was linked from the welcome box on the front page of Make/Themes. I have changed that to a link to the official Requirements ins the Handbook.

The various Handbook pages linked from the Theme Review Codex page are also deprecated, and should be removed.

Make/Themes

The Make/Themes site (this site) is where we post official things, and generate discussion not well-suited to SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. Anything discussed on Make/Themes is unofficial/discussion-only, unless and until it is posted in the Handbook, whether as a Requirement or a Recommendation.

Codex

The Codex is deprecated, and is slated to go away at some point. Thus, the Theme Review page on the Codex is no longer official, or maintained.

Summary

Official:

Unofficial/Discussion-Only:

  • Make/Themes blog posts

Deprecated:

Requirements

Next: requirements. Please discuss the additions in red italic, below. I am proposing them to be included again in the official version. The complete list of current Requirements is below:

A theme must meet all of the following requirements to be included in the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ theme repository.

Along with these checks you should also make sure you run the theme through the theme check pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. It automatically checks for all the required items. You can find a full list of what it checks here.

AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)

  • If the theme has the tag ‘accessibility-ready’ then it needs to meet these requirements.

Code

  • No PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. or JS errors.
  • Include at least index.php and style.css.
  • Have a valid DOCTYPE declaration and include language_attributes.
  • Sanitize everything.
  • No removing or modifying non-presentational hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same..
  • No shortcodes are allowed.
  • Support the following WordPress-generated CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. classes:
    • alignleft
    • alignright
    • wp-caption
    • wp-caption-text
    • gallery-caption
    • sticky (can be unstyled)
    • bypostauthor (can be unstyled)
    • screen-reader-text
  • No backwards compatibility support for outdated versions of WordPress
  • No Theme Check required notices
  • No deprecated function or doing_it_wrong() notices
  • Provide a unique slug for everything the Theme defines in the public namespace
  • Prefix all options, custom functions, custom global variables and custom constants with the theme-slug. (Note: moved from Options and Settings, as the requirement has a wider scope than just options)

CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Functionality and Features

  • Use WordPress functionality and features first, if available.
  • Don’t include admin/feature pointers.
  • No custom post types and no custom taxonomies.
  • No pay wall restricting any WordPress feature.
  • No disabling of the admin tool bar.
  • Use get_template_directory() rather than TEMPLATEPATH to return the template path.
  • Use get_stylesheet_directory() rather than STYLESHEETPATH to return the stylesheet path.
  • Avoid hard coding to modify content. Instead, use function parameters, filters and action hooks where appropriate. For example wp_title should be modified using a filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..
  • Able to have child themes made from them. (Child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/. ready)
  • Include comments_template().
  • The theme tags and description must match the what the theme actually does in respect to functionality and design.
  • Properly implement core template tags and action/filter hooks, when used.

Presentation vs. Functionality

  • Since the purpose of Themes is to define the presentation of user content, Themes must not be used to define the generation of user content, or to define Theme-independent site options or functionality.

Documentation

  • Any custom features, options or any limitations (for example menu restrictions), should be explained. Enough documentation should be provided.

Favicons

  • If implemented, disable favicons by default and have the ability for users to override.

Language

  • All theme text strings are to be translatable.
  • Include a text domain in style.css
  • Use a single unique theme slug – as the theme slug appears in style.css. If it uses a framework then no more than 2 unique slugs.
  • Can use any language for text, but only use the same one for all text.

Licensing

  • Be 100% GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples. and/or 100% GPL-compatible licensed.
  • Declare copyright and license explicitly. Use the license and license uri headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. slugs to style.css.
  • Declare licenses of any resources included such as fonts or images.
  • All code and design should be your own or legally yours. Cloning of designs is not acceptable.

Naming

  • Theme names must not use: WordPress, Theme.
  • Spell “WordPress” correctly in all public facing text: all one word, with both an uppercase W and P.

Options and Settings

  • Save options in a single array.
  • Use sane defaults and don’t write default setting values to the database.
  • Use edit_theme_options capability for determining user permission to edit options, rather than rely on a role (e.g. “administrator”), or a different capability (e.g. “edit_themes”, “manage_options”).
  • Use the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. for implementing theme options.

Plugins

  • Don’t include any plugins. A theme can recommend plugins but not include those plugins in the theme code.
  • Don’t do things in a theme considered plugin territory.

Screenshot

  • The Screenshot should be of the actual theme as it appears with default options, not a logo or mockup.
  • The screenshot should be no bigger than 1200 x 900px.

Security and Privacy

  • Don’t phone home without informed user consent. Find out more about security here.
  • Make any collection of user data “opt-in” only and have a theme option that is set to disabled by default. Validate and sanitize untrusted data before entering into the database. All untrusted data should be escaped before output. (See: Data Validation.)
  • No URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org shorteners used in the theme.
  • Use esc_attr() for text inputs and esc_textarea() for textareas.

Selling, credits and links

  • If you are a theme shop you should be selling under GPL to be in the WordPress.org repo.
  • If the theme adds a footer credit link, there should only be one (link to WordPress does not count)

Stylesheets and Scripts

  • No hard coding of scripts, styles and Favicons unless a browser workaround script. Everything should be enqueued.
  • No analytics or tracking.
  • No minification of scripts or files unless provide original files.
  • Required to use core-bundled scripts rather than including their own version of that script. For example jQuery.
  • Include all scripts and resources it uses rather than hot-linking. The exception to this is Google libraries.
  • If a tag is used in style.css the theme should support that feature or adhere to what that tag stands for. For example custom background or header.

Templates

  • If using templates, custom template files should be called using get_template_part() or locate_template().
  • There are several template specific things you should consider when certain ones are being used.
  • Use *_url() template tags, rather than bloginfo() equivalents.
  • Template files must follow the template hierarchy.

Obsolescence

  • Themes are required to be kept current once accepted in the Theme directory.

It’s worth noting we are working to automate a lot of the above requirements.

Along with the required items, you should also consider the recommended items. The recommended items are there to make sure your theme is the best it can be and good advice to include as best practice.

I am formally proposing that the text in red-italic be restored to the Theme Review Requirements. Please discuss in the comments.