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

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.

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.

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

Rohit Tripathi 2:41 pm on April 3, 2014

+1 For Everything. Especially, the guideline change related to Screenshots. I hope it goes through.
- Edward Caissie 4:19 pm on April 3, 2014
  
  Aside from maintaining the premise of not allowing any sort of spammy / marketing type images I would be fine with opening the screenshots to something relatively easy to configure at installation provided how to create the screenshot’s “look” is documented in at least the `readme.txt` file … or similar documentation available to the end-user within the theme’s package.
tskk 2:57 pm on April 3, 2014

How much time do we have before recommendation of using 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. turns into requirement?
- Chip Bennett 2:59 pm on April 3, 2014
  
  Who knows? It’s something that may never happen. Right now, we just want to promote it as a best practice.
  
  Is there any particular reason not to want to integrate Theme options 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.? I’m genuinely curious what those reasons might be.
  
  EDITED TO ADD: We made the Settings 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. *recommended* years ago, and have never made any move toward making it *required*.
  - tskk 3:03 pm on April 3, 2014
    
    the left pane is very cramped,
    no framework like OF which has all the controls we need,
    no drag and drop setting/option
    - Chip Bennett 3:06 pm on April 3, 2014
      
      True, the left pane can be a bit cramped – but I think they payoff (real-time preview of the setting change) more than compensates. Also, if you segregate your Theme options into logical sections, it makes the UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. much more manageable.
      
      Almost every control imaginable is built-in to the 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.. Which one(s) are you missing, specifically?
      
      Can you explain the drag-and-drop? I’m not sure what you mean.
      - tskk 3:21 pm on April 3, 2014
        
        The ability to use images in place of radio buttons like in optionsframework, ability to have a vertical accordion like i have in optionsframework. Is it possible to add stand alone text and maybe apply css to that text?
        
        If you see one of the cyberchimp themes, they have a drag and drop option where user can drag page elements around like reordering the site elements.
    - Zulfikar Nore 4:03 pm on April 3, 2014
      
      I think with a little thought the drag and drop for page builders can also be integrated in 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..
      
      My thoughts here are based on the new incoming WidgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. control section which has some drag and drop options for the widgets.
  - tskk 2:08 am on April 4, 2014
    
    Also 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. doesn’t have a reset button, import/export option.
    - Schwarttzy 4:12 am on April 9, 2014
      
      import/export would be sweet for 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.
daveshine (David Decker) 3:39 pm on April 3, 2014
*Tranlation-ready* should totally be REQUIRED!

Why?
Translations are essential, and I never understand why an international used platform like 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 should promote untranslateable themes in the year 2014+ ?!?

*Translation-ready* also means a theme can be customized with another tone/ type/ of the same language, for example, still in English (but use British English, formal tone for business etc.).

Also, to have it as a requirement will improve overall theme code and quality – and especially make them more user-friendly! And not to forget, it will all help prepare for upcoming launch of language packs (that are prepared in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., but “not yet launched” here on .org for themes, plugins).

Standards:
There are already standards all there, for years already:
- load_theme_textdomain()
- load_child_theme_textdomain()
- all the translation functions for strings like __(), _e() plus all the related stuff there…
- using sprintf() and printf() to keep as much markup as possible out of translation strings
- using _x() context translation functions to add context to strings and/ or be better help for translators
I don’t know any reason why *Translation-ready* should not be required for any theme here (and plugins also!)? So, if someone has such a reason for me, I am eager to know what speaks against all that.

As a international developer and user I am fighting the good fight for years already, to get more and more themes, child themes and plugins translateable at all, and moreover to have them in the “standards” (see points above). WordPress.org theme repository should be the leading example in this field!

PLEASE make it a requirement! Thanks so much!

Dave from Germany 🙂
- Chip Bennett 3:55 pm on April 3, 2014
  
  I agree that making it *required* is our end goal. But we have to start somewhere. We have to have an established, objective string-translation standard. Then we have to educate developers how to implement it – and we have to educate reviewers how to evaluate Themes against it. We’re simply not ready for that.
  
  I want to get there. We need to get there. I agree that WPORG-hosted Themes should all be translatable. But we’re simply not at the point that we can make it required, and be able to enforce it fairly and consistently.
