• Themes are not to use WordPress in their name. For example My WordPress Theme, WordPress AwesomeSauce, andAwesomeSauce for WordPress would not be accepted. After all, this is the WordPress Theme repository.
  • Themes are not to use the term Theme in their name, such as: AwesomeSauce Theme. Same reason as above … it’s a Themerepository.
  • Themes may use the WP acronym in the Theme name, such as WP AwesomeSauce.
• Themes are not to use version-specific, markup-related terms (e.g. HTML5, CSS3, etc.) in their name.
• Themes are not to use related terms (e.g. Blog, Web Log, Template, Skin, etc.) in their name.
• Themes are not to use Theme author/developer credit text in their name. For example AwesomeSauce by John Q. Developer(makes for a much better credit link); or, SEO/SPAM-seeded text, such as: AwesomeSauce by Awesome Free WP Themes (this is just not going to pass).
• Themes are not to use related Theme names (e.g. WP Twenty Eleven, Twenty Eleven WP, The Twenty Eleven, etc.) in their name.

In light of recent discussions, I think this would be a good time to clarify these guidelines. Please discuss below if you have any comments, questions, or feedback related to the Theme Name guidelines.

WordPress

The requirement not to use the term WordPress in a Theme Name should be obvious; all Themes hosted in the directory are WordPress Themes.

Generic Terms

The following Guidelines relate to the use of generic terms:

• Themes are not to use version-specific, markup-related terms (e.g. HTML5, CSS3, etc.) in their name.
• Themes are not to use related terms (e.g. Blog, Web Log, Template, Skin, etc.) in their name.

These are the guidelines that I think are the least articulate, and need clarification.

The intent is to avoid generic terms related to design elements, features/functionality, or intended use of the Theme. Whether that’s markup (HTML5, CSS3), design (responsiveness), features/functionality (photo galleries, jQuery masonry), or intended use (“Tumblogging”, real estate, business), terms related to these aspects are better left to the Theme description and, where applicable, filter tag keywords.

The purpose of a Theme name is to ascribe an identity to the Theme through the uniqueness of that name.  It is perfectly fine to invoke design elements or intended use of the Theme through the Theme Name, but it should be done using a creative/unique term, rather than a generic term. The intent of the related Guidelines here is to emphasize this point, and to help avoid naming conflicts and disagreements that arise from the use of generic terms.

Developer name

As with the WordPress term, I think this one is self-explanatory.

Reserved Core Theme Names

The WordPress Core team has chosen a naming convention to use for the annually updated Theme distributed with core. Thus, it makes sense to ensure that this naming convention is reserved for core.

Rather than making decisions (or creating new Guidelines) on the fly, let’s discuss those questions, and the issue of branding vs. “white labeling” as a whole, here. What I would envision coming out of this discussion would be a clarification of the Guidelines, to indicate more clearly what we’re currently requiring/enforcing, under a “Theme Branding” heading (or similar) that would envelop the existing “Credit Links” requirements.

For example: logos. Some Themes add a “logo” Theme option, but set the default as a text-as-image Theme Name “logo”. This is obvious branding, and obviously an instance where the user would rather have the Theme default to displaying the user’s configured Site Title, rather than a Theme-branded text-as-image “logo”. But a different developer may want to display a generic/arbitrary logo by default, to demonstrate the Theme’s custom logo feature. So: we should discuss where/how we want to draw the line of appropriateness.

In a discussion such as this one, my default position is: with all else equal, which decision is in the best interest of the end user? But it is equally important to consider the needs and interests of developers, as well. Guidelines should not be onerous or unreasonable for developers. I would contend that, when initially activating a Theme – whether on a new site or a site with established content – an end user will not want then to have to go through the Theme to “disable” the demo/branding content. So, I think it is reasonable to require that all default/demo imagery be generic/non-branded/”white-labeled”.

To take a counter example: footer credit links. Should developers be required to make footer credit links user-configurable (i.e. able to be disabled) via Theme option? I don’t think so. We put enough requirements around the form/display of footer credit links to ensure that they are appropriate, that I think requiring them to be user-configurable via Theme option crosses the line into being too onerous. (Consider all the Themes that have no Theme options; should we force developers of those Themes to incorporate all the overhead of Theme options, just for footer credit links?) What might be more reasonable, however, would to to recommend that footer credit links be user-configurable, via Theme option, custom filter, template-part file, etc.

