A Guide to Reviewing Themes for the WordPress Theme Repository

Filed in Web DevelopmentTags: Theme Review, Themes, tutorials, WordPress

Thanks in large part to Justin Tadlock's recent blog post, in which he solicited more people to get involved with the WordPress Theme Review Team (WPTRT), we have seen a fantastic, huge influx of new volunteers. Many of these new volunteers have had questions about how to perform a Theme review. Hopefully this guide will help answer those questions.

Getting Started

Test Environment Setup

First things first: review How to Join WPTRT.

WordPress Setup

Ensure that a few WordPress settings are modified in order to facilitate the Theme Unit Tests:

  • Settings -> General: set the Site Title to something fairly long, and set the Tagline to something even longer. These settings will facilitate testing how the Theme handles these values.
  • Settings -> Reading: set "Blog pages show at most" to 5. This setting will ensure that index/archive pagination is triggered.
  • Settings -> Discussion: enable Threaded Comments, at least 3 levels deep. This setting will facilitate testing of Theme comment list styling.
  • Settings -> Discussion: enable Break comments into pages, and set 5 comments per page. This setting will facilitate testing of Theme paginating link markup/styling.
  • Settings -> Media: ensure that no values are set for max width or height of Embedded media. This setting will facilitate testing of the Theme $content_width setting/implementation.
  • Settings -> Permalinks: ensure that a non-default permalink setting is selected, e.g. "Month and name". This setting will facilitate stepping through the Theme Unit Tests.

Next, create at least two Custom Menus:

  • Long Menu: all included Pages
  • Short Menu: a menu of 2-3 Pages

Now, you're ready to be assigned a ticket! Read on for the detailed review process.

Policy Requirements

The first area to review involves some policy requirements, rather than code quality. I verify these before I ever download or install the Theme, by reviewing the appropriate template files using the "SVN" link in the Trac ticket.

License

  • Review the header tags in style.css. Ensure that the License: and LicenseURI: header tags exist, that the indicated license is GPL-compatible, and that the indicated URI is a valid, full-text license.
  • Review the Theme files for bundled fonts or icon sets; if included, verify that the licenses for these bundled resources are GPL-compatible, and explicitly declared by the Theme, either in style.css, readme.txt, or somewhere similarly appropriate.
  • Review other template files, such as footer.php, to ensure that there are no inline comments regarding use restriction, such as prohibiting changing the footer, or requiring a credit link, etc.

Credit Links

  • Review the header tags in style.css. Ensure that Theme URI and Author URI, if used, are valid and appropriate.
  • Review the indicated URLs. Ensure that the sites are appropriate, that they do not sell or promote non-GPL WordPress Themes, and that any license or terms and conditions information does not include non-GPL-compatible content.
  • Review footer.php, sidebar.php, etc. and ensure that the Theme does not include any other inappropriate hard-coded links (sponsor links, SEO links, spam links, etc.). Ensure that all public-facing copyright notices indicate the site name, rather than the Theme name or developer.
  • Review functions.php and ensure that the Theme does not hook in any other inappropriate links or copyright notices.

Theme Name

  • Verify that the Theme name meets naming convention requirements.

Screenshot

  • Verify that screenshot.png is sized appropriately.

Theme Check

Next, install the Theme, and before activating, run Theme Check. Note any Warning or Required notices in the Trac ticket. (Note: for any Theme uploaded since late March 2011, Theme  Check should return no such notices, as they should all be caught by the Theme uploader script. If you notice any, please email the Theme-Reviewers mail list, and indicate what notices you observed.)

You are welcome to note Recommended or Info notices in the Trac ticket, but I generally don't. These notices are more for your reference, as you continue to review the Theme.

For Recommended notices regarding Theme functionality (Post Formats, Post Thumbnails, Navigation Menus, etc.), verify that the Theme does not use a custom implementation. If the Theme does use a custom implementation, note in the Trac ticket that the Theme is required to support the core implementation of the functionality.

Step through each Info notice, and review the Theme template files to determine if the notice is applicable. For example: verify appropriate use of include() vs. get_template_part(); verify appropriateness of hard-coded links; etc.

Code Quality

Now, the review enters the bulk of the requirements in the Theme Review guidelines.

header.php