- Ulrich 4:55 pm on April 3, 2014
  
  I think it would be great if every theme and 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 were internationalized. From my experience reviewing themes a number of theme developers do not have a deep understanding of PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. so they find it difficult to internationalize the theme. By placing it as a requirement we are increasing the level of entry. Do we really want to do that?
  
  Somehow I think it is a theme developers decision to choose to support i18n or not. Users can show the demand by asking for i18n support.
  
  We did once discuss what is needed for a theme to be allowed to use the translation-ready tag. At the time we decided that all strings had to be internationalized and the 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. should contain the text domain but does not need to include a POT. How far do theme reviewers enforce best practices for creating strings?
- Justin Tadlock 5:01 pm on April 3, 2014
  
  I’m one of the biggest supporters of theme authors internationalizing their themes that you can find. I’ve done this myself for many years. However, I cannot get behind this being a requirement, at least at this point in time. The reason for this is that it is a huge barrier to entry. I probably would’ve never made my first theme if I had to do this.
  
  We need to start with education. I’d also like to see all articles in the Codex and Handbooks that provide code examples with text strings to actually show those strings with the proper functions.
  - Ulrich 10:02 pm on April 3, 2014
    
    “I’d also like to see all articles in the Codex and Handbooks that provide code examples with text strings to actually show those strings with the proper functions.”
    
    This was already discussed: https://make.wordpress.org/polyglots/2013/10/15/hey-hey-polyglotters-i-have-a-question-from/
- Sami Keijonen 5:30 pm on April 3, 2014
  
  I’m with David here. Make it required. This has been in theme/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 development best practice for so long that it should be required. I don’t mind if it makes a little bit harder to get your theme on WP.org. It should be about quality, not quantity.
  
  Do you have data how many new themes are not Tranlation-ready?
- wpweaver 8:02 pm on April 8, 2014
  
  I am 100% for making theme translatable on the front side (visitor view).
  But, as usual, my theme (Weaver II) is on the extreme edge of things.
  
  It has a very complex admin interface, full of long, complex, and technical descriptions. It uses complex HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. and scripts to make the admin user interface work with its hundred of options.
  
  Making this in a translatable form (it has LOTS of direct HTML output) is next to impossible. And this doesn’t even mention how difficult it would be to get technically correct translations.
  
  But for the visitor side, my theme has already been translated to something like 25 languages, and that number is growing.
  
  So – visitor side translation capable – REQUIRE asap.
  admin side translation capable – leave recommended.
Frumph 3:45 pm on April 3, 2014

… no, no and no.

If you want to write up guides and point to them to the designers, go for it.
- daveshine (David Decker) 3:54 pm on April 3, 2014
  
  Yes, sometimes to much guides/ guidelines make things more complicated and could take away some passion…!
  
  However, it’s not only about design here: it’s also about usability, security of code, making stuff translateable, avoiding aggressive marketing in themes etc. Over the years, the experience was some guidelines should be in place.
  - ruphel 12:17 am on April 4, 2014
    
    With David 100% on this one.,make it rquired
Morgan Feeney 3:47 pm on April 3, 2014

Theme options in 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.! The purpose of which is for live preview of your website, including styles, now widgets too, so why exclude any other content which can be edited on the back end from this?

It makes total sense to me, I am a designer and front-end guy and I think it would be of benefit.

if WordPress is to carry on competing on a global scale with new and existing CMS, anything which enables a real-time preview into how the site looks with on-the-fly changes being made only makes it a stronger contender in the long-run.
Zulfikar Nore 4:13 pm on April 3, 2014

+1 on all proposed changes!

The Screenshot issue has been too stringent – allowing for configurable options to be included in the screenshot is a sane proposal.
Justin Tadlock 5:07 pm on April 3, 2014