Feel free to discuss from both high and low levels: from principle to guideline. But, please try to avoid the, “but Theme X does this” type of arguments. That we are discussing the need to clarify the Guidelines implies that existing Guidelines have been interpreted differently, resulting in different review comments for different Themes. Our aim here is to find consensus regarding the correct approach to handling these issues, regardless of how these issues have been handled consistently or inconsistently in the past.

• Themes are required to facilitate the use of Child Themes. A “basic” Child Theme (i.e. a style.css with Template header tag and @import() of the Template style.css), when activated, should function exactly as the Theme itself functions.
• Themes are required to include functional and resource files in a manner that facilitates the use of Child Themes:
  • Use get_template_directory_uri() to include functional files, or resources that are not intended to be included in/over-ridden the Child Theme.
  • Use get_stylesheet_directory_uri() to include resources that are intended to be included in/over-ridden by the Child Theme.

Based on discussion on the mail-list, consensus appears to be that facilitating end user use of Child Themes is beneficial, so this discussion is the first step in incorporating Child Theme support into the Guidelines.

Please discuss. Do you agree/disagree that Child Theme support should be added to the Guidelines? Are the above Guidelines sufficient? What should be added/removed/changed? What about pluggable/filterable functions?

• Recommended 4:3 W:H ratio, size 600x450px (2x the previous 300x225px, to account for Retina displays).
• Maximum size: 600x450px
• Should be a “reasonable facsimile” of the Theme after it is initially activated with default options

I think a bit of clarification is in order, with respect to Themes designed to be used with a custom front page (i.e. front-page.php). I think that, in this case, the intent of the guidelines includes discretion to account for the design intent of the Theme. To that end, I would like to clarify that appropriate screenshots include the custom front page (front-page.php) display, even if that display requires the user to configure Settings -> Reading in order to display it.

Bear in mind that the original purpose of this guideline was to prevent undue marketing via the screenshot, either with unavailable “dummy” content displayed, or a screenshot that was a company/Theme logo, or that displayed something other than the Theme itself. A screenshot that displays the Theme’s front-page.php view is nothing like any of those mis-uses of the screenshot, and is a legitimate representation of the Theme.

What are your thoughts? Should the guidelines formally be clarified in this regard?

Edit

I forgot to mention: there is also an open Trac ticket to incorporate functionality to let Themes declare that they are designed to use a static front page, and “opt in” to that configuration as the default. If/when that ticket gets implemented, we’ll need to have this clarification anyway.

http://make.wordpress.org/core/2013/01/07/wordpress-3-6-the-post-formats-ui-feature

If anyone has any particular input into the what/how of improvements/changes to or standardization of Post Formats, please contribute there.

We’ll do our best to stay on top of any proposed changes, so that we can give as much advance notice as possible to Theme developers, for anything that would impact Theme development or the Theme Review guidelines.

Would anyone be opposed if we formally added query_posts() to Theme Check as a required stopper?

To understand why query_posts() is always inherently _doing_it_wrong(), see @nacin‘s WordCamp presentation You Don’t Know Query, and this great WordPress StackExchange answer by @rarst.

In short, if you are creating secondary queries, you should use WP_Query(), and if you’re modifying the main query, you should filter pre_get_posts.

Thoughts?

The 3.5 release has little impact on Themes, and as such will be mostly invisible to Theme developers. One minor change will be support for HiDPI (i.e. “Retina”) screenshots. If there are any other 3.5-related changes that we need to account for, please post in the comments.

Here is the starting point for the discussion regarding changes to the Guidelines:

• Change Theme Screenshot (screenshot.png) maximum dimensions from 300x225px to 600x450px. (Fixed per comment below)
• New guideline under presentation-vs-functionality: Themes must not bundle custom post-content shortcodes
• Change guideline: reduce criticality for Content Sidebar feature from required to recommended. (Themes would still be required to implement core Settings API if Theme incorporates content sidebar feature.)
• Change criticality of add_theme_support( ‘automatic-feed-links’ ) from required to recommended. (Modified per comments below)

Please discuss in the comments, and recommend any additions or changes to these proposed Guidelines revisions.

New WordPress 3.4 Functionality

• Custom Headers/Backgrounds
  • New and deprecated functions are already covered by existing Guidelines. Themes may OPTIONALLY provide backward-compatibility with pre-3.4 handling of custom backgrounds and headers