Review header.php, and verify:

  • All appropriate document head guidelines (valid doctype declaration, properly formed tags (html, head, meta, etc.)
  • Feed links are not hard-coded into the document head
  • No CSS files other than style.css are hard-coded into the document head. (These files must either be enqueued and hooked in appropriately, or added using IE conditional tags.)
  • No scripts or script file links are hard-coded into the document head. (These must be enqueued and hooked in appropriately.)
  • No unnecessary meta tags (WordPress generator tag, SEO meta tags, copyright meta tags, etc.) are hard-coded into the document head.
  • The wp_head() template tag is placed immediately before the closing HTML head tag.

footer.php

Review footer.php, and verify:

  • No scripts or script file links are hard-coded into the footer. (These must be enqueued and hooked in appropriately.)
  • The wp_footer() template tag is placed immediately before the closing HTML body tag.

functions.php

Review functions.php, and verify:

  • All custom Theme functions, constants, classes, global variables, and options are prefixed with theme-slug (or an appropriate variant).
  • Theme Settings are implemented properly:
    • Theme options are added to the database via a single options array, rather than separately
    • Settings page added via add_theme_page() rather than add_menu_page()
    • Settings page capability is edit_theme_options, rather than admin, manage_options, edit_themes, etc.
    • All untrusted data are sanitized/validated upon input into the database, and escaped upon output
    • If the Theme is not using the Settings API:
      • Nonce-checking is performed explicitly
      • $_POST, $_GET, and $_REQUEST data are sanitized/validated upon input into the database, and escaped upon output
  • No core WordPress functions introduced prior to one previous, major WordPress release are wrapped in function_exists() conditionals.

style.css

Verify that all tags listed in the Tags: header tag are appropriate, and that all claimed functionality is included in the Theme.

Theme Template Files

Note which hierarchical template files are used (e.g. single.php, page.php, archive.php, date.php, author.php, category.php, tag.php, taxonomy.php, 404.php, home.php, front-page.php, and search.php), so that you will know which of these to verify when performing the Theme Unit Tests, later.

Review Theme template file names, and ensure that any hierarchical template file name variants (e.g. page-foo.php, category-foo.php, etc.) are included in the Theme documentation, with an explanation for their use.

File Includes

Review Theme template files, make note of any uses of include() or require() and ensure that such use is valid. Verify that:

  • All headers are included via get_header()
  • All footers are included via get_footer()
  • All comments templates are included via comments_template()
  • All sidebars are included using get_sidebar()
  • All template part files are included via get_template_part()
  • Any search form markup is included via get_search_form()
  • Any login form markup is included via wp_login_form()

Theme Unit Tests

Now the review moves on primarily to the requirements in the Theme Unit Tests.

Theme Activation Tests

  • Activate the Theme, and open the site in your browser. Verfiy that Debogger returns no PHP errors, warnings, or notices for index.php.
  • Via Dashboard -> Tools -> Deprecated Calls, verify that Log Deprecated Notices does not return any deprecated function calls or other notices.
    • Note: check the Deprecated Calls log one final time when you complete the review, after you switch back to your default Theme. Sometimes, some notices get thrown when the Theme is deactivated.
  • If the Theme includes a Custom Theme Settings:
    • Load the Settings page, and verify that Debogger returns no PHP errors, warnings, or notices.
    • Save current/default settings, and again verify that Debogger returns no PHP errors, warnings, or notices.
    • Test each Theme Option in turn, and verify that each option can be updated, that the setting is applied properly in the Theme, and that Debogger returns no PHP errors, warnings, or notices.
    • If the Theme Settings page includes a "Reset Defaults" button, reset defaults, and verify that default settings are applied, and that Debogger returns no PHP errors, warnings, or notices.
  • If the Theme supports Custom Image Headers, select a custom header, and verify that it is applied/displayed properly
  • If the Theme supports Custom Backgrounds, select a custom background image or color, and verify that it is applied/displayed properly
  • If the Theme supports Custom Nav Menus:
    • Verify that the default/fallback output renders properly
    • Apply the Short Menu to each theme_location, and verify that the menu renders properly
    • Apply the Long Menu to each theme_location, and verify that the menu renders properly, without breaking the site/menu layout
    • If the Theme has a limitation on number of list items in any theme_location, ensure that such limitation is documented in readme.txt
  • If the Theme adds Custom Widgets, verify that all custom Widgets function as intended, generate no PHP errors, are secure, etc.
  • If the Theme supports Custom Editor Style, verify that the Post editor content renders reasonably similar to the site output
  • If the Theme requires any custom settings or setup, ensure that setup instructions are documented in readme.txt

General Tests

Run the W3C HTML/CSS validator on the Readability Test post (to ensure minimal WordPress-caused validation errors), and note any egregious validation errors, such as:

  • Malformed or improperly closed tags, that cause the page layout to break
  • An exceptional number of HTML or CSS errors

View the site index page, and verify:

  • The screenshot, as seen in the Trac ticket, is a "reasonable facsimile" of the default view of the site
  • The Site Title and Tagline, if displayed, do not break the page layout

Template Page Tests

  • For all included template-hierarchy index pages (index.php, home.php, archive.php, date.php, author.php, category.php, tag.php), verify requirements, as specified.
  • If the Theme includes either a front-page.php or a home.php template file, go to Dashboard -> Settings -> Reading, and set the Front Page to display a Static Page (use any existing Page), and set the Blog Posts index to another Static Page (e.g. "Lorem Ipsum"). Verify requirements, as specified.
  • Trigger the Theme's 404.php page by navigating to a non-existent Page slug (e.g. www.domain.tld/sit-amet). Verify requirements, as specified.
  • Trigger the Theme's search.php page by performing a search (e.g. "lorem ipsum"). Verify requirements, as specified.

Blog Posts Index Page Tests

Return to the Blog Posts index page. Step through the Blog Posts Index Page tests.

Individual Unit Tests

Step through each Blog Post and Static Page, verifying all requirements, as specified. Each unit test should be fairly self-explanatory.

Finishing the Review

At this point, the review is thorough and complete. Summarize your comments in the Trac ticket and close the ticket with the appropriate resolution (or propose a suggested resolution, if you do not have appropriate rights to close the ticket).

Feedback

Comments (Comments are closed)

8 Responses to “A Guide to Reviewing Themes for the WordPress Theme Repository”
  1. Emil says:

    Great resources Chip, super job.

    Cheers,
    Emil

  2. Manish Gori says:

    I agree, perfect for beginners like me..

  3. should read : “the wp_head() function should be placed immediately before the closing HEAD tag”?

  4. I need glasses, please ignore comment

  5. Dear mr. Bennet,
    i would like to say thanks for your job,
    i took your thema in wordpress,i’m
    still working on it.
    Ciao from Venice city (Italy)

  6. Mario Peshev says:

    Another thing I usually test for is different browsers. This might lead to unexpected surprises in the layout part :)

  7. Qamar says:

    Thanks Chip,
    This is an excellent work.

  8. Ryan Hellyer says:

    Thanks for this Chip. Bookmarked for reviewing my own themes with in future!

Trackbacks

  1. WordPress Community Links: WordCamps need more tents edition | WPCandy
  2. Theme submission steps – presentation | WordPress Developer