I still disagree with the requirement for license info to be placed into readme.txt. WordPress itself uses a license.txt file for this. I’d be more supportive of this if we allowed for license info to be placed in either license.txt or readme.txt.
- Emil Uzelac 5:42 pm on April 3, 2014
  Wiki has nice readme.txt example:
  http://en.wikipedia.org/wiki/README
  - README General information
  - AUTHORS Credits
  - THANKS Acknowledgments
  - ChangeLog A detailed changelog, intended for programmers
  - NEWS A basic changelog, intended for users
  - INSTALL Installation instructions
  - COPYING / LICENSE Copyright and licensing information
  - BUGS Known bugs and instructions on reporting new ones
- Chip Bennett 5:55 pm on April 3, 2014
  
  I’m fine with that; I’ll update the post accordingly.
- Catch Themes 3:22 pm on April 5, 2014
  
  Yes I agree with Justin… It should be either readme.txt or license.txt.
Ron 5:23 pm on April 3, 2014

Most of the guidelines seems to be in order but I have to disagree with the Custom Logo being disabled by default. Unlike the favicon, a logo affects the overall design of a theme.

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.

True, but what about one that is not visible? There might not be any benefit to the end user whether a custom logo is enabled or disabled by default but then why make it a requirement?

If the generic logo requirement isn’t good enough then maybe we could even have a standard logo image for every theme with a logo option to use. Maybe a WordPress logo?
- Chip Bennett 5:55 pm on April 3, 2014
  
  You might be misunderstanding what “disabled by default” means. It just means that, if the user configures a logo, then that logo is output; otherwise, if the user does not configure a logo, then no “default” logo is output.
  
  I’d be curious to see an actual case where a “disabled by default” custom logo would adversely impact a Theme’s design.
  - Ron 6:10 pm on April 3, 2014
    
    Yup, that’s exactly how I understood the guideline. It might not be a very big difference but a visible logo helps a user envision the overall look of the theme after he/she either removes or changes it.
    
    My point is, are there actual benefits at all from a custom logo being either enabled or disabled by default that would command it to be a requirement? If there aren’t any then this would just unnecessarily add to the growing set of guidelines.
    - Chip Bennett 6:20 pm on April 3, 2014
      
      Yes, there are actual advantages. A company is very likely to have a pre-defined logo that they would then configure for use with the Theme. But an individual (or even a non-commercial entity or group) likely won’t have a logo. For them, it is detrimental to have an arbitrary image (or worse: an image that says “Logo”) prominently displayed on their site. (Note: it would be equally bad to have an image displaying the Theme name prominently displayed on their site.)
      
      This is not an onerous guideline. It simply means wrapping the logo output in if ( '' != $themename_options['logo'] ) {}.
      - Ron 6:50 pm on April 3, 2014
        
        A company is very likely to have a pre-defined logo.
        An individual (or even a non-commercial entity or group) likely won’t have a logo.
        
        Is this really the case? I think a user, whether intending a theme for company or individual use would decide on what theme to use basing on it’s looks (screenshot & preview). The visibility of a logo and seeing its positioning helps make that decision. I think it’s pretty reasonable to expect a user who chooses a theme that has a logo option, to use one. I think the fact that logos are required to be user-configurable is good enough.
        
        I’m not really that much against it but I just can’t see the guideline as an actual benefit to warrant being a requirement.
        
        Chip Bennett 9:26 pm on April 3, 2014
        
        I doubt that users primarily base their decision on whether or not a Theme supports a custom logo, nor should individuals be barred from using a Theme simply because it outputs a logo, and they don’t have or need one.
        
        The decisions to add this guideline is born out of the numerous instances of logos being problematic during the review/approval process. This guideline actually simplifies things for Theme developers, who no longer have to come up with a “generic/unbranded” logo to output by default (most of the time, Themes have had a Theme-branded default logo, and had to go to the extra effort to create an unbranded logo).
  - Catch Themes 3:26 pm on April 5, 2014
    
    I think the only problem with this will be in Theme Preview. If we have option to make that logo available in preview then there will be no effect on design. For example in Catch Kathmandu theme, I added in generic logo just to show in Theme Review at http://wp-themes.com/catch-kathmandu/
