Tag Archives: Guidelines

Chip Bennett 8:05 pm on April 7, 2014
Tags: Guidelines, ,   

How To Ensure Your Ticket Passes Final Approval Audit

Over the past couple of months, the number of approved tickets that have been reopened due to issues found during final-approval audit has declined, but many still get reopened. As a team, we want to ensure that tickets get approved (so that new Themes get added to the directory, and into the hands of end users), and we want reviewers to be able to take advantage of the incentive program.

So I want to step through the things I check when performing a final review audit. We’re looking for some high-level and/or high-impact things that would cause problems for end users:

Overall File Structure

  • Does the Theme look like it is derived from a common Theme (Underscores, Twenty Ten-Fourteen, etc.)? Are there included functional files that I’ll need to check. Are there asset folders (fonts, scripts, etc.) that I’ll need to check?

style.css

  • Check ThemeURI and AuthorURI. Are they appropriate?
  • If ThemeURI or AuthorURI reference commercial Themes, are those Themes sold as 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?
  • If the Theme appears to be derived, does it include a proper derivative-work copyright/license attribution?

readme.txt

  • If the Theme has bundled resources/assets, are they listed in the readme with copyright/license attribution, or will I need to check file headers?
  • Is license for all bundled resources GPL or GPL-compatible?

header.php

  • Are Theme options properly escaped on output?
  • Is favicon, if used, disabled by default?
  • Does the TITLE tag include anything other than the call to wp_title()?
  • Does wp_nav_menu() reference theme_location, and not menu?
  • Are any stylesheet or script links output instead of being properly enqueued

footer.php

  • Does the Theme only use one credit link? Is that credit link exactly ThemeURI or AuthorURI, with no SEO-seeding of link text, title attribute, etc.?
  • Are any footer scripts output instead of being enqueued properly?

index.php

  • Does template markup look generally appropriate?

Front/Home Page Templates

  • Does the Theme have front-page.php? If so, is it used properly? Does it account for both a static page and the blog posts index as site front page?
  • Does the Theme have home.php? If so, is it used properly as the default blog posts index template?
  • Does the Theme have any custom page templates intended to be used as either front-page.php or home.php?

comments.php

  • Does the Theme properly output wp_list_comments() for the comments list?
  • Does the Theme properly output comment_form() for the comment reply form, rather than hard-coding the form?

page.php

  • Does the page template properly call comments_template()?

functions.php

  • Are all functions and other things in the public namespace properly prefixed?
  • Is all functional output properly wrapped in callbacks and hooked into appropriate actions?
  • Is any of the functionality 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 territory?
  • Does any of the functionality replicate coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. functionality?
  • Does the Theme use Theme options? Are they handled properly (single DB entry, proper settings page, sanitized on input, etc.)?
  • Do any of the Theme options replicate core options?

This list comprises 99% of what I look for in an audit, and accounts for the vast majority of issues encountered that require reopening tickets. So, if you verify these things before resolving the ticket as “approved”, the chances that your ticket will get reopened will go down considerably.

(Note: @emiluzelac may have other things to add to the list, for things he checks during an audit.)

#guidelines, #review-incentive, #review-process

Chip Bennett 2:53 pm on April 3, 2014
Tags: Guidelines   

Discussion: Theme Activation Standards

Currently, we are proposing a change to the Guidelines that would blanket-prohibit Themes from adding admin notices, redirects, or other similar functionality on Theme activation. The intent of the Guideline is to curtail the proliferation of nuisance/obtrusive Theme marketing in the user’s Admin.

In the vast majority of cases, such activation functionality should not be needed. Themes are required to use add_theme_page() to add a Settings page, which ensures that end users can always find the Theme’s settings page under the Appearance admin menu. The new requirement for sane defaults will ensure that Themes will always work “out of the box”, at least at a baseline (i.e. no-broken-sites) level. The recommendation for Themes to hook settings into 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. will help ensure that end users can visually preview Theme settings changes via the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Customizer (Appearance -> Customize). And the Contextual Help APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. ensures that Theme developers can add as much rich-text setup/configuration detail as necessary.

That said, there is still room for appropriate, standardized admin interventions on Theme activation. If we can agree on a consensus for standard admin interventions, then the Guidelines could reflect that consensus, and reviewers would have an objective standard to use when reviewing Themes.

So, let’s discuss. What’s appropriate? What isn’t? How can we define appropriateness objectively?

#guidelines

Chip Bennett 2:35 pm on April 3, 2014
Tags: Guidelines   

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

Screenshot

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.

Translation-Ready

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.

Required

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.

Recommended

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.

Translation

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.

Discuss

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

#guidelines

Chip Bennett 2:28 pm on February 7, 2014
Tags: Guidelines   

WordPress 3.9 Guidelines Revisions Proposal

It’s just about that time again, with the WordPress 3.9 release 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:

Required

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.

Recommended

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.

Translation

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.

Discuss

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

#guidelines

Chip Bennett 4:14 pm on November 18, 2013
Tags: , Guidelines   

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