• Child Themes
  • Child Themes will formally be allowed to be submitted for inclusion in the Theme repository.
  • Child Themes are REQUIRED to use an approved Theme as a Template (i.e. as the Parent Theme)
  • Child Themes are REQUIRED to demonstrate sufficient difference from the Parent Theme to warrant inclusion
  • Stand-alone Themes are REQUIRED to provide basic Child-Theme support, including:
    • Proper use of get_template_directory()/get_template_directory_uri() vs. get_stylesheet_directory()/get_stylesheet_directory_uri()
    • Proper enqueueing of stylesheets, and proper cascading of styles, including no inline styles in the Theme template
• Backward Compatibility
  • Backward compatibility is covered by existing Guidelines. Per existing Guidelines (2 major WP versions required/1 major WP version recommended):
    • Themes MUST NOT support backward-compatibility for more than two major WordPress versions (i.e. 3.2).
    • Themes are RECOMMENDED NOT to support backward-compatibility for more than one major WordPress version (i.e. 3.3).
• Theme Settings and Data Security
  • Themes are RECOMMENDED to incorporate Theme options into the WordPress core Theme customizer.

New Guidelines (REQUIRED)

• Required Hooks and Navigation
  • Add to list of template tags REQUIRED where appropriate: previous_image_link()/next_image_link() (or equivalent)
• Theme Features
  • If implementing a site logo, Themes are REQUIRED to provide user-configuration of the logo via the core custom header feature. (Exception: if incorporating both a site logo and custom header, the custom header is required to support the core custom header feature, and the custom logo is then required to be implemented via custom Theme option.)
• Function Parameters, Filters, and Action Hooks
  • Themes are REQUIRED to use function parameters, filters, and action hooks where appropriate in order to modify content, rather than hard-coding:
    • wp_title: Themes are REQUIRED to modify output via wp_title filter. (Refer to Codex note.)
    • body_class()/post_class():
      • Themes are RECOMMENDED to modify output via filter
        (body_class/post_class)
      • Themes may OPTIONALLY modify output via function parameter
        (body_class( $class )/post_class( $class ))

New Guidelines (RECOMMENDED)

• Code Quality
  • Themes are RECOMMENDED to follow the official WordPress coding standards for all PHP code.
  • Themes are RECOMMENDED to follow the official WordPress CSS coding standards for all CSS.
• Script Enqueueing
  • Themes are RECOMMENDED to enqueue the comment-reply script at the comment_form_before hook
    

    function theme_slug_enqueue_comment_reply_script() {
    	if ( comments_open() && get_option( 'thread_comments' ) ) {
    		wp_enqueue_script( 'comment-reply' );
    	}
    }
    add_action( 'comment_form_before', 'theme_slug_enqueue_comment_reply_script' );

Clarifications

Clarifications to existing guidelines being enforced:

• Presentation vs Functionality
  • Themes are REQUIRED to function as stand-alone code. Themes may OPTIONALLY integrate support for third-party Plugins; however, Themes are REQUIRED to degrade gracefully and to function fully and properly without any such Plugins active.

Feedback

What else should be included? What should be revised? Let us know in the comments.

First, a word on nomenclature. For the purposes of this discussion, and the guidelines, a “Theme framework” is not a stand-alone Theme, but rather a “drop-in” code library used to facilitate Theme development. The following are examples of such Theme frameworks (note: this list is not an endorsement; rather, it constitutes a quick Google search for examples only):

• Carrington Core
• Hybrid Core
• UpThemes Framework
• Options Framework

Note that none of the above examples constitutes a full, stand-alone Theme. Each is a library of code, used to develop a Theme. Such code libraries are different in both nature and purpose from stand-alone Themes that use the term “framework” to refer to an intended use as a Theme to be forked for further development. (Even the Codex conflates the uses of the “Theme framework” terminology in this manner.)

So, to keep the terminology clear, when I refer to “framework”, I mean a drop-in code library, and not a stand-alone “starter” or “base” Theme. In other words, using this definition of “framework”: Hybrid Core is a Theme framework; the Genesis Theme (even though it is called “Genesis Theme Framework”) is not a Theme framework, but rather a stand-alone, base/starter Theme.

Now, on to the Guidelines, which include the following requirement:

Themes are required to use a unique slug as a prefix for anything in the public namespace, including all custom function names, classes, hooks, public/global variables, database entries (Theme options, post custom metadata, etc.)

