WordPress 3.9 Guidelines Revision Proposal: Round 2

Based on the previous discussion, the Guidelines proposal has been revised as follows. The proposed guideline change for Credit Links has been removed, and a proposed guideline change for Custom Logos has been added. Other proposals have been clarified based on previous discussion.

The two most significant clarifications regard arbitrary 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./footer scripts, and Theme activation.

The proposed Recommended guidelines have not changed. While we understand the argument that there may not be consensus around certain implementations of features, we maintain that it is within the overall scope and objective of the Theme Review Team to encourage, facilitate, and drive best-practice consensus, and that it is in the best interest of end users to establish best-practice consensus. Thus, arguing that the Theme Review Team should not be establishing/promoting such best-practice standards in order to encourage consensus is moot – though we absolutely encourage discussion regarding what implementations should be considered/promoted as best-practice standards.

Other Discussion Topics


I would be interested in discussing our screenshot requirements. It seems that “reasonable facsimile”, as a standard, isn’t really sufficiently meeting anyone’s needs. While the intent was to avoid blatant marketing via screenshot, the requirement tends to be taken so literally that developers cannot even display user-configurable features in their screenshot. This is especially limiting for Themes with featured-content front-page templates. As currently interpreted, the “reasonable facsimile” standard prevents the screenshot from displaying the featured-content front-page, because the featured content first has to be configured. So, let’s discuss a more sane/useful guideline for screenshots.


I would also be interested in discussing the establishment of at least some “best practice” guidelines for translation-readiness – primarily, proper i18n of strings. I think it is all but a given that, eventually, we should be requiring Themes to be translation-ready; but currently we don’t have objective standards to follow. The first step, then, is creating those standards, and then educating developers on them.


Sane Defaults: Themes are required to use sane defaults.

Themes must not save default settings to the database without explicit user action, and Themes must function properly out-of-the-box without user configuration (that is: if the user does not save settings, the Theme will still function properly)

Bundled Plugins: Themes must not bundle Plugins.

Themes may incorporate support for Plugins, and may integrate 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 code directly into the Theme (if that Plugin code meets the presentation-vs-functionality requirement), but Themes must not bundle Plugins as a whole.

Arbitrary Header/Footer Scripts: Themes must not provide Theme options for arbitrary header/footer scripts.

Arbitrary scripts are non-Theme-specific scripts added to the document head or footer to provide non-Theme-specific functionality. Such scripts are Plugin territory, and pose a significant security risk if not handled properly.

Custom CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. is acceptable, if properly sanitized.

Note: this guideline does not apply to content “scripts” added to the template outside of the document head/footer, such as script widgets (Google Maps, Twitter Feed, etc.). Essentially, if a script can be hooked into the template via wp_head() or wp_footer(), then it falls under this guideline; otherwise, it does not.

Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality on activation.

Note: this guideline does not apply to admin notices such as TGM recommended Plugins (if implemented properly). I will open a separate discussion regarding consensus/standard “unboxing” admin notices. The purpose of this Guideline is to curtail the proliferation of unnecessary/obtrusive marketing in the user admin area, not to prevent legitimate, useful activation information for the end user.

Theme Documentation: Themes must place any required documentation in a clearly marked readme file.

Note: this guideline applies only to required documentation. Required documentation includes copyright/license attributions, Theme design constraints/limitations, description of non-standard Theme functionality, etc. Plugin-standard readme.txt is preferred, but not required.

License: Themes are required to document in the Theme readme or license file the copyright/license attribution for all bundled resources.

Themes are required to provide this documentation in the Theme readme file, regardless of where or how those bundled resources provide their own attribution. The purpose is to ensure that end users (and also, reviewers) don’t have to search for this important information, and to ensure that the developer has done due diligence to ensure that licenses for all bundled resources are 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.-compatible.

Note: “blanket” statements for developer-owned resources (images, etc.) bundled with the Theme are perfectly acceptable. It is only third-party bundled resources that need to be listed explicitly.

Custom Logos: If implemented, custom logos must be user-configurable, and disabled by default.

This guideline will bring the handling of Theme options for custom logos in-line with the handling of Favicons. Currently, we require that “default” logos be generic/unbranded, but generic/unbranded logos are of no benefit to the end user. Likewise, Theme-branded logos are of no benefit to the end user. The most logical approach, then, is to require that custom logos not be displayed at all, unless the end user has configured one.


Theme Documentation

Themes are recommended to include a Plugin-standard readme.txt file.

Themes are recommended to meet the WP coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. standard for inline documentation.


Themes are recommended to be translation-ready.

Social Profile Links

Themes are recommended to use a custom navigation menuNavigation Menu A theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site. when incorporating social network profile links

Theme Options

Themes are recommended to integrate Theme options into the core Theme 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.


Please discuss in the comments below.  If you have any additions to propose, please post them in the comments below, as well.