WordPress 3.9 Guidelines Revisions Proposal

It’s just about that time again, with the WordPress 3.9 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. just around the corner. We’ve taken a few release cycles off from making any major changes to the Guidelines, so now is a good time to take a look at what we can improve. To kick off the discussion, the admins propose the following revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. to the Guidelines:


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 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: 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. Suchscripts 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.

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

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

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

Theme Credit Links: ThemeURI and AuthorURI, if both are used, must be from distinctly separate sites.

Using both ThemeURI and AuthorURI is not required, and if only one is appropriate, then only one should be used. ThemeURI is a resource specific to the Theme. AuthorURI is a resource specific to the developer. For example, a Theme shop really only needs to use examplethemeshop.com OR examplethemeshop.com/themes/theme-slug. There’s really no need for both. Likewise, a non-commercial individual really only needs to use exampleperson.com OR exampleperson.com/blog/post-about-theme-slug. There’s really no reason to use both. But, if an individual has a ThemeURI of github.com/authorname/theme-name, and an AuthorURI of exampleperson.com, that’s totally appropriate.

The intent here is to try to drive the focus of ThemeURI and AuthorURI back to being *end user* resources, first and foremost: information about the Theme, or a way to contact the developer. This clarification will hopefully eliminate some of the issues regarding appropriateness of ThemeURI/AuthorURI.


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.


Is the Theme Directory “Blog” Focused?

Some recent discussions in the community have indicated that the Theme directory is too “blog” focused, and that the Guidelines actively discourage non-blogging Themes from being submitted.  There are some things that are true, some things that are untrue, and some things that are simply outside of the control of the Theme Review Team, in terms of the Theme directory and “non-blogging” Themes.

One thing that is true is that the current stance of the Theme Review Team is that the “CMS” use case is not significantly compelling for a Theme to omit support for a blog. From a coding perspective, the differences between a post loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. and a static page loop are minimal. From a user perspective, there is no real reason to restrict a “CMS” Theme’s user base only to users who don’t intend to use the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blog functionality.

Another thing that is partially true is that the current Theme Unit Tests appear heavily blog-centric. But that’s mainly because the unit tests are presented as blog posts. Some things – taxonomies, posts navigation, post formats, etc. – only apply to blog posts; but most of the rest of the Theme Unit Tests apply equally regardless of post type. The Theme Unit Tests are designed as test-every-reasonable-use-case data: to push edge cases and boundaries, to ensure that Themes accommodate the widest possible range of use cases and to see how Themes respond to break points. Generally speaking, the entire suite won’t apply to any given Theme (for example, most Themes don’t add support for all post formats; so the unit tests for unsupported post formats wouldn’t apply).

By contrast, one thing that is not true is that there is no recourse for hosting a non-traditional Theme in the Theme directory. Want to submit a Theme intended to be used as a support ticket system, a knowledge base, or a presentation slideshow? Those are all welcome in the Theme directory.  We refer to these Themes as “niche” or “custom use” Themes, and we already have a mechanism in place to “whitelist” those Themes so that they can bypass non-applicable upload script tests. All we ask is that developers email the mail-list and ask for an exemption, along with explaining the justification.

But there are many things that are outside of the control of the Theme Review Team, including anything that deals with the infrastructure of 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//themes itself. We have one Theme directory to work with. We can recommend 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. tags to be added, removed, or modified; but we don’t make the final call on them. We have no control over the each Theme’s page in the directory, the ratings/review system, the algorithms for trending Theme lists, or pretty much anything other than actually marking Themes as “live” in the directory, after completing a review. There are many ways that these things could be improved, but we are dependent on other people who have much higher priorities in the grand scheme of the WordPress project and website.

I would love to have the ability to host Theme frameworks (in the classic, non-marketing sense of the term: a drop-in code library that facilitates Theme development) in the directory, it would greatly simplify review for Themes that use frameworks such as Hybrid Core and the like; but we currently have no infrastructure to do so. I would love to have the Theme’s directory listing page parse the Theme’s readme file the same way that a 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’s listing page parses its readme; but that’s something else that isn’t possible at the moment.

I would love to explore the idea of having multiple Theme directories, or some sort of “tier” system; but we just don’t have that infrastructure. And that’s one of the primary reasons that we have what appears to be a “one size fits all” approach and mechanism for Theme submission, review, and approval – but that doesn’t mean that we can’t or won’t accept submissions for Themes that don’t fall strictly within the “blogging” genre. If you have an idea or question, mail the Theme Reviewers mail-list and ask. It can’t hurt anything, and you very well may be surprised by the response.

#discussion, #guidelines

Theme Unit Tests: Recommended

Based on the recent discussion prompted by @lancewillett, the following change has been made to the Guidelines, effective immediately: the Theme Unit Tests have been reduced in criticality from Required to Recommended.

We believe that this change will help eliminate a source of subjectivity/inconsistency in Theme reviews, while ensuring that review effort focuses on the truly required criteria. And in all honesty, almost everything that is truly required in the Theme Unit Tests will be found during the code review. In the future, this change may allow us to re-focus the Theme Unit Tests on recommended/best-practice design/aesthetics, without introducing further subjectivity into the review process.

Please note that this change does not impact any of the rest of the Guidelines; only the Theme Unit Tests specifically. And during reviews, Themes should still be checked against the Theme Unit Tests, any conformance issues should be noted as Recommended as part of the review, and Themes will still be required to document any extraordinary design limitations.

As a reminder: when conducting a review, please ensure that Required criteria are clearly stated, separately from recommendations or other comments, to ensure that those required criteria are clearly communicated to the developer. (A bullet list of required items usually helps.)  Reviewers are welcome (and encouraged) to leave other recommendations or constructive feedback for developers, but we need to ensure that developers know exactly what is needed in order for Theme approval.

As always, thank you, all, for your continued contributions!


Guidelines Shouldn’t Fail a Theme

Chip’s great post on Points of Emphasis and a recent discussion about a specific Theme Unit Test guideline (failing themes with long titles that overflow) point to a need to change our attitudes to the theme review guidelines.

If you step away from that specific TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. ticket and look at the bigger picture you’ll see a change is needed to make all WP theme reviews less dogmatic and more pragmatic; not only WP.org directory but also for WP.com, ThemeForest, MOJO, any other marketplace that accepts some submissions and rejects others.

The items in the Theme Unit Test are guidelines not hard and fast rules. Highly recommended and encouraged and we should feature and love and promote the themes that nail them all. Shout from the mountaintops if a themer manages to achieve the full list! Themes that don’t nail them all can sink to the bottom of the list organically because people might end up not liking them as much.

Guidelines shouldn’t cause a theme to fail or be prevented from being in the directory. That should be limited to blockers like licensing, security, and spam/malware. What Chip said.

By letting theme designers choose to implement guidelines in full—or not—you give the power to end users to vote for the best ones by activating them. Instead of keeping out hundreds or thousands of potentially amazing themes that fail the too-strict rules we have now. The themes—and the people behind them—that we lose out on might never come back; and there’s evidence this has happened many times already.

Changing a strict philosophy of enforcing guidelines as rules to encouraging more experimentation and variety will go a long way to remove negative friction from reviews and make the themes in the collection better in the long run.

In summary: let’s enforce the “Points of Emphasis” (security, license, no spam) and leave the rest as recommended guidelines. We absolutely love if you follow them all, but none are blockers to your theme being included in the directory.

#community, #guidelines, #reviews