This guideline applies to forked/derivative Themes. For example, several Twenty Ten and Twenty Eleven derivative Themes get submitted to the repository. We require these Themes to re-namespace their custom functions, hooks, global variables, textdomain, etc.

However, some confusion arises when a Theme uses a framework – i.e. a drop-in code library – to develop the Theme. Should the Theme be required to re-namespace the framework code? Our current thinking is that such a requirement would effectively defeat the purpose of using a Theme framework, and would deter, rather than facilitate, Themes using such frameworks – and, more importantly, keeping the framework updated.

Requiring Themes to re-namespace such framework library code would be analogous to requiring Themes to re-namespace bundled jQuery Plugin libraries. Also, requiring such re-namespacing serves no practical purpose, and would be counter-productive toward one of the Theme Review Team’s long-term desires to have the means/process/infrastructure for vetting/approving such Theme frameworks, in order to facilitate their broader use. If we started requiring Themes to re-namespace the framework library code today, we’d have a mess on our hands in the future, if we one day are able to have vetted/approved versions of those same frameworks.

So, bottom line, TL:DR: forked/derivative stand-alone Themes ARE required to re-namespace; Themes that use framework libraries are NOT required to re-namespace the framework library code.

What are your thoughts?

Welcome to WordPress Themes Trac

There are 161 new tickets waiting for review. 24 themes were reviewed in the last 7 days.

Although right now is the holiday season here in the US, and most of us have been busy getting ready for the just-released WordPress 3.3, that review queue number is extraordinarily high. That number represents a lot of developers awaiting feedback on their Themes, and a lot of end users not benefiting from new and/or updated Themes. Let’s see what we can do to address it!

Revising the Trainee Reviewer Experiment

First things first: the Theme Review Team has been experimenting with a training program for new reviewers. After a few months, it appears that this experiment isn’t working out as intended. New reviewers aren’t getting assigned tickets as quickly as possible, and full reviewers don’t seem to have enough time to follow up on those reviews, provide feedback, and resolve/close the tickets. While we want to provide training for new reviewers, so that we equip our volunteers with the tools and skills necessary to complete Theme reviews, we can’t let that training get in the way of completing Theme reviews.

So, effective immediately, we’re going to try something else: anyone who requests a ticket to review, and then completes their assigned review, will be given full “reviewer” status in Theme-Trac. That means that, once a new reviewer has requested and completed their first ticket, they will then be able to assign themselves tickets, and will be able to resolve/close tickets on their own. An admin reviewer will double-check tickets resolved as “approved”, but otherwise, once you’ve done one review, you’ll be free to review without the burden of any additional oversight.

Where previously we have been slow to “promote” to full reviewer status, and exceedingly slow to remove reviewer privileges, now we will look to be very quick in granting reviewer privileges, and perhaps somewhat quicker than we were previously with removing reviewer privileges, either due to inactivity or poor reviews (mainly, approving Themes that should not be approved).

Revising the Queue Priorities

Second: for a considerably longer period, the Theme Review Team has used a three-tiered priority approach to the review queue:

1. Priority #1: Currently Approved Themes
2. Priority #2: Previously Reviewed, Not-Approved Themes
3. Priority #3: Never-Reviewed Themes

This three-tiered approach has worked fairly well, especially for Themes that have successfully passed the review process, and are currently approved. However, the Theme Review Team has been unable to keep the Priority #2 queue cleared, meaning that new Themes end up waiting weeks (or longer) to get even an initial review.

So, effective immediately, we’re adding a fourth tier to the prioritization, which will become the new #2 priority: tickets that have been in the review queue for longer than two weeks, regardless of previous review/approval status. The new prioritization will be as follows:

1. Priority #1: Currently Approved Themes
2. Priority #2: Tickets Older Than 2 Weeks
3. Priority #3: Previously Reviewed, Not-Approved Themes
4. Priority #4: Never-Reviewed Themes

Hopefully with this change, the oldest tickets will be reviewed in a more timely manner. Our long-term goal will be that this new Priority #2 queue will be – and stay – empty; but for now, it will help ensure that tickets don’t stay in the queue for weeks on end.

Revising Handling of Review-Based Theme Revisions

Currently, once a Theme is reviewed, if the developer revises the Theme to address issues from the review, and then re-submits the Theme, the re-submitted Theme goes to the end of the Previously-Reviewed Themes queue. This process does not encourage or facilitate such review-based Theme revisions. Understandably – especially with the state of the review queue – Theme developers may be discouraged by the process, and may choose never to submit a revision. This outcome helps no one: end users don’t benefit from an approved Theme becoming available, Theme developers don’t benefit from having their Theme hosted in the repository, and the Theme Review Team expends time and effort reviewing a Theme that never ultimately gets approved.