Emil Uzelac 6:20 pm on April 3, 2014

+1 for all @chipbennett!
- alex27 10:34 am on April 4, 2014
  
  I totally agree with Chip on the logo. What good does the fancy custom logo does to the user anyway, when theme authors do not provide source files to customize it (not that I think we should require it).
Codice e Bella 2:47 am on April 4, 2014

I only developed my first theme for the repository about a month ago. While I created a very basic and simple theme to learn the process so that I could start developing themes that weren’t so “basic”, I didn’t think learning to develop it as translation-ready was that difficult. Someone else said it should be about quality, not quantity. Even as a new developer to the theme repository, I would agree with that, and say making it a required practice shouldn’t stop someone from developing new themes for the repository.
mudthemes 6:57 am on April 4, 2014

Screenshot Proposal is brilliant.

To make it more transparent, why not ask theme developers to include the exact method used to achieve the screenshot in readme.txt or link the plugins/widgets used to create it.
Frank Klein 11:47 am on April 4, 2014

Screenshot

I think that the screenshot should reflect the intended use case of the theme, so a blogging theme (like TwentyThirteen) should show the blog index. A theme with a front page template (like TwentyTwelve) could show this specific template.

I’d argue though that themes should always show the front page (whether a blog index or static page). It is okay to have a screenshot that shows user-configurable options already set up. However the screenshot should not contain elements that are dependent on the installation of plugins.

Translation-Ready

I would be in favor of making this a requirement. I agree with Justin Tadlock that this represents a further barrier to entry for theme developers. But I would say that we need to think about the users first and only then about the developers.

With an increasing number of WordPress users that don’t have English as their native language, themes that are not translated are effectively useless. So in this case, we should side with the users and make this a requirement.

I would also add that Internationalization is no longer a mystery or novelty. With the amounts of tutorials and WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. talks on this subject, learning this is not an issue.

Custom Logos

I agree fully with this. Custom logos are an option. As such they should optional.

Licensing information

Having a file (whatever name it has) that contains all the licensing information for the theme is a big help for reviewers. It also makes the life for users easier that want to use themes for their own projects, as they don’t have to worry about finding out what licenses apply to the different elements of a theme.
Devin Price 4:09 pm on April 4, 2014

+1 for all these changes.

I think we should put a note about how to properly enqueue Google fonts as this has come up a lot in my recent reviews. It could also perhaps be somewhat automated: https://github.com/Pross/theme-check/issues/6

I would also love to get more theme support for translations. Perhaps there is a better way to match theme developers who are knowledgeable in this area with developers who wish to learn it?
Catch Themes 3:32 pm on April 5, 2014

+1 for the changes. Ready to work on Theme Review. Will need to adjust some on my themes as well. Thanks 🙂
Scott Smith 2:18 am on April 7, 2014

How should I be escaping Custom CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.? I crawled the internet for a while and wasn’t able to find a helpful bit of advice on this.
- Frank Klein 12:00 pm on April 7, 2014
  
  Id’ say that you can use htmlspecialchars(). Make sure to pass the blogs charset to it along with the appropriate quotes flag: htmlspecialchars( $css, ENT_QUOTES, get_option( ‘blog_charset’ ) );
  - Frank Klein 12:02 pm on April 7, 2014
    
    Forget to say that the documentation for the flags is here: http://docs.php.net/manual/en/function.htmlspecialchars.php
    
    With Custom CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site., you should know what kind of quotes to expect (if any) and then set this accordingly.
Catch Themes 12:49 pm on April 17, 2014

Has this guideline been finalize. Can we use this proposed guidelines while review new themes. WordPress 3.9 is out now. But I don’t see final guidelines.
- Chip Bennett 12:57 pm on April 17, 2014
  
  New Guidelines are typically enforced one month after final release, to allow sufficient time for adoption.
  - Catch Themes 1:21 pm on April 17, 2014
    
    Thanks Chip 🙂