The following changes to the Theme Review Guidelines are being issued for public review and comment. All comments and feedback are welcome and encouraged.
The changes will be finalized when or shortly after WordPress 3.1 is released, and will be made effective one month after the release date of WordPress 3.1.
New WordPress 3.1 Features
The following guidelines will be implemented for new features introduced in WordPress 3.1:
- Post Formats
- Themes may optionally to support Post Formats.
- Themes may optionally implement layout and/or style changes for any, all, or none of the standard Post Format types.
- Unless an extension API is implemented in core, Themes are required not to implement a custom extension for Post Format types (e.g. “hacking” the core Post Format type list to add custom types, such as “code”).
- Custom Post Type Index Pages: if Themes include Custom Post Type Index Pages, they are required to provide Theme documentation to explain their usage
- Admin Bar: Themes should be aware of any potential aesthetic impact of the Admin Bar
Previous “Draft” Guidelines
The following guidelines revisions, previously listed as “draft”, are now final:
- Site Information Template Tags: the correct template tags must now be used where appropriate (home_url(), site_url()
- WordPress-generated CSS classes: definitions for .sticky and .bypostauthor are now required
- Guidelines for optional additional footer credit links
Other Changes to Guidelines
The following changes will also be made to the Guidelines:
- License Header Tags:
- Themes are required to add License: and License URI: header tags to style.css
- Translation and Custom Theme Function/Option Names:
- Themes are required to use theme-slug as the Theme’s translation namespace, and as a prefix for all custom Theme functions and options
- Theme Documentation:
- Themes are recommended to include a readme.txt file, using Plugin readme.txt markdown.
- In lieu of a readme.txt file, Themes are recommended to include a changelog, indicating version-to-version Theme changes.
- TimThumb:
- Themes are required not to use TimThumb solely as a replacement for core Post Thumbnail functionality.
- Any use of TimThumb outside of this requirement will be evaluated on a case-by-case basis.
- Up-Sell Themes:
- Up-sell Themes may be subjected to more rigorous or additional Theme-Review requirements, at the discretion of the Theme Review Team
- Favicons:
- Themes are recommended not to implement custom favicon functionality.
- If implemented, favicon functionality is required to be opt-in, and disabled by default.
- If implemented, favicon functionality is required to support user-defined favicon images
Ian Stewart, 
Justin Tadlock 5:24 am on November 16, 2010 Permalink
CSS Classes:
I’m not in favor of requiring CSS definitions that don’t affect functionality. Some classes must always be styled appropriately such as
alignleft,alignright, andaligncenter. Other CSS classes should be considered tools that theme authors can take advantage of to create nicer themes. We shouldn’t be dictating which style rules are required for use. And, if we do make the decision to require these, how would one determine whether something is sufficiently styled enough to make it through the review process?Just because a post is sticky doesn’t mean it needs a custom style. The sticky feature in and of itself is to add a post at the top of the posts list. Whether it’s designed to our liking shouldn’t really concern us unless it negatively impacts functionality.
The
bypostauthorclass is another style choice. Personally, I think it’s a great addition to themes, but it’s still about design.I do think we should be strongly recommending the use of these classes though.
Post Formats
You know I’ve got things to say about post formats.
If one wants to style/format a certain kind of post a specific way, it shouldn’t be required to use the core post formats feature. Below are some reasons why.
Reason #1:
I’ve already had tons of requests from theme users to allow for personal customization of post formats. I can get behind the idea that the theme itself shouldn’t add in custom formats. Personally, I wouldn’t want to do that anyway. Post formats are about standardization and portability. There wouldn’t be too much benefit in my themes having a non-standard format.
However, making it possible for my theme users to extend the feature for their own sites shouldn’t be frowned upon. I can’t simply tell them to go build a custom taxonomy. I can make it extremely easy for them and let them copy/paste a few lines of code to get the feature they want.
This is the biggest reason I’ve argued for custom post formats. I don’t much care if themes add custom formats or not.
Reason #2:
Let’s suppose a theme dev has the “aside” (supported in core) and the “audio” (not supported in core) formats. Right now, the guidelines would require him to use the built-in post formats feature for “aside.” However, the guidelines would disallow the him from using the “audio” format. So, the developer would be forced to use a tag/category/tax to style the “audio” format but still have to use post formats for the “aside” format.
This would make for a horrible user experience. It would confuse users because they’d have to perform different actions to do the same thing. Consistency is more important here. The theme developer should at least be able to register a custom taxonomy or use a preexisting taxonomy to make for a consistent user experience.
Reason #3:
Andrew Nacin has already stated that a theme dev has the option of doing it better.
http://twitter.com/nacin/status/2812540635578368
Chip Bennett 2:26 pm on November 16, 2010 Permalink
Justin,
Great points, all! Just to clarify:
Regarding WordPress-Generated CSS Classes:
For .sticky and .bypostauthor, a *blank* definition will be accepted. We certainly don’t want to dictate to Theme devs regarding truly stylistic/aesthetic design decisions. But we *do* want the Theme dev to make a conscious decision regarding the WordPress-generated CSS classes. If that decision is, “I know these two classes exist, but for the purposes of this Theme, they aren’t getting any special styling”, that’s perfectly fine.
(This is the same way we treat caption/gallery CSS classes, by the way..)
Regarding Post Formats:
I think that, in order to be consistent (see, e.g. handling of Post Thumbnails), we absolutely have to require support for core Post Formats implementation when a Theme adds such a custom-post-format feature. The narrow scope here, of course, is Themes like TwentyTen or Matala that output the Loop differently depending on a specific category, such as “Gallery” or “Aside”.
Given that we’re also only discussing Themes hosted by the Repository, the question of what users can and cannot do to modify their own Themes for their own personal use isn’t all that relevant. The point is that, for all current features, for Repository-hosted Themes, support of core implementation of those features is required if the feature is included in the Theme.
*Personally*, I agree with your stance regarding extensibility of Post Formats. But if I were to develop a Theme that custom-extended the Post Format types for my own use, such Theme wouldn’t be appropriate to be hosted in the Repository.
Providing instruction to users for how to extend Post Format types in their own Themes? Well now, that’s another matter entirely.
(It’s also well outside the purvey of the Theme Review Team…)
Justin Tadlock 6:14 am on November 19, 2010 Permalink
Hooray! My test comment went through this time!
This is my fourth reply to this topic, but I didn’t save the last two when they didn’t go through. So, I’ll try to break down my thoughts.
I want to make sure we understand the full scope of what post formats should be used for before making any decisions. I believe some clarification by Nacin would help in determining how we should handle post formats within the review process.
—
What I’d like to do with my themes is include a feature called “Post Whatevers” (temporary name). This would be a separate taxonomy from the
post_formattaxonomy. This feature would work in basically the same way as core’s post formats as far as the UI and functions go. It’s purpose would be threefold:Provide a way for users to create custom “whatevers” for their sites in much the same was as post formats. But, they’d be custom and wouldn’t require a user learning how to create a taxonomy.
Allow this feature to fall back to post formats when necessary and integrate with the core post formats when the “whatever” is in the official list of formats.
Create themes that have specific “whatevers” (yes, non-standard and non-portable). For example, I might want to create a photoblog theme that has the image, gallery, and slideshow post “whatevers.”
I would think this falls outside the scope of the post format part of theme reviews. While “post whatevers” is a similar feature, the theme would most definitely not be using the post formats feature from WordPress. It would be using its own taxonomy.
This is the route I plan to blog about, share code for, and encourage other theme authors to take if they want something similar to post formats but need the ability to use this type of functionality in other ways. I believe it is the best approach to take while keeping a distinction between the core feature and theme-specific feature.
I just wanted to run the idea by everyone so that everyone would have an opportunity to weigh in on what they’d like to see from such a feature and to keep it safe for the theme repository.
Chip Bennett 1:24 pm on November 19, 2010 Permalink
Justin,
I think the key point in your example is that you’re creating a custom taxonomy, not attempting to extend Post Formats. So, I don’t see any real issue with what you want to do.
Justin Tadlock 7:32 am on December 12, 2010 Permalink
We also need to make sure reviewers are aware that themes can filter
embed_defaultsas opposed to setting$content_width, especially in themes with dynamic widths.cais 4:29 pm on December 12, 2010 Permalink
A good point to consider, perhaps the uploader/theme-check should be testing for this alternative method as well?
pross 7:41 pm on December 12, 2010 Permalink
Added
http://bit.ly/e6fNcm
Ian Stewart 5:53 pm on December 30, 2010 Permalink
I would leave
LicenseandLicense URItags as recommended (it seems a little redundant for themes that ship with a license) along with.bypostauthorstyling. Encouraging of awareness of that class is great but doing so by requiring an empty selector seems odd.Everything else: Looks good to me!
Chip Bennett 6:25 pm on December 30, 2010 Permalink
The problem is that a license, alone, may not be sufficient. For example, all of the following are different:
– “GPL”
– “GPLv2″
– “GPLv2 (or newer)”
– “GPLv2 (but not newer)”
The header tags ensure that the licensing intent of the Theme developer is explicit.
Ian Stewart 6:11 pm on January 5, 2011 Permalink
A license alone is sufficient if it’s explicit then? I don’t think a stylesheet header could make an included license more explicit. Those licenses, they’re pretty explicit.
Chip Bennett 7:25 pm on January 5, 2011 Permalink
Two issues:
1) License text != a copyright statement, and a copyright statement should declare the license.
2) Including full-text GPLv2: how do you know if the license is GPL, GPLv2, GPLv2 (or newer), or GPLv2 (but not newer), unless the copyright statement explicitly declares the author’s intent?
Ian Stewart 5:38 am on January 7, 2011 Permalink
“How do you know if the license is GPL?” By looking at the license.txt.
Lance Willett 6:04 pm on December 30, 2010 Permalink
What about checking for an included license.txt file? I think having either one or the other should be sufficient.
Chip Bennett 6:26 pm on December 30, 2010 Permalink
See my response to Ian, above.
(Also, I think there is benefit in establishing a “de facto” standard, especially with respect to license disclosure.)
Lance Willett 6:31 pm on December 30, 2010 Permalink
I don’t see a reply to Ian. ??
Lance Willett 6:37 pm on December 30, 2010 Permalink
Oh, I see it now.