For some time, the Theme Review Team has had an informal policy, subject to the discretion of each reviewer, of allowing a review to be continued on a subsequent ticket, if a revision is submitted in a timely manner. This informal policy has facilitated prompt Theme revision submissions, and has led to more Themes eventually passing Theme review, and being approved.

So, effective immediately, we’re formalizing this policy: any review-based Theme revision that is submitted within two days of the previous review will be assigned to the previous-ticket reviewer, and the review continued on the new ticket. Bear in mind: exercise of this policy will still be at the discretion of each reviewer, and should be considered to be a privilege, based on a good-faith effort on the part of the Theme developer. While most Theme developers will exercise such good-faith effort, I want to make clear that this policy is not a license to use the review process as quality control.

Revising Review Emphasis

The Theme Review Guidelines currently include a requirement for W3C HTML/CSS validation. It has become clear that this requirement is largely a distraction, both to developers and to reviewers. From the beginning, the W3C Validation requirement was intended to be a holistic tool used in the review process, rather than a rigid requirement; however, all too often, reviews have emphasized W3C Validation results – even at the expense of far more important guideline requirements.

So, effective immediately, W3C Validation criticality is being reduced from REQUIRED to RECOMMENDED, and Theme reviewers will no longer make review comments regarding W3C Validation. Theme developers can/should use W3C Validation as a development tool, but it will no longer be part of the review process.

Also, the Theme Review Team has made an effort to ensure that every review is thorough and complete, in order to reduce the number of times any given Theme must go through the submission/review process prior to approval. However, it is clear that this emphasis on thorough reviews has acted to the detriment of performing reviews expeditiously. What was intended to be a service to Theme developers has actually led to more developer frustration, as the review queue continues to grow.

So, effective immediately, the Theme Review Team will no longer emphasize complete and thorough reviews, and will instead close tickets upon observation of any non-trivial issues. Theme developers have always been responsible for knowing and following the Theme Review guidelines. The key take-away on this point: if you have a question, ASK. As much as we would like to walk every developer through the review/approval process, we simply don’t have enough volunteers to spare the time. If you are unsure about a review guideline, or need clarification on a review comment, ASK. Ask on the theme-reviewers mail-list before you submit your Theme. Ask in the review ticket after you submit. We are here to help developers, but will need to rely more on developers to communicate your questions and concerns, so that we can focus more on reviewing/closing tickets.

Summarizing The Changes

Again, here’s what we’re going to be doing differently, effective immediately, to help facilitate Theme reviews:

• Anyone who requests a ticket to review, and then completes their assigned review, will be given full “reviewer” status in Theme-Trac
• We’re adding a fourth tier to the prioritization, which will become the new #2 priority: tickets that have been in the review queue for longer than two weeks, regardless of previous review/approval status
• Any review-based Theme revision that is submitted within two days of the previous review will be assigned to the previous-ticket reviewer, and the review continued on the new ticket
• W3C Validation criticality is being reduced from REQUIRED to RECOMMENDED, and Theme reviewers will no longer make review comments regarding W3C Validation
• The Theme Review Team will no longer emphasize complete and thorough reviews, and will instead close tickets upon observation of any non-trivial issues

I would also like to add a gentle reminder that the Theme Review Team is a 100% volunteer effort. None of the Theme reviewers are paid for our efforts. For almost all of us, Theme reviews take time away from other development work (whether paid or free) – time that we are happy to contribute. That said: while we understand your frustration in waiting for your Theme review to be completed, I would like to make a request: before you email the theme-reviewers mail-list asking when your Theme will be reviewed, post a comment to the current Trac Ticket Review Request Queue, and ask to be assigned a ticket of your own to review. This request is not a pay-for-play scheme, and no tickets or developers are given special treatment for participating in Theme reviews; rather, the more people we have reviewing Themes, the faster the review queue will get processed. (And as a bonus: you’ll learn more than you might otherwise imagine about what is required to pass the review process successfully.)

Remember: in the end, our entire effort is all about ensuring that WordPress end users have the best-possible Themes available for use.

If you have any other suggestions for how we can improve the process, please let us know – either in the comments, or via the theme-reviewers mail list.