WordPress.org

Ready to get started?Download WordPress

Theme Review Team

Tagged: Guidelines Toggle Comment Threads | Keyboard Shortcuts

  • Chip Bennett 1:22 am on July 9, 2014 Permalink | Log in to leave a Comment
    Tags: Guidelines, sane defaults, , Theme Mods API   

    Using Sane Defaults in Themes 

    With the release of WordPress 3.9, one of the changes to the Theme Review Guidelines is that Themes must use sane defaults. That means that Themes must not write default setting values to the database. For many Themes, this may seem like a major change; but it doesn’t have to be. This post will step through a few ways to implement sane defaults.

    Portability/DRY

    To make this method easier, put all of your defaults inside a function:

    function themeslug_get_option_defaults() {
    	$defaults = array(
    		'option_1' => 'value_1',
    		'option_2' => 'value_2',
    		'option_3' => 'value_3'
    	);
    	return apply_filters( 'themeslug_option_defaults', $defaults );
    }
    

    (Note: by making the return valuable filterable, the Theme defaults can be easily overridden by a Child Theme or Plugin.)

    We’ll make use of this function later.

    Options API

    Most Themes use the Options API, and will use get_option() to put Theme settings into a global:

    $themeslug_options = get_option( 'theme_themeslug_options' );
    

    Knowing that this get_option() caall will return FALSE if the option has not yet been saved to the database, Theme developers have taken to saving default values to the database as part of Theme initialization, like so:

    if ( false == get_option( 'theme_themeslug_options' ) ) {
    	update_option( 'theme_themeslug_options', themeslug_get_option_defaults() );
    }
    $themeslug_options = get_option( 'theme_themeslug_options' );
    

    But this is entirely unnecessary. And everything needed to implement a better solution already exists.

    As a first step, consider that get_option() includes a second parameter, which specifies the default value to return, if nothing is returned from the database:

    get_option( $name, $default );
    

    So, the simplest solution is merely to tell get_option() to return the defaults, using the function we previously defined:

    $themeslug_options = get_option( 'theme_themeslug_options', themeslug_get_option_defaults() );
    

    This works, but isn’t perfect. It will return the Theme-defined defaults if the user hasn’t saved settings to the databse. But if later versions of the Theme add, remove, or change options, this might break, since the return value is either/or: either the database-saved setting, or else the defaults. So, if the user saves settings, and then a new setting is added in a later Theme version, the new setting value won’t be included in $themeslug_options unless/until the user saves settings again.

    The solution is to merge the arrays, rather than to return one or the other. WordPress has a core function specifically for this purpose: wp_parse_args(), which will use the settings array, and “fill in the blanks” with the defaults array:

    wp_parse_args( $settings, $defaults );

    Caveat: bearing in mind that wp_parse_args() expects both parameters to be arrays, and knowing that get_option() returns FALSE by default, be sure to specify get_option() returns an empty array by default: get_option( ‘theme_themeslug_options’, array() ); otherwise, wp_parse_args() will (might – see note below) choke if the user hasn’t saved settings to the database.

    The construct will look something like this:

    $themeslug_options = wp_parse_args( 
        get_option( 'theme_themeslug_options', array() ), 
        themeslug_get_option_defaults() 
    );
    

    This is perhaps the simplest, most elegant way to implement sane defaults.

    (Note: according to Otto, passing an empty arrayy() as the second parameter to get_option() isn’t necessary. In his words: “The wp_parse_args() function checks for the first parameter to be an object or an array. If it’s neither, then it calls wp_parse_str on it, because it can take a GET URL-like array of parameters too. The wp_parse_str() function calls PHP’s parse_str on it, and does a deep strip_slashes if magic quotes is on, then filters the result. So, because false maps to the empty string, parse_str will return an empty array for it, so passing false to wp_parse_args should be A-OK and probably has been like that for a very long time. Doesn’t hurt to add the empty array(), but doesn’t really change anything.” YMMV.)

    Theme Modification API

    Using the Theme Modification API (get_theme_mod()/get_theme_mods()) is fairly similar.

    An individual setting can be called via:

    get_theme_mod( $name, $default );
    

    But perhaps more useful, all settings can be called via:

    $themeslug_options = get_theme_mods();
    

    Since get_theme_mods() returns an array, you can use the same technique as with Options API settings:

    $themeslug_options = wp_parse_args( 
        get_theme_mods(), 
        themeslug_get_option_defaults() 
    );
    

    Portability/DRY (Part 2)

    To be able to use this method throughout the Theme, wrap the wp_parse_args() call inside a function:

    function themeslug_get_options() {
        // Options API
        return wp_parse_args( 
            get_option( 'theme_themeslug_options', array() ), 
            themeslug_get_option_defaults() 
        );
        // Theme Mods API:
        /*
        return wp_parse_args( 
            get_theme_mods(), 
            themeslug_get_option_defaults() 
        );
        */
    }
    

    Then, wherever you need access to Theme options:

    $themeslug_options = themeslug_get_options();
    

    From there, you can globalize $themeslug_options, or cache/transient it, etc. When you need to add a new option, simply add the new option default to the defaults array, and the Theme will handle it automatically.

     
    • Justin Tadlock 2:05 am on July 9, 2014 Permalink | Log in to Reply

      No need for the custom filter hook there on the defaults. Child theme authors can simply filter 'default_option_' . $option if they need to overwrite this.

      • Chip Bennett 12:32 pm on July 9, 2014 Permalink | Log in to Reply

        But that only works if the option is not yet set in the database, right? In which case, it’s a bit more fragile, and wouldn’t work in the case of a Theme (or Child Theme) adding a new option in a later version of the Theme.

  • Chip Bennett 8:05 pm on April 7, 2014 Permalink
    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 GPL-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 Plugin territory?
    • Does any of the functionality replicate core 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.)

     
    • ruphel 9:16 pm on April 7, 2014 Permalink

      Thanks for the checklist Chip

    • Emil Uzelac 11:47 pm on April 7, 2014 Permalink

      My process is very similar to @chipbennett and there is nothing more to add.

      I would like to say that rushing through reviews will most definitely resolve getting your ticket reopened. Take your time and you will be golden.

      Your time and efforts are greatly appreciated!

      For some weird reason, my post got published 4 times, sorry about that.

      • Rohit Tripathi 5:35 pm on April 8, 2014 Permalink

        One thing I would like to Add on behalf of @emiluzelac

        Make sure the themes have correctly spelt “WordPress”, with W & P in captals. I have seen this as a reason in many re-opened tickets.

        :P :)

    • ThemeZee 7:28 am on April 8, 2014 Permalink

      “Does the Theme have any custom page templates intended to be used as either front-page.php or home.php?”

      Does this mean we are not allowed to use for example template-homepage.php for a custom front page template, but have to use front-page.php instead ?

      • Justin Tadlock 3:10 pm on April 9, 2014 Permalink

        home.php and front-page.php have very specific meanings in WP. They should only be used when they’re meant to be used. template-example.php, even if intended to be used on the front page, can also be used if the template can be used with any page.

        Personally, I prefer that devs make a custom page template that’s usable on any page. It offers more flexibility for users.

        • Chip Bennett 3:22 pm on April 9, 2014 Permalink

          Intent is important here. If it’s obviously intended as the site front page template, then it should be `front-page.php`. If the developer doesn’t necessarily intend for it to be the site front page, then call it a “featured content” template (or something similar), and name it `template-featured.php` (or whatever).

    • Jose Castaneda 11:25 pm on April 8, 2014 Permalink

      One of the things I often look for are hooks and filters. I’ve seen a few themes that register meta boxes and some that add post types. It just depends on how they are being used ( though post types should really be avoided in themes ).

      One thing I’ve learned is using the command line to my advantage and using grep to find all the add_action/add_filter calls a theme uses.

    • PageLines 12:30 pm on April 9, 2014 Permalink

      Thanks for the checklist guys!

  • Chip Bennett 2:53 pm on April 3, 2014 Permalink | Log in to leave a Comment
    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 Customizer will help ensure that end users can visually preview Theme settings changes via the core Customizer (Appearance -> Customize). And the Contextual Help API 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?

     
    • Han 3:28 pm on April 3, 2014 Permalink | Log in to Reply

      How about adding admin notice about important changes of the new version? For example when we move the header and footer script, or custom css feature from theme to a plugin.

    • mudthemes 7:04 am on April 4, 2014 Permalink | Log in to Reply

      Even if the theme redirects the user after activation, the redirect must be to a page where only the documentation regarding the theme configuration is written.

      • eminozlem 5:51 pm on April 4, 2014 Permalink | Log in to Reply

        I think the extent may be defined with two rules a.) The redirected page should be theme’s page (most likely options page or documentation help page) b.) The page should be a related page and not advertising purpose page. Just like the same in many rules such as author & theme uri etc.

    • eminozlem 9:16 am on April 4, 2014 Permalink | Log in to Reply

      I don’t understand what’s the big deal with redirection on activation. It’s essential for themes with Option Framework that the options are initially saved for the theme to properly function.
      If you put your mind to it you can use anything out of its intended purposes so I think it’s not fair to punish everyone else because of the aggresive advertisers by prohibiting all kinds of redirecting / notice boxes that could otherwise prove useful.

      Semi OT: You mentioned sth. about the screenshot. I totally agree with that, screenshot guidelines shouldnt be that restrictive. After all, no theme ever really does look like the demo out-of-the-box. Screenshots should be allowed to display what theme might look like with proper modifications and / or content.
      Also I dont see any harm including other material in screenshot (like theme options). I mean some themes provide 4 theme options, others a hundred. It’d be eye-catching and easier for the user to spot the one for them if other aspects are allowed in the screenshot.

      • Chip Bennett 2:23 pm on April 4, 2014 Permalink | Log in to Reply

        Its essential for themes with Option Framework that the options are initially saved for the theme to properly function.

        This statement is untrue. Refer back to the Sane Defaults requirement. Properly implemented Theme options work out of the box, using developer-determined sane defaults, without any user configuration required. Themes that “break” if the user doesn’t configure Theme options have not properly implemented those Theme options.

        If you put your mind to it you can use anything out of its intended purposes so I think its not fair to punish everyone else because of the aggresive advertisers by prohibiting all kinds of redirecting / notice boxes that could otherwise prove useful.

        I do agree, which is why I’ve linked to a separate discussion, so that we can work out some meaningful standards/guidelines.

      • Chip Bennett 3:02 pm on April 4, 2014 Permalink | Log in to Reply

        It’s essential for themes with Option Framework that the options are initially saved for the theme to properly function.

        This statement is untrue. Refer back to the Sane Defaults requirement. Properly implemented Theme options work out of the box, using developer-determined sane defaults, without any user configuration required. Themes that “break” if the user doesn’t configure Theme options have not properly implemented those Theme options.

        If you put your mind to it you can use anything out of its intended purposes so I think it’s not fair to punish everyone else because of the aggresive advertisers by prohibiting all kinds of redirecting / notice boxes that could otherwise prove useful.

        I do agree, which is why I’ve linked to a separate discussion, so that we can work out some meaningful standards/guidelines. Please provide feedback there.

    • tskk 2:35 pm on April 4, 2014 Permalink | Log in to Reply

      I have opposed banning redirection in earlier discussion too, taking the user back to themes page after activation is meaningless, doesn’t serve any purpose, they have to click on theme options link and go select options anyway to get the best out of the theme. Wasting their time and effort is no good.

      Redirecting to theme options should be allowed.

      • Chip Bennett 3:07 pm on April 4, 2014 Permalink | Log in to Reply

        I disagree that user configuration of Theme options should be necessary. That’s partly why we’re adding a requirement for Sane Defaults. Users should know where to find the Theme Settings page should they choose to modify any of the defaults; users should not be forced to deal with settings configuration out-of-the-box.

        Theme-activation redirection UX is something that should be defined and handled by core, IMHO.

      • Frank Klein 3:21 pm on April 4, 2014 Permalink | Log in to Reply

        I disagree with this.

        When a user installs a theme, the experience should be the same, no matter what theme he just installed. Forcing the user to visit another screen without any action from his part makes the experience very confusing, especially if it doesn’t happen that way consistently.

        Imagine that you are a user. You found this great theme, installed it and activated it. The last thing you want to see is an options panel. You want to see how your site looks with this theme applied!

        Is the current theme activation experience as good as it can be? Probably not, but the Core team has been working on this, and they will continue to iterate on it. We should let Core handle this, because it is part of the core experience of WordPress.

        Themes should look good without having to configure options. Nobody likes setting up something, it is boring and often complicated.

        Also if a user can’t figure out quickly how to get a free theme to look like he wants, he’ll either post a support forum message or just download another theme. Either way that is not the outcome you want to achieve.

    • Devin Price 4:02 pm on April 4, 2014 Permalink | Log in to Reply

      I don’t think we should do a blanket-prohibition of admin notices. I am using two in the latest version of Portfolio Press if users are upgrading (so, actually, re-activation). One is a notice about important updates in the version, along with a link to a post about them. A second notifies users that they should update their Reading Settings. I think room should be left in the theme review guidelines for situations like this.

      I agree that upsell and marketing links should not be allowed on activation.

      I agree that notices about an option panel do not need to be displayed on activation. Users are becoming more aware about the “Customize” link. Good theme documentation can also help educate users.

      @eminozlem, Chip is absolutely right about defaults in Options Framework. You should pass a default when you call an option, e.g. of_get_option( ‘my-option’, ‘default’ ), if the theme requires something other than “false” as the reply if the option is not set. Does that make sense? Happy to explain more if needed: http://wptheming.com/contact

      • eminozlem 9:13 pm on April 4, 2014 Permalink | Log in to Reply

        Sure, my theme with OF does work defaults. But there are other specific reasons my implementation of the theme is better with an initial redirect (refresh) on activation.
        I agree with notices.The point is, no matter what the case is, be that notice, redirection, prompt or whatever, I think all should be allowed as long as it’s used in good faith and not in an abusive manner for marketing purposes.

    • @mercime 2:50 am on April 5, 2014 Permalink | Log in to Reply

      +1 blanket-prohibit Themes from adding admin notices, redirects, or other similar functionality on Theme activation.

    • CyberChimps 6:13 am on April 8, 2014 Permalink | Log in to Reply

      We’re strongly opposed to banning all theme activation notices.

      Some kind of default activation notice is required to alert users of a successful activation and what to do next.

      A better solution would be to have a default activation notice similar to what we’ve built into Responsive that directs users to theme options and documentation.

      In a perfect world, we’d all love if a theme just worked out of the box, but the truth is users need a help in knowing what the next step is to configure their website, and some customization will always be required, and the Customizer does not include all use cases yet.

      When .org forced us to removed redirects in our themes we saw significant increases in theme abandonment, and increased support from people who could not locate the theme options. Adding a customize button to the wp-admin bar is an illogical UI progression that most users don’t follow.

      Also, what about notices for companion plugins? Does this proposal intend to ban those as well?

      • Frank Klein 6:55 pm on April 8, 2014 Permalink | Log in to Reply

        TGM Plugin Activation notices or similar are not prohibited by this guideline.

        The Customizer has been introduced a while ago, and users definitely are getting used to it. Having to go to a separate options page to configure the front end of your website is more illogical than a contextually relevant and prominent link to the Customizer.

        I agree that there will always be users that struggle with setting up a theme, and we should help those. But I think that overly complicated themes are more to blame than the banning of admin notices or redirects.

        Instead of every theme shop rolling their own, we should use the feedback and experiences made to develop a Core proposal that will alleviate some of these pain points.

        • CyberChimps 12:21 am on April 17, 2014 Permalink | Log in to Reply

          The Customizer is fine for front end settings, but what about template configurations? Layouts?

          The Customizer is a great tool, but not an end to theme options.

          We would love standardized ways of addressing these pain points, which is why we would prefer if admin notices aren’t banned until a solution is actually in place.

      • Emil Uzelac 4:13 am on April 14, 2014 Permalink | Log in to Reply

        Companion plugins are excluded from the get-go and proposal does not affect them.

        Please note that @chipbennett was asking and not making solo decisions here, otherwise this post would not even exist.

        What is the best way to handle the activation and can we standardize?

        Emil

    • sanerdesign 10:22 am on April 8, 2014 Permalink | Log in to Reply

      I’m all for standardizing the theme activation notices rather than applying a blanket ban. I really feel that the admin notices can benefit the user if we can agree on the information that is displayed.
      This is just a suggestion, from my experience, but I think the following should be allowed in an agreed layout:

      Thank you message
      Link to developers site
      Link to the options if the developer isn’t just using customizer (optional)
      Link to that theme’s support pages

      It’s important to link to the developer in recognition of their hard work.
      A link to the theme options, I feel, is still important whilst they still exist. Theme options allow the developer to not just add options but to add a lot more information than they could on the customizer. Yes I am talking upselling (dirty word I know). Whilst we are probably all against over-the-top upselling and promotion of pro options etc we also have to accept that businesses are making money from this format and it is that money that pays for ongoing development and support of the theme. If we make it too difficult for developers to upsell we could end up with a lot of poorly supported themes that don’t get developed. I do think that this would be bad for the end user.
      The link to support pages is self explanatory but it is really important to let the user know immediately that there is somewhere to get help if they struggle with their chosen theme.

      Whilst I believe that it is the user experience that is always the most important for every action that we take we should consider the developer and their business for it will always be them that keep the WordPress themes fresh, supported and developed.

      Hugo

    • Schwarttzy 4:04 am on April 9, 2014 Permalink | Log in to Reply

      I don’t understand why after a theme gets activated that they get redirected to the page “Appearance.” Are they trying see how many themes they can activate in a minute or what? What’s so wrong with a page explaining the theme? Or possibly things they may want to do now that they activated this theme?

      Why is it so crucial that they get taken back to all the other possible themes they could change too?

      • CyberChimps 1:09 am on April 10, 2014 Permalink | Log in to Reply

        +1.

        Valid points.

        The explanation I was told was because they want to improve the on boarding process for WordPress, and there is some concern that a lack of selection for themes may be a pain point. However, they are simply creating a user experience nightmare with all of these new rules.

    • nikeo 2:13 pm on April 21, 2014 Permalink | Log in to Reply

      Hi,
      This follows a discussion with @chipbennet and @catchtheme during a theme review (https://themes.trac.wordpress.org/ticket/18164).

      We were wondering about the possibility to incorporate links into the top admin bar.
      In my case (Customizr theme), I have added a “Help” button in the admin bar which is visible both on back end and front end for a user connected.
      Users can have an almost direct link to the support forum on WP.org, the FAQ or the theme ‘s documentation if they feel lost. I think this makes the theme more user’s friendly and this is not redundant with the built-in WP links already displayed in this bar like : add a new post,/page…, link to dashboard, search, …

      Many popular plugins are elevating those kind of links in the admin bar and I think that’s often really interesting from a user experience perspective too.

      I would love to have your point of view/feedback about this and hope that we could come up with consistent guidelines for the WP themes.

  • Chip Bennett 2:35 pm on April 3, 2014 Permalink
    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 header/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 Plugin 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 CSS 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 GPL-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 core standard for inline documentation.

    Translation

    Themes are recommended to be translation-ready.

    Social Profile Links

    Themes are recommended to use a custom navigation menu when incorporating social network profile links

    Theme Options

    Themes are recommended to integrate Theme options into the core Theme Customizer

    Discuss

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

     
    • Rohit Tripathi 2:41 pm on April 3, 2014 Permalink

      +1 For Everything. Especially, the guideline change related to Screenshots. I hope it goes through.

      • Edward Caissie 4:19 pm on April 3, 2014 Permalink

        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 Permalink

      How much time do we have before recommendation of using theme customizer turns into requirement?

      • Chip Bennett 2:59 pm on April 3, 2014 Permalink

        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 Customizer? I’m genuinely curious what those reasons might be.

        EDITED TO ADD: We made the Settings API *recommended* years ago, and have never made any move toward making it *required*.

        • tskk 3:03 pm on April 3, 2014 Permalink

          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 Permalink

            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 UI much more manageable.

            Almost every control imaginable is built-in to the API. 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 Permalink

              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 Permalink

            I think with a little thought the drag and drop for page builders can also be integrated in the customizer.

            My thoughts here are based on the new incoming Widget control section which has some drag and drop options for the widgets.

        • tskk 2:08 am on April 4, 2014 Permalink

          Also customizer doesn’t have a reset button, import/export option.

          • Schwarttzy 4:12 am on April 9, 2014 Permalink

            import/export would be sweet for the customizer

    • daveshine (David Decker) 3:39 pm on April 3, 2014 Permalink

      *Tranlation-ready* should totally be REQUIRED!

      Why?
      Translations are essential, and I never understand why an international used platform like 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 core, 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 Permalink

        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 Permalink

        I think it would be great if every theme and plugin were internationalized. From my experience reviewing themes a number of theme developers do not have a deep understanding of 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 header 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 Permalink

        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.

      • Sami Keijonen 5:30 pm on April 3, 2014 Permalink

        I’m with David here. Make it required. This has been in theme/plugin 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 Permalink

        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 HTML 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 Permalink

      … 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 Permalink

        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 Permalink

          With David 100% on this one.,make it rquired

    • Morgan Feeney 3:47 pm on April 3, 2014 Permalink

      Theme options in the customizer! 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 Permalink

      +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 Permalink

      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 Permalink

        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 Permalink

        I’m fine with that; I’ll update the post accordingly.

      • Catch Themes 3:22 pm on April 5, 2014 Permalink

        Yes I agree with Justin… It should be either readme.txt or license.txt.

    • Ron 5:23 pm on April 3, 2014 Permalink

      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 Permalink

        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 Permalink

          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 Permalink

            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 Permalink

              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 Permalink

              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 Permalink

          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 Permalink

      +1 for all @chipbennett!

      • alex27 10:34 am on April 4, 2014 Permalink

        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 Permalink

      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 Permalink

      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 Permalink

      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 WordCamp 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 Permalink

      +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 Permalink

      +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 Permalink

      How should I be escaping Custom CSS? 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 Permalink

        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’ ) );

    • Catch Themes 12:49 pm on April 17, 2014 Permalink

      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 Permalink

        New Guidelines are typically enforced one month after final release, to allow sufficient time for adoption.

  • Chip Bennett 2:28 pm on February 7, 2014 Permalink
    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 revisions 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 Plugin 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. Suchscripts are Plugin territory, and pose a significant security risk if not handled properly. Custom CSS 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 GPL-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 core standard for inline documentation.

    Translation

    Themes are recommended to be translation-ready.

    Social Profile Links

    Themes are recommended to use a custom navigation menu when incorporating social network profile links

    Theme Options

    Themes are recommended to integrate Theme options into the core Theme Customizer

    Discuss

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

     
    • tskk 2:34 pm on February 7, 2014 Permalink

      I have seen reviewers asking authors to declare license for images which are part of the theme, do we authors need to? if so how? do we have to list all images used in the theme and declare their license?

      Also will the recommendations be migrated to required any time soon?

      • Chip Bennett 3:02 pm on February 7, 2014 Permalink

        Yes, bundled images must have licenses declared. If the developer created the images, then it is fine to state that they are copyright the developer, and released under the Theme’s license.

        • tskk 3:42 pm on February 7, 2014 Permalink

          but do we have to list them like :
          Filename.png – License ?

          If a theme has multiple skins, the list will be huge.

          • Rohit Tripathi 3:55 pm on February 7, 2014 Permalink

            We can do it folderwise. All images inside a particular folder fall under one license. And the ones in a different folder have a different license.

      • Chip Bennett 3:05 pm on February 7, 2014 Permalink

        Some things added as *recommended* are there as a phased approach toward *required*; others are not; they are simply there as a best-practice recommendation.

        • tskk 3:28 pm on February 7, 2014 Permalink

          Is theme customizer going to be required? if so how much time do we have? its going to be major overhaul for many themes.

          • Chip Bennett 3:32 pm on February 7, 2014 Permalink

            If there’s ever a timeline, we’ll communicate it. For now, this is the “get it on people’s radar” phase. :)

            And, it really isn’t a huge overhaul at all, if the Settings API is implemented properly. It takes minimal code to extend the Customizer via the Customize API.

      • fernandot 9:04 am on February 16, 2014 Permalink

        What about the changelog?

        It’s strange that there are complete guidelines for plugin submission that require a special readme.text file with a section for change log and there aren’t the same guideline for themes en the official repository.

        It’s frightening to update any theme with no information about the changes that you’re going to approve, while with plugins you are plenty informed about what is gonna happen.

        I’m truly concerned about this absence of mandatory for themes since they are the face of our sites. And yes, of course, I can make a child theme for my customizations but the problem remains the same: I don’t know what it is gonna happen when I update a theme from the repository.

        Why?

        Cannot this be changed?

        • Chip Bennett 11:17 pm on February 16, 2014 Permalink

          I agree with you in part, but the reality is, with the current infrastructure, even if we required Themes to include a Change Log, there would be no way to expose that Change Log to end users, either via the WP-Admin back-end, or via the Theme’s directory listing page. End users would have to pull up the Theme’s directory listing, then dig through the SVN files to find the readme or change log file.

          Also: requiring a change log would not ensure that all Theme developers add consistently useful and detailed information for each update.

          So, requiring a change log would not guarantee any real benefit to end users. Ensuring that end-user benefit is a long-term objective that will have to include changes both in what is required of Theme developers and also in the Theme directory infrastructure.

          • fernandot 5:29 pm on February 17, 2014 Permalink

            I agree with you, also in part :)

            I understand your complaints but I really believe that it could be a great benefit for users. You only visit the updates page in your dashboard and, if there is any update for plugins and themes the difference is huge and, in case of themes, a question of faith.

            As for plugins there could be mandatory to submit a change log, if plugin developers can do it (most of them no profit) more easy for theme developers to require because they are the main interested in promote their themes in repository, as a lot of them sell themes (profit).

            It’s my opinion as heavy user and WP consultor for some companies that demand it to me.

            • Chip Bennett 1:39 pm on February 18, 2014 Permalink

              The point is: we could require a Plugin-standard readme.txt for Themes, including Change Log and Update Notices, but it wouldn’t change anything. As far as I know, WordPress doesn’t parse Theme readme.txt files in order to display Update Notice on the Upgrades page. The infrastructure isn’t in place, the way it is for Plugins.

    • Inekris 2:52 pm on February 7, 2014 Permalink

      Just some clarification for non-English readers might come in handy.

      • By ‘must not’, the actual meaning is ‘are not allowed to’, ,ie, it is a binding restriction
      • By ‘end-user’, the person(s) actually administering, or have acces to the back-end of the site, not the readers.

      I know these questions might seem silly, but assumptions are the root of all screw-ups, so better safe than sorry.

    • Sami Keijonen 2:53 pm on February 7, 2014 Permalink

      I would definitely require translation-ready.

      It doesn’t encourage to use Plugin-standard readme.txt file, when it’s not used anywhere in .org site.

      Other than that guidelines seems good to me.

      • Chip Bennett 3:03 pm on February 7, 2014 Permalink

        I would, too; but we’re simply not ready. Consider making translation-ready formally *recommended* as the first step toward eventually making it *required*.

        • daveshine (David Decker) 9:09 pm on February 14, 2014 Permalink

          Can explain further what “we’re simply not ready” means? Is that regarding “Language Packs” or such?

          It should be required that all themes are translation-ready — that has nothing to do with language packs directly, though it would need no extra work if language packs happen for themes then… :)

          When I give support for my plugins, one of the biggest issues are bad internationalized themes or those that are not translation-ready at all.

          Any GOOD WordPress theme should be translation ready, if it is not, than it is no good theme IMHO, no matter how it looks…! :)

          • Chip Bennett 11:12 pm on February 16, 2014 Permalink

            “We’re simply not ready” means that Translation itself isn’t mature enough as a properly implemented feature to be *required* at this point. It’s a matter of education, not one of infrastructure. I agree that the ultimate goal is to require translation for directory-hosted Themes; but we need to ensure that implementing that requirement doesn’t raise the bar unreasonably high. Right now, it would. 90% – perhaps even 95% – implementation is fairly simple. But it is that 5-10% of string translation that prevents us from making it a requirement at this time.

            Full disclosure: I personally lobbied to propose that we make “translation-ready” a requirement in this go-round. But I agreed with the rest of the admins (and others queried) who argued that, as a whole, we’re just not ready to make it a strict requirement. So the approach we would like to take is to emphasize translation now, by making it *recommended*, and then setting some future end date, probably tied to a future WordPress release, at which time we will increase the criticality to *required*. And in the time in-between, we will put effort into educating developers regarding proper/best-practice implementation of translation.

      • Chip Bennett 3:06 pm on February 7, 2014 Permalink

        Note: there are (long-term) plans for readme parsing. Those plans will first include the Plugin-standard readme file, and will hopefully be extended to include others (readme.md, for example). So, making it *recommended* at this time is a first step in that direction.

    • Ulrich 3:02 pm on February 7, 2014 Permalink

      Just to clarify the readme file can also be a readme.md?

      I would like to see a Child Theme and Tags section.

      • Chip Bennett 3:07 pm on February 7, 2014 Permalink

        Yes, at this time, the readme file can be any clearly identified format (readme.txt, readme.md, README, etc.)

        I’m not sure what you mean by Child Theme and Tags section?

        • Ulrich 4:03 pm on February 7, 2014 Permalink

          What I meant have a guidelines for child themes. Something along the lines of “Child themes need to be functionality wise or design wise different to the parent theme.”

          There is no clear guideline what the theme needs to achieve to be allowed to use a certain Tag. accessibility-ready being the exception here.

    • Rohit Tripathi 3:22 pm on February 7, 2014 Permalink

      I don’t think Custom Navigation Menu for Social Profile Links is a Good Idea.

      +1 for everything else.

      • Chip Bennett 3:25 pm on February 7, 2014 Permalink

        Why don’t you think it’s a good idea? What are the disadvantages?

        EDIT: I have ulterior motives for this question. I’m presenting on the concept at WordCamp Dayton in a month, and would love to know any issues/problems/disadvantages with the concept, so that I can try to address them.

        • Rohit Tripathi 3:41 pm on February 7, 2014 Permalink

          Truly speaking. I can not think of a way in which it could be implemented. If you could provide a link to a theme, which implements social icons using custom menus, then I could provide better feedback on this.

        • kevinhaig 3:44 pm on February 7, 2014 Permalink

          The two themes I have use a widget for social links. It seems odd to add social links to a menu that is usually crowded to begin with.

          • Chip Bennett 4:09 pm on February 7, 2014 Permalink

            But a menu is just a “list of links”. A bunch of social profile links are a form of a “list of links”. Where it gets placed and how it gets styled is completely up to the developer.

            • kevinhaig 4:18 pm on February 7, 2014 Permalink

              I agree, however so is a social widget. So why is it recommended over a widget or other methods?

            • Zulfikar Nore 4:20 pm on February 7, 2014 Permalink

              Another problem that might arise here is the different icon fonts that are available. Are we going to say that all developers use one specific icon font set i.e. genericons?

            • Chip Bennett 4:21 pm on February 7, 2014 Permalink

              A social Widget is fine as well, but may not be as tightly integrated into the Theme. The recommendation is that the custom nav menu implementation is recommended over Theme Options or other Theme-specific implementations.

            • Chip Bennett 4:21 pm on February 7, 2014 Permalink

              Why would the icon font matter, if the Theme defines the CSS? :)

            • Zulfikar Nore 4:24 pm on February 7, 2014 Permalink

              So if theme A defines the CSS for Genericons and theme B defines its social menus as Font Awesome how would that carry over to the new theme?

              The user will still have to redo the menu won’t they?

            • Chip Bennett 4:37 pm on February 7, 2014 Permalink

              Why would the user have to redo the menu? A menu is just a group of “menu-item” post-types that get output as HTML list items. The separate Themes define the separate CSS to style the separate implementations of the social custom nav menu.

        • Ulrich 4:14 pm on February 7, 2014 Permalink

          This will be difficult for theme with another solution to switch.

          Is there a solution to do it with images and not icon fonts?

          • katmoody 4:28 pm on February 8, 2014 Permalink

            I’m newer here but wanted to jump in … hope that’s okay?

            This is my default way of handling menus for clients and I have done them with images, sprites and Font Awesome … maybe having a default would be a good idea. Justin Tadlock has a post that uses the same idea of a social menu but utilizes CSS selectors for the different social networks – which would make it possible to have lots of different social networks included without having to have them in the same order within the menu OR having to add class names. I can’t remember if he used Font Awesome with that example or a different one, but it works well and could be a great default.

            Theme authors could utilize hooks to change it around, use images, use an image sprite, or even just use text links …

            As for themes that already have a solution in place – that’s pretty easy – you just don’t display the menu (deregister it?)

            As for Justin’s work … both his Social nav posts are worth reading to understand how this could be done:

            http://justintadlock.com/archives/2013/08/07/social-media-nav-menus

            http://justintadlock.com/archives/2013/08/14/social-nav-menus-part-2

      • bassjobsen 3:39 pm on February 7, 2014 Permalink

        Can you give an example of a custom navigation menu for social profile links? I don’t understand what this mean at all.

        • Jose 7:23 pm on February 7, 2014 Permalink

          I know Stargazer, ( already mentioned ), I think Konstantin K’s Expound ( might ?) I know sorbet has it and uses really well. It’s just a simple way of creating a social links area without having to store/lose that information within themes. since menus are saved and theme options vary from theme to theme.

      • Ulrich 4:16 pm on February 7, 2014 Permalink

        @jeffr0 How did you find using it on wptavern?

        • Jeff Chandler 4:25 pm on February 7, 2014 Permalink

          I love the way Stargazer utilizes an icon font for social icons. It does limit the ability to use different icon images to represent social services but the icon fonts have the look and colors of the services and it’s portable so I’m willing to take the good over the bad.

          The only other potential downfall is if you want to make the icons larger, you must increase the icon font size. If you are using one icon font declaration in the CSS for use of icons across the entire site, adjusting the size will adjust all of them. Doesn’t work out so well if you only want the icons within the social menu larger instead of the entire site.

          • Chip Bennett 4:29 pm on February 7, 2014 Permalink

            The icon colors are actually defined via CSS – at least for Genericons. Also, because you can use specific CSS IDs and class names for custom nav menus, you can target your social menu specifically for adjusting the font size.

            • Jeff Chandler 4:31 pm on February 7, 2014 Permalink

              Yeah, I realize it’s just CSS and with the right CSS, I could increase the social icons by themselves without messing with the rest of the site. So not really a good or bad thing, just a means of how they are setup.

      • Konstantin Obenland 4:36 pm on February 7, 2014 Permalink

        Having a hard time to find a place for this comment. :)

        Even as (only) a recommendation, I think we are steering in very muddy territory here. While using the menu functionality to provide social links may be a good way to provide a somewhat portable social links experience, in reality it is not. There are no standards surrounding an implementation, so even if two themes use menus for it, it may very well be that they are still not compatible with each other.

        There are plenty of other, valid ways out there to provide social links. IMO it is not the place of the Theme Review Guidelines to recommend one approach over the other, especially without any kind of core provided support for a truly portable solution.

        We don’t recommend a specific way or script to implements sliders, we don’t tell theme authors how Featured Content should be done, we don’t recommend using `li`s over `div`s in comment list markup. Why would we recommend how to implement Social Links?

        • Chip Bennett 4:40 pm on February 7, 2014 Permalink

          The biggest advantage of the custom nav menu implementation is that the user retains user-created content (a group of links to social network profiles) when switching Themes. It is terrible user experience for a user to have to enter 6-10 social network profile URLs as Theme options every time the user switches Themes.

          And the implementation has no adverse impact. If a Theme doesn’t use it, the user still has to input the Theme options, and simply doesn’t apply the social menu to any of the Theme’s defined Theme Locations. It’s as if that menu doesn’t even exist.

          • Konstantin Obenland 4:43 pm on February 7, 2014 Permalink

            I’m not disputing that it is one of the better ways to provide that functionality.

            I’m saying that the Theme Review Guidelines have no place in even recommending it, without explicit core support.

            • Chip Bennett 4:46 pm on February 7, 2014 Permalink

              My comment above addresses this, but I see no problem at all with the Theme Review Guidelines adopting as “recommended” things that are best-practice implementations. That’s partly why some things are “recommended” rather than “required”.

              And core *does* have support for the implementation: the custom nav menu feature.

        • Konstantin Kovshenin 4:43 pm on February 7, 2014 Permalink

          Compatibility really just means the way the navigation menu location is called. In Stargazer and Expound it’s social, if all themes used the same theme location, it will all just work out of the box. If they use a different slug, well, the user will have to just assign their existing menu to the new location. If they don’t use wp_nav_menu(), the user can just assign their existing menu to a sidebar widget.

          In any case, the user will not have to re-enter their links to their social profiles every single time they switch a theme.

          • kevinhaig 4:54 pm on February 7, 2014 Permalink

            Usually if a user switches a theme, it’s for a longer period, and minor adjustments are not a big deal, in my opinion.

            However don’t you feel these kind of recommendations ultimately dampen the creativity of a theme development?

          • Chip Bennett 5:35 pm on February 7, 2014 Permalink

            While we want to defer to the developer’s prerogative regarding design intent and aesthetics whenever possible, I fail to see a “creativity of Theme development” argument in this case. We’re talking about a list of links.

          • Chip Bennett 6:08 pm on February 7, 2014 Permalink

            Since the Theme can define the menu CSS ID and class names, it’s really unnecessary to rely on a given custom menu name at all. The user merely needs to assign the correct menu to the correct Theme Location. Same with a Plugin that makes use of a menu Widget.

        • Chip Bennett 4:45 pm on February 7, 2014 Permalink

          I should also add: sometimes, the best way to *create* a standard is to pick an implementation, and then encourage its adoption. That’s been true for the Theme Hooks Alliance (outside of the Theme Review Team), Post Formats implementation, and many other features.

          To my knowledge, there is no better, more-portable way to implement social network profile links integrated into a Theme, than to use the custom nav menu method. So, unless and until a better method comes along, it is a net benefit to end users to encourage the best-known method as an adopted best-practice.

          • Konstantin Obenland 5:25 pm on February 7, 2014 Permalink

            sometimes, the best way to *create* a standard is to pick an implementation, and then encourage its adoption.

            Is it the WPTRT’s job to create a best practice?

            To my knowledge, there is no better, more-portable way […]

            That is a bad reason to create a recommendation. If anything, developers should be encouraged to come up with new, unique, and better ways. And of course there are already other ways of doing it out there!

            • Ian Stewart 10:03 pm on February 7, 2014 Permalink

              Another +1 to Konstantin’s points here.

            • Chip Bennett 10:14 pm on February 7, 2014 Permalink

              So, Konstantin and Ian: you both think it is a bad idea, and detrimental, for the Theme Review Team to promote and facilitate consensus around best practices? Really?

              I must strongly disagree with that position. Who better to educate and promote regarding best practices, and to help build consensus around those best practices? It is in the best interest of the WPTRT – and more importantly, it is in the best interest of end users – for WPTRT to engage in consensus-building around best practices.

              And promoting one implementation as recommended because it is the *current* best practice does not preclude the later development of *better* practices.

            • Emil Uzelac 10:40 pm on February 7, 2014 Permalink

              I will have to agree with Chip here, promoting best practices is not bad idea at all. Also why shouldn’t we educate?

      • Konstantin Kovshenin 4:36 pm on February 7, 2014 Permalink

        Just to clarify, using wp_nav_menu() to display links to social profiles doesn’t mean you have to use Genericons, or any icon font at all. You can still use sprites or images, that’s up to your theme.

        • Chip Bennett 4:37 pm on February 7, 2014 Permalink

          THIS. That’s the beauty of the implementation.

        • Zulfikar Nore 4:40 pm on February 7, 2014 Permalink

          That still does not make it portable from theme to theme as Konstantin Obenland points out above.

          • Chip Bennett 4:42 pm on February 7, 2014 Permalink

            How so? It’s always there. And someone could write a Plugin to define the CSS, and allow the social profile menu to be used, for example, in a sidebar Widget, regardless of the Theme.

            100% portability, with or without explicit Theme support.

            • Zulfikar Nore 4:43 pm on February 7, 2014 Permalink

              Then lets make it a “Plugin territory” in that case – always portable in terms of user defined links as well as the icons :)

            • Chip Bennett 6:05 pm on February 7, 2014 Permalink

              Why swing the pendulum that far that direction – too far in that direction, IMHO?

              If a Theme is designed such that social profile links are displayed in the site header (or footer), for example, you could do that with a dynamic sidebar. But that’s a lot of unnecessary hoops for both the developer and the end user, when the developer could simply output wp_nav_menu() in the desired location, and be done.

      • Justin Tadlock 5:36 pm on February 7, 2014 Permalink

        I want to provide a little feedback and answer a few questions on the whole social nav menu idea since I originally proposed it. This isn’t a direct response to Rohit only, but to all who have asked.

        The original article is here: http://justintadlock.com/archives/2013/08/07/social-media-nav-menus This shows how to create the menus with and image sprite.

        The updated tutorial is here with Genericons: http://justintadlock.com/archives/2013/08/14/social-nav-menus-part-2

        Those two posts go into quite a bit of detail and answer some of the questions some of you might have.

        I originally came up with this concept for a theme called Socially Awkward. After testing its success with users, I later added it to a theme called Stargazer. Both themes are on WordPress.org. Since then, it has picked up a little steam with other theme authors implementing it.

        The main reason for this concept was to handle data portability. The idea is that a user can create a nav menu with their social links. These can be used with nearly any theme either via a theme’s nav menu locations or widgets. They’re simply menu items.

        The cool part is that theme authors, if they choose, can define styles like what I’ve done with Genericons to make these menu items look cool without the user having to do anything other than select the nav menu location for a particular theme. It doesn’t require them to re-enter information or know the names of CSS classes to have their social menus look cool.

        This is but one approach to social profile links. I think it’s pretty cool. However, I don’t think it should be listed under “recommended”. What I’d really like to see is a separate section on the Make Themes site for “cool things you should try”. To me, this is nothing more than a resource that we should promote, which should be separate from the guidelines.

        • kevinhaig 5:07 am on February 8, 2014 Permalink

          +1 Justin

          I think your idea of social links is a very cool one, and I will look into it more.

          I also love the idea of a section on things to try.

          I just don’t like the idea of it being recommended, as developers will tend to gravitate to this solution as it is classified as a best practice. I’m not against best practices by the way, just not in this case. As theme developers move to this proposed best practice, it will in my opinion limit other creative ways of presenting social links.

          • Chip Bennett 1:01 pm on February 8, 2014 Permalink

            The idea is for developers to gravitate toward a consensus best-practice, because that gravitation leads to consistency for end users. It’s always important to be open to new and creative ways to do things, and that certainly applies here. And of course, a specific core-implemented solution would trump all.

            • kevinhaig 2:44 pm on February 8, 2014 Permalink

              I agree that consistency for end users is a good thing, but I think it’s important to balance that with creativity. Creative design also has a huge impact on the user experience.

              Incorporating social links into a menu is a great idea and an option that will fit many themes. But in some themes it may make better sense to go a different route.

              I think in this case it’s very a minor impact on the user experience, and as such I don’t feel it warrants being considered a best practice.

              Enough said….I do appreciate these kinds of discussions Chip! It’s one of the things that makes WordPress so great :)

            • Chip Bennett 3:07 pm on February 8, 2014 Permalink

              I agree that creativity is important, and I believe in deferring to the developer’s design and aesthetic prerogative. But, I just don’t see how this recommendation in any way hinders or infringes developer design. Bear in mind that we’re simply talking about HTML markup here – HTML markup for a “list of links”. Semantically, that’s a UL with a bunch of LIs. I don’t recall any Themes that are doing anything meaningfully different with the markup for their social profile links. Likewise on the back-end: the “list of links” is generated by a set of Theme options. There’s no “creativity” there. The Theme options are entirely utilitarian.

              The real creativity here is in the design/style of that markup – and that creativity is in no way hindered by using a custom nav menu to output the list items, or by having the user input their “list of links” via the custom nav menu UI rather than via the Theme settings UI. In fact, it’s the real beauty of this implementation. Want to use an icon font? You can. Want to use a different icon font? You can do that too. Want to use images or an image sprite? You can do that, too. It’s all defined in the CSS, by targeting link attributes.

    • bassjobsen 3:41 pm on February 7, 2014 Permalink

      I should make the standard readme.txt required

    • kevinhaig 3:53 pm on February 7, 2014 Permalink

      I’m not sure I fully understand the Arbitrary Header/Footer Scripts requirement.
      In themes I have developed I allow the user to set up a copyright strip at the bottom of the page, by entering an html line in a custom option panel. This allows them to set up links (for example designer links, or sitemap links). Is this what you are talking about?

      • Chip Bennett 4:12 pm on February 7, 2014 Permalink

        Links should be added as a custom nav menu. But a line of HTML is HTML, and not a script. In this case, “script” refers to an actual script, just as javascript or jquery.

    • Frank Klein 3:57 pm on February 7, 2014 Permalink

      Concerning the theme activation, the proposed guideline is “Themes must not implement activation redirects, admin notices, or similar functionality.”

      Does this exclude admin notices generated by something like the TGM Plugin Activation class?

    • Mel Choyce 4:18 pm on February 7, 2014 Permalink

      Any chance for allowing multiple theme authors any time soon?

      • Rohit Tripathi 3:27 am on February 8, 2014 Permalink

        Even I Look forward to it! Let’s hope its added sometime in future,

    • Chip Bennett 4:24 pm on February 7, 2014 Permalink

      Unfortunately, that one’s outside of our control/scope. That’s an issue with the WordPress.org Theme Directory itself. If the infrastructure supported multiple authors, the Theme Review Team certainly would as well.

    • Konstantin Obenland 4:26 pm on February 7, 2014 Permalink

      Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality.

      “Similar functionality” is extremely soft. The Theme Foundry recently started to integrate “unboxing” messages right after activating themes. That has received nothing but exceptional feedback on WordPress.com, but would probably fall under this guideline. It is also not clear that while admin notices are forbidden in general, it is fine to display them in the context of plugin recommendation. I understand how redirects can be confusing, I don’t like the direction of the other two.

      Theme Credit Links: […] a Theme shop really only needs to use examplethemeshop.com OR examplethemeshop.com/themes/theme-slug. There’s really no need for both.

      I understand the requirements around each URL, I do not understand how having one makes the other obsolete. I think it is reasonable for a theme author to specify both URLs, respecting the current guidelines in place. The links are currently only visible to users in the Appearance menu, and have no effect on the front-end. If anything they provide users with more context, and avenues to get support. This would be one of the rules that seem arbitrary and overreaching.

      • Zulfikar Nore 4:28 pm on February 7, 2014 Permalink

        +1

      • Jeff Chandler 4:29 pm on February 7, 2014 Permalink

        Just a question but is this guideline also in reference to Helpers that can be used to provide a tour of the theme when it’s activated. Would those violate this guideline

        • Chip Bennett 4:35 pm on February 7, 2014 Permalink

          They already do. Core defines those as a core-only functionality. Unless/until core considers them to be open to use by Themes/Plugins, they’ll be disallowed. (That’s been true since their inception.)

          • Jeff Chandler 4:43 pm on February 7, 2014 Permalink

            Wow, and here I am constantly telling developers they should add helpers to their plugins or themes after activation so I know where to go to configure them. Now I feel bummed out for giving bad advice,

      • Chip Bennett 4:34 pm on February 7, 2014 Permalink

        I’d love to see some UX feedback on types of activation messaging/help/etc. The intent is to prevent misuse/abuse, not to prevent legitimate user assistance.

        As for the credit links: again (and unfortunately), the problem is the misuse/abuse of them. If they’re useful and appropriate, they’re generally going to pass.

        And as with most Guidelines, exceptions can be granted with sound justification. These Guidelines that get into subjective areas are very difficult to write objectively. It will always be a work-in-progress to improve and clarify them.

        • Konstantin Obenland 4:39 pm on February 7, 2014 Permalink

          These Guidelines that get into subjective areas are very difficult to write objectively.

          Ha, I remember it being the biggest challenge for me, when I started reviewing themes! :)

          But I really don’t see how only allowing one link rather than two improves that. It doesn’t change the nature of the linked content. It does not help in solving the challenge of subjectivity.

          • Chip Bennett 4:41 pm on February 7, 2014 Permalink

            It’s not that only one link instead of two is being allowed; rather, it is that the two links provide meaningfully different information.

            • Zulfikar Nore 4:56 pm on February 7, 2014 Permalink

              somethemeshop.com as author url provides meaningful info about the author and somethemeshop.com/blog/theme-slug has meaningful info on the theme.

              If that is the desired end result then why are we saying that is no longer acceptable? Or even considering it?

              The abuse/misuse is when neither of the links are relevant and meaningful in context right?

            • Chip Bennett 5:36 pm on February 7, 2014 Permalink

              If you’re landed on somethemeshop.com/blog/theme-slug, what are the chances that you can’t or wouldn’t find your way tosomethemeshop.com?

            • Zulfikar Nore 5:57 pm on February 7, 2014 Permalink

              The chances are pretty good but I still think we should not penalize authors for using their themeshop/dev site as author url under the guise of misuse/abuse.

              As long as the two are relevant to the theme then I say its perfectly fine to have them included.

            • Chip Bennett 6:01 pm on February 7, 2014 Permalink

              I don’t think it’s a matter of “penalizing”. The Theme URI and Author URI really aren’t publicly exposed (except for the one used as footer credit link). They’re entirely for conveying information to the end user.

              The ultimate point we’re trying to convey is that the links should be useful for conveying relevant information to the end user.

        • Zulfikar Nore 6:23 pm on February 7, 2014 Permalink

          I think the requirement should then be “If both theme url and author url are used” they “must be” relevant as in conveying….

          (a) Information about the author and
          (b) information about the theme.

          If the two conditions are not met then the url is not allowe be it the author or theme url.

          To outright say that author url is not allowed is a bit too restrictive IMHO!

          • Chip Bennett 6:30 pm on February 7, 2014 Permalink

            And to outright say that Author URL is not allowed is not the intent. :)

            In my mind, this mainly impacts:

            1) Theme shops. A Theme shop isn’t an “author”; an author is a person. So, a Theme Shop landing page is, from the end user perspective, redundant with the Theme’s page on the Theme shop’s site.

            2) Individual Theme developers who have a valid Author URI, but then use what amounts to a “hey, I released this Theme” blog post as Theme URI. Generally, such a blog post provides no additional, meaningful information for the end user from what is already provided by the Author URI.

            (Now, Otto’s example, where the developer provides a static page with Theme documentation, information, maybe support links, etc.? Entirely appropriate as Theme URI.

            I’m just struggling with the right words to articulate the difference.

      • Ulrich 4:59 pm on February 7, 2014 Permalink

        @obenland Do you think you could share a screenshot of what The Theme Foundry has done?

      • Ian Stewart 10:02 pm on February 7, 2014 Permalink

        +1 to both these points.

      • Emil Uzelac 10:48 pm on February 7, 2014 Permalink

        I would definitely love to see an example and users feedback as well.

    • Justin Tadlock 5:18 pm on February 7, 2014 Permalink

      I wanted to bring up some of these points in the admin exchange on this a couple of days ago, but I’ve been a bit busy this week. Now that I’ve had some time to sit down, here’s my response to the required points.

      Sane Defaults: This is something we’ve been pushing for some time. It’s definitely needed.

      Bundled Plugins: I agree on this as well, but I want to reiterate what I’ve previously said in this discussion to make sure we’re not taking this too far. Here’s the link: http://lists.wordpress.org/pipermail/theme-reviewers/2014-January/017291.html

      Arbitrary Header/Footer Scripts: +1

      Theme Activation: Agreed for the most part. However, I wouldn’t be entirely against all things like this. I’d like to see a particular implementation first before making an overarching decision on all features.

      Theme Documentation and License: Disagree in parts, particularly with copyright/license attributions. A license.txt file works just fine for this purpose. As long as the theme makes copyright and license clear, that’s all I care about.

      On the subject of readme.txt, I don’t believe we should be dictating much of anything that goes into that file. It should be treated **exactly** like that of the plugin directory.

      I also see this as largely another stumbling block for theme authors. I’d rather them focus on making great themes than having to figure out the complexity of doing a readme file the correct way. By and large, it has nothing to do with theme development and everything to do with what a few of us would like to see.

      Theme Credit Links: Strongly, strongly disagree. I simply can’t get on board with this at all. If I wanted to give justintadlock.com as my author URI and justintadlock.com/themes/example as my theme URI (what I used to do before having a separate theme site), I can’t think of a valid reason not to allow that. One of the earliest reasons for the theme review team was to prevent spam and people trying to game the system in some way. That’s the reason we check the author and theme URIs.

    • Samuel Wood (Otto) 5:32 pm on February 7, 2014 Permalink

      I disagree with the credit links. If I made a theme, I most certainly would use an Author URI of http://ottopress.com and a Theme URI of http://ottopress.com/themename or similar to that, and yes, that would be perfectly valid.

      To disallow this is not an acceptable “requirement”.

      • Chip Bennett 6:02 pm on February 7, 2014 Permalink

        Clearly, as-written, it’s not articulating what we’re trying to get after. That’s why we’re having the discussion: to generate the feedback necessary to articulate what we’re trying to accomplish.

    • Zulfikar Nore 6:35 pm on February 7, 2014 Permalink

      I totally agree with point #2

      But for #1….For most theme shops – the shop is the developer (a team effort) and therefore they are essentially the author.

    • Zulfikar Nore 6:38 pm on February 7, 2014 Permalink

      OK, I don’t know why this landed down here but it was in response to: http://make.wordpress.org/themes/2014/02/07/wordpress-3-9-guidelines-revisions-proposal/#comment-33797

    • Chip Bennett 6:44 pm on February 7, 2014 Permalink

      “Essentially the author” – but that’s not the intent of Author URI.

    • Jose 7:49 pm on February 7, 2014 Permalink

      I am for most of the things. I, too, will have to agree with Otto and Justin with credit links. We just have to use our best judgement when it comes to that. :)

      As for the readme I think it should be recommended not required.

      • Chip Bennett 8:01 pm on February 7, 2014 Permalink

        Yep – the intent of the credit links was to get wording out, and to get feedback. Expect changes there. :)

        And regarding the reaadme: the only thing that’s changing is that we’re specifying the location for any *required* documentation. Previously, we stated that certain things were required to be documented, but didn’t say where. So, we’re clarifying that the location for required documentation is in the readme file.

        The *format* of the readme is being recommended as the Plugin-standard readme.txt, but we’re not proposing that it should be *required* to be in that format.

        • Jose 8:09 pm on February 7, 2014 Permalink

          Gotcha! That makes a little more sense now. :)

    • Chip Bennett 8:06 pm on February 7, 2014 Permalink

      Regarding admin notices: would it be helpful to clarify that any admin notices must be related specifically to Theme setup, and not advertising in nature?

      • Ulrich 9:37 pm on February 7, 2014 Permalink

        Yes, I am working on an extension of the current activation notice. This is what I have created.
        http://grappler.tk/screenshots/Screenshot-20140205001.jpg

        It is only displayed once when the user activates the theme the first time. There is no advertising.

        • Chip Bennett 10:10 pm on February 7, 2014 Permalink

          That is certainly unobtrusive, but is it *necessary*? It merely provides a link to the Theme Options page – a page that is in a standard location that is the same for all Themes. I see this more as a user education issue than a real need.

    • CyberChimps 10:14 pm on February 7, 2014 Permalink

      “Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality.”

      This a bad move that will hurt users experience, and continue to cause user confusion.

      What we need is a core solution to the problem such as what I mocked up here: https://twitter.com/trentlapinski/status/428995176426532865/photo/1

      The reason we got rid of redirects was so people can switch between themes quickly without being redirected, a reasonable move. What this also did unfortunately was confuse first time users, increased theme abandonment rates, as well increases in support from people asking where the theme options went.

      First time users need hand holding to let them know where to go to setup their theme, find documentation, and support. We absolutely need some kind of method to on-board users to setup their themes for the first time. The current theme activation notice is useless, and doesn’t tell anyone anything.

      This is why my team and I are developing the concept above, and are hoping to get it in core and would love the Theme Review Admins to encourage we add a standard way of on-boarding users for all themes.

      On Social Profile Links: Poor solution, can we please figure out a better one? I think we need a core solution to this as well.

      On Theme Options in favor of the Customizer: Again not a good solution. The Theme Customizer is half baked, and the version of the Customizer is embarrassing compared to WordPress.com. It was implemented into Core way too soon, and needs to be refined and polished before it can ever be considered as a longterm solution to theme options.

      On that note, Theme Options are not going away even if we perfect the Theme Customizer. For example, how can we ever add drag and drop functionality to the blog or define settings for archives and templates from the theme customizer? You can’t, Theme Options aren’t going anywhere. Again would love a core solution or some kind of options framework for everyone to use, which would make a lot more sense, but forcing people to use the Customizer to do things it was never intended to do isn’t the solution either.

      • Chip Bennett 10:21 pm on February 7, 2014 Permalink

        “What this also did unfortunately was confuse first time users, increased theme abandonment rates, as well increases in support from people asking where the theme options went.”

        Has this been supported anything other than anecdotally? I’d love to see user testing on this point, and would certainly support solutions that resolve demonstrated UX issues.

        “On Social Profile Links: Poor solution”

        Why is it a “poor solution”? Please elaborate.

        “On that note, Theme Options are not going away even if we perfect the Theme Customizer.”

        You are correct. The Theme Customizer doesn’t replace Theme Options. At best, it could (potentially) replace Theme *Settings Pages*. Themes would still have to use either the Settings API or the Theme Mods API to define, save, and use Theme options. The recommendation is added only because it is beneficial to end users, and actually helps resolve the issue you mention above – because if Theme Settings are incorporated into the Theme Customizer, then end users can configure Theme Options and activate their Theme in one, single action.

        “…but forcing people to use the Customizer…”

        Recommended != Required. No one is being “forced” to do anything.

        • CyberChimps 10:56 pm on February 7, 2014 Permalink

          Seeing as we can’t track users we don’t have the kind of hard data wish we had to definitively prove this.

          All we know is we’ve seen an increase in first time users in our support forums who can no longer find our theme options since 3.8 was released and we had to remove our redirects. We’ve also seen an increase in theme abandonment since 3.8 which we are assuming is due to people who do not know what to do once the theme is activated and can’t find the theme options or our support forums. All we can do is track what happens in our support forums and listen to what users tell us, and ever since 3.8 was released we’ve seen increased confusion as to what to do after a theme is activated.

          We could even simplify it to something like this: http://i.imgur.com/mgtRBVV.jpg Or anything really that gives the user some kind of direction to go in after a theme is activated. Again the purpose of this is to give a first time user a guide on what to do next. The new activation notice does not accomplish this.

          As for the Social Profile links, again this is something that I think needs to be either addressed in Core or in a plugin. Almost all themes I’ve seen use stylized social icons, using the menu system for assigning links to icons is confusing. While a clever work around, I don’t even want to think about the support nightmare this is going to cause.

          As for the Customizer, again at most this can only be recommended for now. I was speaking about in the future of possibly requiring the Customizer.

          • tskk 11:03 pm on February 7, 2014 Permalink

            I too would like to redirect users to theme options page after activation, Redirecting theme there is helping them use the theme better.

          • Emil Uzelac 12:19 am on February 8, 2014 Permalink

            I will still stand against the redirects.

            The image you presented us with seems harmful and if really is beneficial and if it doesn’t cause any issues, maybe we can work something out. Nothing is written in stone, right?

            • Zulfikar Nore 7:53 am on February 8, 2014 Permalink

              +1.

              I’ll also stand against redirection.

              How about hooking in to the “Theme Actions” section on the active screenshot? A theme options button next to the Customize button sort of thing.

              You could also be innovative and add a secondary button below the current “Theme Details” on hover and maybe that too could open in a modal window with help details? Or better still, hook in to the current modal and details there?

              Just throwing some ideas around :)

            • Chip Bennett 1:04 pm on February 8, 2014 Permalink

              Here’s my suggestion for an improved workflow:
              https://core.trac.wordpress.org/ticket/26899

            • tskk 1:27 pm on February 8, 2014 Permalink

              That would need all themes to use customizer ditching the theme frameworks we use.

            • Chip Bennett 1:40 pm on February 8, 2014 Permalink

              No, it wouldn’t. Why do think that it would?

              Whatever options framework you use itself uses either the Settings API or the Theme Mods API. The Customizer doesn’t replace either of those APIs, and in fact, *requires* and relies on the use of one of the two APIs. The Customizer is merely a different *front end* for settings. Hooking into the Customize API doesn’t change anything at all with any of your current Settings. It can (but doesn’t have to) replace the Theme Settings page. But your options framework? It doesn’t replace that; in fact, it *can’t* replace that – and without your options framework, the Customizer wouldn’t work at all with your Theme’s settings.

        • nikeo 1:12 pm on February 8, 2014 Permalink

          +1 for this https://core.trac.wordpress.org/ticket/26899
          => Lot more advantages than drawbacks to me from a user experience perspective

        • Zulfikar Nore 2:04 pm on February 8, 2014 Permalink

          The proposed customizer redirect although has some advantages it will only benefit themes that have adopted the Customizer as the means for theme Settings.

          IMO it is defeatist on two counts …

          (1) It will go against the grain of “No Redirection” stance.
          (2) Bad user experience to land on an empty Customizer (except for the defaults) if the developer uses a custom options framework.

          We all seem to assume that all first time users are “dumb” so lets spoon feed them when the emphasis should be on educating them and then let them find their way to those places where they can better understand the facilities and use them effectively.

          • Chip Bennett 2:23 pm on February 8, 2014 Permalink

            You’re missing the point. The Customizer isn’t a “means for theme Settings”. It’s merely a front end that *exposes* existing Theme settings. It doesn’t change the way that Themes handle settings, at all. Not one bit. It’s just an alternate front-end – and a darn useful one, I might add, because of the real-time preview of changes.

            1) The Themes UI already includes a “customize and activate” link for Themes. It’s not a redirection; it’s merely part of the Theme-selection workflow. In fact, the Customizer is invoked before the new Theme is ever even active, allowing for user configuration and preview of settings before that configuration ever appears on the site front end. This is freaking awesome UX, not “defeatist”.

            2) I don’t think you’re understanding what the Customize API is or how it works. Unfortunately, that seems to be a somewhat widespread problem. We’re attempting to help alleviate that misunderstanding/problem by encouraging Theme developers to hook their existing options into the Customizer – emphasis on *existing*. Nothing changes, except that the Theme settings auto-magically get exposed in the Customizer. The Theme’s handling of those Settings doesn’t change. Not at all. Not even a little bit. Your Settings Page still exists (though if you wanted to, you could get rid of it). Your Settings framework still exists. Your Theme Settings are still added via register_setting(), still get passed through your defined sanitization callback when saved, and are still called via get_option(). None of that changes.

            Nothing “defeatist” there. Just awesome UX made available to the end user.

            “We all seem to assume that all first time users are “dumb” so lets spoon feed them…”

            That’s actually pretty ironic, given that the reason that I argue against Theme activation admin notices is because we should be educating users about where the standard location for a Theme Settings page is. Users aren’t dumb, and we don’t need to treat them as such. We’re merely *recommending* that Themes hook into an awesome API that provides a sweet end user benefit (real-time preview of settings configuration). It has nothing to do with users being dumb (not true) or with a systemic lack of educating users about basic WordPress UI (true, and a failure on the part of developers, not users).

    • PeterRKnight 4:04 pm on February 8, 2014 Permalink

      Just to be extra clear does a bundled plugin mean actually packaging the files with the theme?
      Or does it also apply when using an activation class that downloads & activates a plugin separately during the activation process?

      • Chip Bennett 4:06 pm on February 8, 2014 Permalink

        Activation scripts are fine. In that case, the Plugin files are not actually bundled with the Theme; the user downloads and installs the Plugin from the WPORG Plugin Directory.

        Bundled Plugins refer to Plugins for which the Plugin files are physically bundled with the Theme.

    • alex27 6:14 pm on February 10, 2014 Permalink

      Regarding Arbitrary Header/Footer Scripts – it’s still allowed to add a field for Custom CSS to be outputted in header, right?

      • Chip Bennett 2:31 pm on February 11, 2014 Permalink

        Quoting directly from the post:

        Custom CSS is acceptable, if properly sanitized.

    • wpweaver 7:43 pm on February 17, 2014 Permalink

      RE: Header/Footer scripts

      This is a good idea in theory, but….

      It seems to me the requirement overlooks a serious problem. The thought is that is plugin territory, but it isn’t in this case because there is no way to have a plugin get into header.php or footer.php. No actions, no usable filters.

      So say I want to add a video script right below or above my header image. The header image typically gets inserted in header.php by each theme, right? If not a video, then there are other examples of external sites providing a plugin script one might want in the header/footer – I know of some musician sites that provide very nice links to players and the like via scripts. But you can’t get modify that code from a plugin. I’ve tried to write that plugin, and I don’t know how to do it. There is no support from the core to do that. As far as can tell, doing so will require a new standard hook or something that all themes need to call from header.php and footer.php. To me, this is a huge gap in the API.

      So it is not a reasonable requirement. Unless that is not what you mean – stuff coming from header.php and footer.php. Or unless I missed something fundamental about how header.php and footer.php work.

      • wpweaver 7:56 pm on February 17, 2014 Permalink

        A good compromise requirement would be to only allow scripts in the header/footer from users with an appropriate user role.

        • Konstantin Kovshenin 7:59 pm on February 17, 2014 Permalink

          That would actually be a bad compromise because it’s insecure. You can’t assume that everybody is using the same set of capabilities for specific roles. For example, on many networks the unfiltered_html capability is turned off for everyone, even for the super administrator role.

          • wpweaver 8:00 pm on February 17, 2014 Permalink

            Role/capability – whatever.

          • wpweaver 8:04 pm on February 17, 2014 Permalink

            I’m after a bigger point – I think non-programmer but competent site admins should be able to insert a script to a musician’s player – or whatever – right below the header image (or above it, or after the title – don’t want to nitpick), or into the footer. These kind of needs exist. Banning scripts from header.php/footer.php would totally preclude this option from anyone other than someone with the ability to go in and modify PHP code. That is not a good option for “mere” mortal users.

            • Chip Bennett 1:44 pm on February 18, 2014 Permalink

              The Theme can provide template hooks (such as THA), or competent site admins can use a Child Theme to add the desired scripts.

              Again, an actual use case would be helpful here.

      • Konstantin Kovshenin 8:01 pm on February 17, 2014 Permalink

        You should check out the wp_head and wp_footer actions.

        • wpweaver 8:06 pm on February 17, 2014 Permalink

          Yeah – I have. Tell me how to do what I just said with those action? Let’s see – wrap header.php with output buffering, capture that, parse it, find the right place to insert the code. Yeah, right.

          • Konstantin Kovshenin 8:13 pm on February 17, 2014 Permalink

            Output buffering? We’re talking scripts here, ones that go in the head section of the site, or before the closing body tag in the footer, that’s pretty standard. Unless you’re referring to mid-page inline js-code, which users can already insert using the editor (if they have the necessary capabilities).

            • wpweaver 8:25 pm on February 17, 2014 Permalink

              And that is my point. A”mortal” user doesn’t have the “necessary capabilities. But they could fill in a box that says “Insert before site header image” or “Insert above menu” or “Insert after site title” – places the theme author can add the the code in “header.php”. This is a reasonable thing for people to want to do – so some with unfiltered_html should be allowed to do that without having to have a programming degree – or the level of comfort of editing PHP file.

              (Which of course is a terrible idea any way. Don’t know why that editor is still there! Change theme functionality via child themes only!!! Just HATE people even hinting of editing theme files! Nothing but trouble.)

              May we could put a little box up “I want to put this script in my header area. I promise to be a good person, and that I have the right to do this, and that the script does only nice things. I am aware of security issues.”.

              But header.php must output everything from …

              typically

              . So what I’m talking about is the stuff in the site content header – title, image header, menus. That’s where an average user wants to easily add extra HTML and nice scripts, and where there is no way for a pluging to get access to the code that generates that content. A theme option is the only feasible way to do that.

            • Konstantin Kovshenin 8:31 pm on February 17, 2014 Permalink

              So what you are referring to is various places in the theme where users should be able to “inject” their inline javascript code. Can you provide more use cases to what a user would insert “after site title” and “above menu” and “before header image”?

              Also, have you considered adding custom actions to the various places you would like users to inject code, and then using a plugin to inject the js during those actions? Finally, if you’re looking at standardizing such actions across many themes, you should take a look at the “Theme Hook Alliance” initiative.

          • wpweaver 9:07 pm on February 17, 2014 Permalink

            OK – a use case. I can’t find the music player script I’ve used in the past, but…

            Let’s say there is a site – say Google Maps – that provides nice little scripts to anyone that supports its latest and greatest features. Features that one one has yet provided a plugin to do. So maybe not google, but say great-maps-startup.com. To use this new feature, you have add the script source somewhere – by lets say in the HEAD block. So my theme has an option “Add to HEAD Section”. The user copy/pastes the block right in there. (or the footer if it should be at the end.) A plugin could enqueue the script, but plugins don’t keep up with all the sites that do offer such scripts.

            And if you are fussy, and want to do exactly what you want to do, sites like Google Maps will generate exactly the script you need to show whatever map you want. Things a plugin might not do. Things someone who can read the instructions at the site can follow, and copy and paste.

            The whole point of allowing this option is to let the site owner make the decision, and have the tools needed to add scripts where they need to be added. We can’t predict every use case – just the fact is is that scripts exist on many small and varied sites that average, non-techie site owners want to copy and paste and use without modifying php code.

            And, of course, one could add actions or filters to the theme to appropriate places in header.php to avoid the explicit proposed requirement, and offer a recommended companion plugin to do that (which is of course what I will do if this requirement is added), but the ability to add JavaScript music players or maps at specific places on a site (presentation of that content in appropriate spots) does seem like something a theme should be able to offer.

            I think having to “sneak” around the content/presentation issue, in this case presentation of content in site locations unavailable via plugins – e.g. header.php, is something that by reality is only available to the theme. No one else can affect just what comes out in the HEAD section, or the header/menu section typically found at the top of themes.

            And such specialized plugins can be confusing to the user – it has to be very theme specific. Moving stuff that can only be handled by the theme (header.php) into a fake-out companion plugin seems a little intellectually dishonest – no matter what the intent.

            And of course, I believe we owe it to the average WordPress user to offer options that are accessible to anyone – not just techies who know how to write code, or modify theme php files. The platform has moved beyond the days that only the informed elite can create custom sites.

            • Konstantin Kovshenin 9:17 pm on February 17, 2014 Permalink

              To use this new feature, you have add the script source somewhere – by lets say in the HEAD block. So my theme has an option “Add to HEAD Section”. The user copy/pastes the block right in there. (or the footer if it should be at the end.)

              Sorry but I just don’t get it :) That’s exactly what the wp_head action does. It’s meant to output stuff in the head section of your theme. Or any other theme for that matter.

              A plugin could enqueue the script, but plugins don’t keep up with all the sites that do offer such scripts.

              A plugin can also create an “Add to HEAD section” which would function exactly the same as your theme – it would output custom javascript in the HEAD section of the site.

              Maybe this is just a bad use case…

            • Chip Bennett 1:53 pm on February 18, 2014 Permalink

              First, that script doesn’t belong in the *Theme*. It is by-definition Plugin territory. The user would presumably want to retain that great-maps-startup.com functionality/integration regardless of active Theme.

              Second: two simple solutions already exist to incorporate such a script properly by the end user – Child Themes and Site Functionality Plugins.

              Third: the appropriate way for Themes to support arbitrary injection of user code at defined template locations is via defined custom template hooks (such as the Theme Hooks Alliance is trying to standardize). Offering a companion Plugin is a perfect solution, and not some sort of “loophole” or “workaround”. Heck, I do this: I define action/filter hooks in Oenology, and have an Oenology Hooks Plugin to facilitate users hooking into the template.

              Fourth: you’re simply wrong about document head output. We require the wp_head() call to come immediately before the closing HTML HEAD tag for this very reason: to ensure that Plugins and the end user can have precise control over the order that scripts and stylesheets output in the document head. Nothing can bypass the wp_head priorities by injecting something after the wp_head() call in the document head.

              Finally: I believe in focusing efforts on teaching end users the proper and safe way to administer their sites, rather than providing inherently unsafe hand-holding features. Teach users how to use a Child Theme. Teach users how to write a simple site-functionality Plugin. Don’t facilitate unsafe practices.

      • Ulrich 7:00 am on February 18, 2014 Permalink

        You could add support for the Theme Hook Alliance
        https://github.com/zamoose/themehookalliance

        You could then create a plugin that allows people to insert HTML in those separate locations. That plugin would then be compatible with any theme that uses the Theme Hook Alliance.

        I think you need to make the difference between HTML and JS scripts.

      • Chip Bennett 1:43 pm on February 18, 2014 Permalink

        Use case, please? I simply don’t understand the issue you’re trying to describe. “Arbitrary” scripts are scripts added by *users*, over which the Theme has no control. (That’s why they’re *arbitrary*.)

        If a Theme uses a script, it can simply bundle it, and enqueue it via appropriate hook (wp_enqueue_scripts, wp_head, wp_footer, etc.). This guideline has zero impact on a Theme’s ability to incorporate and to use a bundled script.

        • wpweaver 6:21 pm on February 18, 2014 Permalink

          Chip said: “Teach users how to write a simple site-functionality Plugin. Don’t facilitate unsafe practices.”

          This is an elitist and egotistical comment, and demonstrates what I think is a “we know better than you” attitude common among many WP developers. Who are the users? Not the WP core development team. Not plugin writers, not theme writers. The users are the thousands of individuals who plug along the best they can with their own sites, slowly becoming more competent every day. They are the thousands of independent SITE developers who eek out a living building WP based web sites for many others.

          These people can’t “write a simple site-functionality” plugin. A child theme – seriously? But they do have an artistic eye, and with the right tools, can build pretty amazingly functional sites. Saying they aren’t good enough to do that because they don’t have the skills to write a plugin is just a bit too much for my ethics.

          And these people are artistic perfectionists. They know how to go to Google and use the webmaster tools there to generate a perfect Google map JS snippet they would like to insert in the site content header – things that no plugin can do. The want to EASILY, without writing their own plugin (because the can’t) insert a little script to tweak some styling. They want to use some custom JavaScript available for some obscure site to add something to the header or footer. Want to see some real life use cases: Look at this discussion: http://forum.weavertheme.com/discussion/8149/poll-do-you-add-javascript-to-your-site-using-head-section-or-other-html-insertion-options

          All your use case confusion seem to miss the fact that there are tons of little content JavaScripts that add content, and that aren’t/can’t be supported by a plugin.

          Using wp_head allows the right before the closing HEAD tag, but virtually every header.php file then goes on to define the header content (like the header iamge) as well – ain’t no filter gonna fix that. Let’s see – Twenty-XXX, Oenology, … – I couldn’t find a theme that doesn’t do that, actually.

          And, as one last bit of evidence of the folly of banning script insertion from header.php and footer.php, currently anyone one with unfiltered_html capability can insert whatever they want into a plain old Text Widget. What is the difference?

          MAYBE, if there is some day a great theme hook for inserting content in then banning script insertion from header.php and footer.php might make sense, but asking the average designer to write code? Elitist in the extreme. Right now there are plenty of great reasons that a web designer with limited programming skills will want to insert a script in the code generated by header.php and footer.php, but there are no API tools to support that unless a theme does it directly.

          But I guess all these people aren’t good enough because they aren’t real programmers?

          • Chip Bennett 8:31 pm on February 18, 2014 Permalink

            Guidelines don’t impact users; they impact Theme developers. Users can inject whatever code they want, anywhere they want, in whatever template files they want. Nothing here would prevent them from doing that.

            I fail to see how a statement that espouses a belief that end users are fully capable of understanding how to use a Child Theme or a site functionality Plugin is somehow egotistical or elitist. I think it is far more elitist to assert that end users are *not* capable of understanding or learning how to use Child Themes or site functionality Plugins, for example:

            These people can’t “write a simple site-functionality” plugin. A child theme – seriously?

            Personally, I’ll keep on believing that users are fully capable of using a Child Theme, or learning how to write a site functionality Plugin. Maybe we just need to be better teachers? Maybe we need to take the time to teach the *right* way to do things, instead of encouraging lazy and unsafe, blind copy-and-paste code usage?

            Users who need to inject such arbitrary scripts at precise locations in the Theme template can and should use a Child Theme to do so. It’s not even feasible for a Theme to account for every possible template location at which a user might need/want to add some code or script. The closest we get to that is a standardized set of template action hooks, such as Theme Hooks Alliance – and even then, the correct implementation is a hook callback via Child Theme or site functionality Plugin. Exposing Theme options to that effect represents a significant security vulnerability. Doing so also represents Theme lock-in, by placing user-generated content in a Theme option; if the Theme goes, so too goes the user-generated content.

            Using wp_head allows the right before the closing HEAD tag, but virtually every header.php file then goes on to define the header content (like the header iamge) as well – ain’t no filter gonna fix that. Let’s see – Twenty-XXX, Oenology, … – I couldn’t find a theme that doesn’t do that, actually.

            Actually, Oenology makes extensive use of custom filter and action hooks, including the ability to override the site header (image/text) completely. Several other Themes do likewise, including every Theme that implements the THA standard.

            All your use case confusion seem to miss the fact that there are tons of little content JavaScripts that add content, and that aren’t/can’t be supported by a plugin.

            There are Plugins that allow insertion of arbitrary scripts in post-content, via shortcode, which is the correct implementation. Themes don’t need to be involved in post-content javascript.

            And, as one last bit of evidence of the folly of banning script insertion from header.php and footer.php…

            Part of the issue here is that you’re conflating two entirely separate issues: insertion of scripts via wp_head and wp_footer, and insertion of content in arbitrary template locations.

            The vast majority of impact of this Guideline will be on scripts hooked into wp_head and wp_footer. There’s absolutely nothing “Theme-specific” about those hooks; they are standard, universal template hooks found in every WordPress Theme worth using. A Site Functionality Plugin (or Child Theme functions.php callback) is the correct way for the user to hook arbitrary scripts into wp_head and wp_footer. Not Theme Options. Looking at your poll/forum post: if you’re encouraging your users to add Google Analytics, Facebook Like scripts, etc. via your Theme options, then you’re doing your users a disservice.

            • wpweaver 11:12 pm on February 18, 2014 Permalink

              I give up. You obviously don’t see your own elitism.

              “Guidelines don’t impact users; they impact Theme developers. Users can inject whatever code they want, anywhere they want, in whatever template files they want. Nothing here would prevent them from doing that. ”

              User’s CAN NOT inject code wherever they want. In spite of how “easy” you might think PHP programming is, IT IS NOT. There are thousands and thousands of WP site designers who can figure out how to copy/paste a little JS snippet, but who just aren’t as smart as you are, and don’t find it easy to write a little plugin, or write a little child theme. So the need to be able to do that without programming is really there. Honest. There is no need to turn a site designer into a programmer. They aren’t even interested in learning to program, and why should they?

              (And on the other side, I don’t quite understand why there are so many WP folks who think that only programmers should design themes. There are some nice themes for sure, but I’ve not met that many programmers who are really good design artists. That’s why I deeply believe there should be themes with plenty of ways for non-programmers who really are design artists to build beautiful web sites without the need to learn to program.)

              I’m not encouraging or discouraging people for adding JS snippets. These people are control freaks, and can’t find a plugin that will do every single thing a particular JS API to some well-known or obscure site has to offer, but they can get the exact JS snippet to do what they want. They want to add the exact Google tracking code they want and not rely on an invisible plugin to do it – but they don’t want to write a child theme to do that. And why should they?

              So no matter if the theme has to use a back-door plugin, or THA_ or whatever, there is still content lock in to a theme. Until there is a more widely used (what was it – 6 themes listed using THA_? It is good to see Oenology is one) standard, it just seems to me it is sensible to make such insertion areas part of theme options.

              And really – this is a sincere question – what is the difference between inserting scripts in the content header, a text widget, a footer content area, or even a post? Does it really matter where the script is injected, from a security standpoint? I really don’t know how that can be true. If done via a theme injection option, or via a text widget – the site developer can actually see the scripts are there, so I can see that “hiding” it in the header is a valid reason.

              So is the real issue theme lock-in? Then let’s say that, and not hide behind security as the reason.

              I guess it is designer vs. techie, and obviously the techies are the gate keepers.

            • Chip Bennett 1:47 am on February 19, 2014 Permalink

              Sorry, still not accepting that this position is elitist. It is simply not elitist to espouse the belief that the typical end user is perfectly capable of understanding Child Themes and Site Functionality Plugins; in fact, such a belief is the polar *opposite* of elitism.

              But let me address the point of user programming skill that you keep bringing up: owning and administering a web site is not a matter of design; further, owning and administering a web site comes inherent with the responsibility to know what you’re doing. That means some basic understanding of things like web hosting, FTP, server security, and, yes: PHP (if using a PHP-based application such as WordPress). WordPress isn’t the Ron Popeil of web applications that magically turns self-hosting a website into a set-it-and-forget-it Showtime Rotisserie.

              It is bad and irresponsible of us as developers to encourage and facilitate bad practices such as “just copy and paste this code snippet”. It is good and responsible of us as developers to help educate users about the correct, safe, and future- (and theme-)proof methods of extending WordPress functionality.

              What’s so hard about teaching someone how to write a Site Functionality Plugin? Here, I’ll demonstrate:

              examplecom-site-functionality.php

              <?php
              /**
               * Plugin Name: example.com site functionality
               */
              

              All done!

              Now, how hard is it to teach someone how to add their Google Analytics script to the file?

              <?php
              /**
               * Plugin Name: example.com site functionality
               */
              
              function examplecom_google_analytics() {
                  // Code goes here
              }
              add_action( 'wp_head', 'examplecom_google_analytics' );
              

              That’s not hard – to teach, or to understand. Users can get it; we just have to put in a modicum of effort to explain why this is a better method.

              Now, let’s back this up a bit.

              First: scripts injected by the user at wp_head and wp_footer are *by definition* Plugin territory, because they are (by definition) not part of or dependent upon the Theme, and the user would want and expect those scripts to be retained when switching Themes.

              There’s really no getting around that. Google Analytics scripts and similar need to be maintained by the user, apart from the current Theme.

              Can we agree on that point, at least? That arbitrary, user-defined scripts intended to be hooked into wp_head and wp_footer don’t belong in Theme options?

    • Narga 2:29 am on February 19, 2014 Permalink

      Themes must not implement activation redirects, admin notices, or similar functionality.
      But I refer it redirecto Theme Option Customizer after actived because user can get Theme Preview and can change Theme Options

    • Frumph 4:57 pm on March 6, 2014 Permalink

      Yeah, no. -1 to the requirement of no theme redirect, as per cyberchimp and everyone else who also disagree’s. -1 to stating licenses of my own images. -1 “Themes must not save default settings to the database without explicit user action”

      These are all recommendations; should not be requirements; everything listed about in the requirements section.

      • Chip Bennett 2:51 pm on March 7, 2014 Permalink

        Can you articulate *why* you disagree with the things you list?

        Regarding redirects: there needs to be a core-defined workflow. In the meantime: Theme settings will *always* be in the same place (Dashboard -> Appearance -> Theme options (or whatever the Theme names the page) ), and we would far better serve end users by educating them about this standard location, than by allowing all manner of arbitrary workflows that will only serve to confuse users.

        Regarding licensing of your own images: that’s always been required. We’re merely specifying a standard location to provide that explicit copyright/license information. For developer-owned resources, a blanket statement is fine. You don’t have to list each image individually, or anything onerous. You simply need to state that, unless otherwise indicated, all images are copyright you, and licensed under [theme license].

        Regarding not saving default settings to the database: why do you oppose the requirement? Does it force developers to implement sane defaults so that the Theme works “out of the box” without user intervention? Yes. That’s the point. But it’s not a difficult change, at all.

        • tskk 3:00 pm on March 7, 2014 Permalink

          I have seen many reviews where reviewer doesn’t agree with statement like “unless otherwise indicated, all images are copyright you, and licensed under [theme license].”

          So if you can specify that its acceptable in the rules, it would be helpful in avoiding arguments.

          • Chip Bennett 8:49 pm on March 7, 2014 Permalink

            Why would such a statement be unacceptable, and why wasn’t it resolved in-ticket (or an admin brought into the ticket)? Of course such a statement is acceptable. The onus is on the Theme developer to ensure that it’s *true*; but assuming that it is, it is perfectly fine to make such a blanket statement.

  • Chip Bennett 4:14 pm on November 18, 2013 Permalink
    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 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 core 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.org/themes itself. We have one Theme directory to work with. We can recommend filter 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 Plugin’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.

     
    • nofearinc 4:25 pm on November 18, 2013 Permalink

      I’ve already expressed my thoughts last week, and I’m happy for getting this discussion in the public.

      I agree with most of your thoughts here. The only thing I’d like to outline is that: 1) the limitations of the existing infrastructure shouldn’t stop us from proposing new features that would bring value to the Directory, if we all agree on this, and 2) we could express these thoughts of yours (such as “All we ask is that developers email the mail-list and ask for an exemption, along with explaining the justification”) in a more public manner.

      Otto is mostly in charge of http://meta.trac.wordpress.org/ and I believe that we could propose some changes (and texts, which is easy) to improve the process with time. That’s valuable only if we are on the same page when it comes to the state of themes and it makes sense to build a roadmap that slowly gets into the infrastructure.

    • tskk 4:30 pm on November 18, 2013 Permalink

      We need new tags, frameworks can be added under a new tag, KB themes can be added under a new tag etc…

      Getting new tags should be doable and first step.

      • StyledThemes 5:08 pm on November 18, 2013 Permalink

        That would be great. Actually the tags need an overhaul…I already know of one that should be added: responsive

      • StyledThemes 5:21 pm on November 18, 2013 Permalink

        You pretty much got to the point of some changes would be great but as you mentioned as one idea:

        “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.”

        That would be a great one actually; one for the current basic themes, then another for the more professional designed themes (free of course). It would be nice to also have the theme pages like the Plugins have for layout and information. I’d even like to see that Preview system abolished as it does not do justice for themes…make it a link to a live demo site instead. There’s a lot of ideas that can be presented but as you said, the infrastructure is not there…perhaps this is something that should be looked into at some point and have a scalable solution in place.

        Anyway, as for the Blog or cms topic, I never really noticed that there was focus more on blog themes (or the appearance of) and never gave it much thought. I know for my themes I make them for both uses. I’ve had some people as me if my themes can be used without the blog and the answer is definitely yes. I am seeing a growing number of people looking to the cms theme solution, but it’s still important to maintain a blogging capability within themes should one decide to use it.

        • StyledThemes 5:22 pm on November 18, 2013 Permalink

          sorry…not sure why or how this reply got posted here, it was meant for Chip’s first opening post.

    • Zulfikar Nore 4:34 pm on November 18, 2013 Permalink

      Agreed +1

      I’ve hated each time I’ve had to ask an author to reconfigure their theme so that it handles the “Blog” as intended. Personally I see nothing wrong with a theme having a custom front page with the blog handled on another internal page.

      Not only will this move simplify the review process but it will also facilitate the ability for authors to submit custom (non bloggy <- if that's even a word!) themes. I would totally welcome the chance to do so myself :)

      And since we have from having the TUT being a required element of the theme approval process, dealing with CMS type themes shouldn't too tasking on the team as whole.

      • Zulfikar Nore 4:36 pm on November 18, 2013 Permalink

        EDIT: And since we have “moved” from having the TUT being a required element of the theme approval process, dealing with CMS type themes shouldn’t too tasking on the team as whole.

        • Chip Bennett 4:37 pm on November 18, 2013 Permalink

          We already can deal with “CMS” Themes. But if the only defining difference for a “CMS” Theme is that it omits support for the blog, that’s not a reasonable enough difference to warrant an exception.

          • nofearinc 4:44 pm on November 18, 2013 Permalink

            IMO it’s not really the “omits support for the blog”, but rather focusing on other, business-theme related details, and not covering some details from TUT. The “Recommended” status of the TUT would facilitate that process, especially if there is a major shout-out to theme developers for the new decision and the willingness of the TRT to help CMS theme authors without being too picky and restrictive (just as is with UI comments for reviewers that are subjective).

      • Chip Bennett 4:37 pm on November 18, 2013 Permalink

        But that’s kind of the point: there’s no change happening here. I’m mostly just trying to dis spell some misconceptions.

    • Subharanjan 4:50 pm on November 18, 2013 Permalink

      “”” 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. “””
      — Can we have some rules for themes of different kinds to be accepted after approved by 5 reviewers.
      — If approved, it should be allowed to use custom theme unit test data to better match its functionality and design.

      • Chip Bennett 5:04 pm on November 18, 2013 Permalink

        I don’t understand the need for 5 reviewers?

        Also: The Theme Unit Test data are what they are, and they are used only so far as they serve their purpose. There really isn’t a need to “specialized” Theme Unit Test data for custom Themes. Are you referring to the Theme Previewer, by chance? That’s something else we don’t have control over.

  • Chip Bennett 1:25 pm on November 12, 2013 Permalink
    Tags: Guidelines   

    Theme Unit Tests: Recommended 

    Based on the recent discussion prompted by @lancewillett, the following change has been made to the Guidelines, effective immediately: the Theme Unit Tests have been reduced in criticality from Required to Recommended.

    We believe that this change will help eliminate a source of subjectivity/inconsistency in Theme reviews, while ensuring that review effort focuses on the truly required criteria. And in all honesty, almost everything that is truly required in the Theme Unit Tests will be found during the code review. In the future, this change may allow us to re-focus the Theme Unit Tests on recommended/best-practice design/aesthetics, without introducing further subjectivity into the review process.

    Please note that this change does not impact any of the rest of the Guidelines; only the Theme Unit Tests specifically. And during reviews, Themes should still be checked against the Theme Unit Tests, any conformance issues should be noted as Recommended as part of the review, and Themes will still be required to document any extraordinary design limitations.

    As a reminder: when conducting a review, please ensure that Required criteria are clearly stated, separately from recommendations or other comments, to ensure that those required criteria are clearly communicated to the developer. (A bullet list of required items usually helps.)  Reviewers are welcome (and encouraged) to leave other recommendations or constructive feedback for developers, but we need to ensure that developers know exactly what is needed in order for Theme approval.

    As always, thank you, all, for your continued contributions!

     
    • Rohit Tripathi 2:26 pm on November 12, 2013 Permalink

      As an Author. I really appreciate this update. This eliminates the problem of us having to do certain things, which we don’t want to. Like styling the sticky posts. Some themes just don’t have a different looking sticky post. Smart Decision to make the unit tests recommended.

      • Chip Bennett 2:30 pm on November 12, 2013 Permalink

        See, that’s part of the problem: you’ve *never* had to style sticky posts in any particular way. All that is required is including the `.sticky` CSS class (even if empty). It demonstrates that the sticky-post case was considered, and factored into the design. The ultimate design decision, though, has always been left up to the developer.

        So, that sort of subjectivity/misinterpretation of the Guidelines is exactly what we want to avoid.

        • Rohit Tripathi 2:40 pm on November 12, 2013 Permalink

          Well, I completely agree to the fact that you have always left the things which are a design decision to the authors. But, there are certain things regarding the Unit Tests which have been misleading to us as reviewers.

          A Particular line on the Unit Test says that, “The sticky post should be distinctly recognizable in some way in comparison to normal posts.

          A Normal person would interpret that as: styling the sticky posts is reqiured. Otherwise, how else can we make them distinctly recognizable.

          I am sure, this current step to make the unit tests recommended would avoid all the subjectivity/misinterpretation there exists regarding this.

          • Chip Bennett 3:03 pm on November 12, 2013 Permalink

            Again, part of the problem: the TUT wording was never standardized against the Required/Recommended wording in the rest of the Guidelines. So educating reviewers on how to treat the TUT was an ongoing struggle.

    • Edward Caissie 3:39 pm on November 12, 2013 Permalink

      I agreed this was a good move to make with the Theme Unit Tests (TUT) as well.

      I think it will actually provide for more interesting design ideas being brought forward as Theme Authors should feel more at ease with their design aspects that may have been unintentionally stifled by misread or misconstrued TUT content being considered as Required versus the (original ideals of) Recommended.

      I’m looking forward to what we will see next …

      • Emil Uzelac 7:45 pm on November 12, 2013 Permalink

        Same here and definitely good move. This will help everyone.

    • Lance Willett 4:28 pm on November 12, 2013 Permalink

      Thanks for the clarification, Chip. I agree with Cais it’ll hopefully mean less stress on theme designers and reviewers, and remove a bit of the friction to getting themes into the directory.

    • rclilly 6:36 pm on November 12, 2013 Permalink

      I think this is a good move that, hopefully, will reduce the subjectivity in the theme review process while at the same time continuing to ensure that the themes that do pass are of a high enough quality to warrant being included in the official repository. Users need to be able to trust that each and every theme they have access to from the “Install Themes” admin area meets, or exceeds, a minimum set of standards.

      My hat is off to all of you theme reviewers as well as to every person who has even attempted to submit to the repository. Without people like you the WordPress ecosystem wouldn’t be the thriving entity that it is.

    • @mercime 9:21 pm on November 12, 2013 Permalink

      I have to disagree with the decision to make passing the Theme Unit Tests recommended only.

      To sacrifice the interests of the many WordPress.org users to the altar of a few theme designers who cannot deign to improve their themes by supporting core WordPress elements is a retrogradation. Many issues seen in Theme Unit Tests can easily be fixed with CSS tweaks only. This a great imposition on the designers? Really?

      What are some of the consequences of making Theme Unit Tests optional?

      As Otto and Chip already mentioned in the previous post, Matt had said that we’re not looking for all Themes for the directory, but rather the best. Do themes which do not also pass the Theme Unit Test represent the “best” of WordPress? I think not.

      I also bring your attention to the Usability Guidelines of the WordPress.com Theme Guide http://developer.wordpress.com/themes/ To quote:
      “The WordPress.org Theme Unit Test Data is comprised of multiple posts and pages designed to push your theme to the limits. Please download the data and import to your test server. Running your theme through all of the provided tests can help ensure that your theme will be flexible enough to handle a wide variety of actual user data.”

      To summarily demote the Theme Unit test to recommended or optional for WordPress.org users now, after all these years, is like saying that WordPress.org users are unimportant second-class citizens compared to the WordPress.com users. What kind of hospitality is WordPress.org showing by serving up half-baked themes to the end users? It’s just like:

      • serving Dom Perignon to WordPress.com users but serving vinegar to WordPress.org users
      • serving prime Kobe beef to WordPress.com users but serving scrap meat to WordPress.org users
      • serving perfect Tiramisu to WordPress.com users but serving stale crumbs to WordPress users

      Have mercy on the WordPress.org users. Bring back passing Theme Unit Tests as a requirement before a theme is distributed in the WP Theme Repo.

      Allow the all-volunteer WP Theme Review Team to continue to serve the WordPress.org users the same way Automattic employees serve the WordPress.com users by providing users with themes which pass quality controls. That’s all.

      • Zulfikar Nore 12:57 am on November 13, 2013 Permalink

        +1

        I’m in total agreement with @mercime.

        Taking this post I’ve already been challenged on one ticket regarding fallback on Site title in the absence of a logo. Continuing to hold the above view and keeping TUT as recommended will only increase friction and not reduce it.

        I’m willing to work with theme authors and even compromise on some points but not all and certainly not at the expense of the end user experience – they are the ones we (authors and reviewers) are here to serve!

        Please reconsider.

      • Justin Tadlock 10:11 am on November 13, 2013 Permalink

        Theme designers don’t have to make sure that image which is center-aligned in editor is center-aligned in front end. After all, fixing this is only recommended. http://themes.trac.wordpress.org/attachment/ticket/5573/limitless-images-not-center.jpg

        I just wanted to point out that this specific example is not optional. According to our guidelines (not the theme unit test data), WordPress-generated classes, such as .aligncenter, must be supported.

        • Zulfikar Nore 2:07 pm on November 13, 2013 Permalink

          And that is where the TUT plays its part in exposing such issues, no?

          • Chip Bennett 2:16 pm on November 13, 2013 Permalink

            That can be found just as easily during code review, especially for things highlighted by Theme Check.

          • Justin Tadlock 4:04 pm on November 13, 2013 Permalink

            You can check with the Theme Check plugin, the theme unit test data, or your eyes. Whatever method is fine by me. I just wanted to make sure anyone reading that example got the correct information.

      • Piet 1:49 pm on November 20, 2013 Permalink

        +1

      • Piet 1:57 pm on November 20, 2013 Permalink

        The real shocking issue here is – and imo (at least part of) the reason why all of a sudden the TUT are recommended instead of required – that a developer of a default theme does not pass the TUT.

        So instead of repairing a broken default theme, the rules are just flexed a bit, so the theme can pass.

        • Chip Bennett 3:22 pm on November 20, 2013 Permalink

          In all honesty, no Theme would be “not approved” if the only issue was a too-long title not being handled properly. For a long time, our stance has been to note such issues as being required fixes in the next Theme revision, and approving the Theme.

          So, no: the TUT was not made “recommended” merely to allow Twenty Fourteen to pass. There would be no need to do so. If those above the WPTRT paygrade wanted a core-bundled Theme to be made live even with outstanding Theme Review issues, it would be made live regardless.

          The discussion may have been prompted by the Twenty Fourteen issue, but the decision was made independently of that issue.

  • Lance Willett 4:37 pm on November 10, 2013 Permalink
    Tags: , Guidelines, reviews   

    Guidelines Shouldn’t Fail a Theme 

    Chip’s great post on Points of Emphasis and a recent discussion about a specific Theme Unit Test guideline (failing themes with long titles that overflow) point to a need to change our attitudes to the theme review guidelines.

    If you step away from that specific Trac ticket and look at the bigger picture you’ll see a change is needed to make all WP theme reviews less dogmatic and more pragmatic; not only WP.org directory but also for WP.com, ThemeForest, MOJO, any other marketplace that accepts some submissions and rejects others.

    The items in the Theme Unit Test are guidelines not hard and fast rules. Highly recommended and encouraged and we should feature and love and promote the themes that nail them all. Shout from the mountaintops if a themer manages to achieve the full list! Themes that don’t nail them all can sink to the bottom of the list organically because people might end up not liking them as much.

    Guidelines shouldn’t cause a theme to fail or be prevented from being in the directory. That should be limited to blockers like licensing, security, and spam/malware. What Chip said.

    By letting theme designers choose to implement guidelines in full—or not—you give the power to end users to vote for the best ones by activating them. Instead of keeping out hundreds or thousands of potentially amazing themes that fail the too-strict rules we have now. The themes—and the people behind them—that we lose out on might never come back; and there’s evidence this has happened many times already.

    Changing a strict philosophy of enforcing guidelines as rules to encouraging more experimentation and variety will go a long way to remove negative friction from reviews and make the themes in the collection better in the long run.

    In summary: let’s enforce the “Points of Emphasis” (security, license, no spam) and leave the rest as recommended guidelines. We absolutely love if you follow them all, but none are blockers to your theme being included in the directory.

     
    • PankajAgarwal 4:44 pm on November 10, 2013 Permalink

      You have taken a very right decision, I am completely agree with all your point..

    • Samuel Wood (Otto) 4:46 pm on November 10, 2013 Permalink

      I’m going to have to disagree with you here, Lance. The purpose of the review process is to improve the quality of the themes in the directory in general. As Matt once said, the themes directory should contain the best themes, it doesn’t need to contain all themes.

      Most of the guidelines listed are indeed blockers, because they specifically are there to address perceived breakages. When a theme wants to make a design decision to have certain colors or layouts or what have you, that’s obviously not something to be questioned. But when it doesn’t want to include next post links or widget support, then that’s where the interface of WordPress itself gets broken by something the theme is doing.

      The specific issue in question for Twenty Fourteen is the title overflow problem. And while I agree with your response in that ticket that it is an issue with the unit test, I disagree that it is not a problem in the theme itself as well. While the question of how to handle overflow properly is indeed up for debate, what I don’t see as up for debate is the fact that not handling it at all is a poor decision that leads to a broken theme. Yes, it’s an edge case, but it’s a case that should be properly handled. If the proper handling is to say “we want to allow overflow to happen”, then that’s fine, but that needs to be explained properly instead of being shrugged off.

      So no, I have to disagree with you and say that the theme reviewers should continue to strive for a minimum level of quality and to continue to raise the bar and improve the quality of themes in the directory as a whole. And if a theme doesn’t adequately address issues like these, or have meaningful responses to back up why they think that these are design decisions, then yes, they should be not-approved and not allowed in the directory.

    • Chip Bennett 4:52 pm on November 10, 2013 Permalink

      I could buy into this approach for the Theme Unit Test Data, but everything else in this list is required for good reason.

      • Lance Willett 4:59 pm on November 10, 2013 Permalink

        Yes, this is for the guidelines in the Theme Unit Test.

        That said—I think most themers would agree with me, and “would-be” themers especially, that other list could stand to be much shorter. It’s scary long and intimidating.

      • Lance Willett 5:02 pm on November 10, 2013 Permalink

        • Chip Bennett 5:09 pm on November 10, 2013 Permalink

          Yes, and complaining on Twitter is quite helpful. The Theme Review Team is comprised of almost 100 volunteers of varying level of Theme development expertise and review experience. Of course it’s not possible for all reviews to be conducted with 100% consistency – though we certainly strive for that, and try to address all meaningful inconsistencies as we are made aware of them.

          The remedy for an inconsistent or incorrect review is to respond in-ticket and work through any issues directly with the reviewer – and if that doesn’t work, to post to the mail-list and ask for an admin to intervene.

          Sadly, random tweets aren’t something that the TRT admins are able to monitor; so Tweeting about issues really doesn’t solve anything.

          • Lance Willett 5:12 pm on November 10, 2013 Permalink

            It’s still valid. No matter what the communication channel, it’s a human being and a voice that should be heard. (Yes, we can also ask Andy Peatling if his Dad wrote up a long-form treatise on his negative intro to WPTRT and WP themeing.)

            • Chip Bennett 5:18 pm on November 10, 2013 Permalink

              With all due respect: “totally broken” is not valid. Since the approximate date of that post, 330 Theme developers managed to navigate the review/approval process for new Themes.

              Is the process perfect? Of course not. It is nearly impossible for the process ever to be perfect. Those who want to help improve the process can avail themselves of one of the many communication channels to provide constructive criticism of the process. (That happens quite frequently, and generates a lot of beneficial discussion, and improvements.)

              Those who just want to rant, and not make any effort to bring issues to our attention so that we can address them? Ain’t nobody got time for that.

    • Edward Caissie 5:02 pm on November 10, 2013 Permalink

      This is definitely a double-edged sword of a discussion whereas I agree with Otto on his points, I can also see validity in the points Lance is bringing about for discussion.

      I, as a Theme Review Team administrator, do not agree with all of the guidelines currently in place (more specifically one that is unfortunately much too long standing) and to be honest it was quite a labored decision whether or not I would continue to have the theme hosted in the repository. (It may be a small item but one I think to be very important.)

      I took my opinion to the appropriate venue for discussion and the majority insisted the guideline was a required restriction on what I consider more an author’s choice and as such the theme remains in the repository but I struggle with this decision for the theme to remain in the repository every time I review it for updates and re-submission … forcing me to use a Child-Theme on my own site(s) because the theme’s native form does not suit my opinion of what the it is meant to display (a content related presentation aspect) and accomplish.

    • StyledThemes 5:25 pm on November 10, 2013 Permalink

      I can understand the need for standards in WordPress coding methods are important, as well, ensuring that most (not necessarily all) of the important features and functions of WordPress becomes part of a theme.

      However, I agree that the review test is extensive and can be intimidating for the new themer. In fact, I almost didn’t go through with submitting my first theme because when I saw the list, I was like wow! Granted, for me it wasn’t as bad as it might be for some others because I came from the Joomla platform and standards are important and I was already used to the idea that it’s going to take more time to put something together for WordPress.

      I totally agree that submitted themes need a review process to ensure proper coding standards are in place that relate to how WordPress works, ensuring that the core basic features of WordPress are part of the theme for continuity regardless of the theme being activated for a user. Perhaps some minor tweaking is needed, but I think for the most part it does help for quality code standards.

      The only one big issue I have is that the review process seems to focus too much on the review list of guidelines and looks away blindly when it comes to the visual design of the theme. When I look at the list of themes in the repository, it’s kind of shameful to see so many themes that look so basic and plain, yet all look the same. I strongly believe that themes submitted should have overall design and creativity included in the review process….almost a 50/50 split of coding quality as well as design. The repository is filled with (I’m really sorry to say this) themes that look like they were designed by people who have absolutely no creative design abilities, and it’s filling up the repository with themes that should not be there.

      A friend of mine found an online tool that can search the net for sites that uses themes. What he found out was scary and might prove some points that the majority of the themes are not being used. Sure they get downloaded a lot but on average, only 3-5% are being used on sites with select themes.

      What I would like to see is more emphasis on visual design and features, and I bet the WordPress repository would be seen a place for serious website and business owners to explore and download professional looking themes. Something to compete with the likes of Theme Forest, Mojo, etc.

      • tskk 5:29 pm on November 10, 2013 Permalink

        What is beautiful is extremely subjective and giving importance will only end up in trouble.
        Can i have the link to this tool you are talking about?

      • Chip Bennett 5:32 pm on November 10, 2013 Permalink

        What I would like to see is more emphasis on visual design and features, and I bet the WordPress repository would be seen a place for serious website and business owners to explore and download professional looking themes. Something to compete with the likes of Theme Forest, Mojo, etc.

        I completely understand where you’re coming from, but it’s not something that’s practical. Design/aesthetics are completely subjective, and it is difficult enough to get conformance to objective guidelines – and to ensure that all reviews against those objective guidelines are consistent.

        I think any design/aesthetic considerations would have to be a second level of curation, over and above the quality guidelines that Themes must pass in order to be hosted in the Theme directory. I’d be fully in favor of such second-level curation, but we don’t really have the tools or infrastructure in place to make that happen.

        • StyledThemes 6:09 pm on November 10, 2013 Permalink

          I understand what you are saying Chip…it really would end up having the requirement of a second level, but then it becomes who would be qualified to do just that, would require unbiased individuals having a design background. Changing something or adding something of this level at this point in time definitely would be a huge undertaking, but not impossible. It would be something in a sense where the design review process happens as a 1st level and if passes, then it goes to level 2 for code reviewing.

          For the record though, with the current review process, the one thing that stands out above sites such as Theme Forest, Mojo, etc., is that the review team takes the time to go through your theme code and often finds things that were missed. But they also continue to provide possible solutions and point out where the issues are, and I believe that is a huge bonus when being reviewed. I still encounter and shown things I missed, but that definitely helps make me more aware with each theme I submit.

          • alex27 7:47 am on November 11, 2013 Permalink

            I also wanted to talk a little about the design quality. It’s true that ultimately users decide on the themes that they like best, but with the amount of poorly designed themes out there it’s just too difficult and too time consuming for the average user to find them. I have a very hard time convincing people that it’s worth the effort and why they should not discard official theme repo out of hand .

    • tskk 5:34 pm on November 10, 2013 Permalink

      All rules in http://make.wordpress.org/themes/guidelines/ have reasons and are easy to follow.
      There are other rules we point out during reviews, wish they are added to the above list so there is less friction during reviews.

      • Chip Bennett 5:41 pm on November 10, 2013 Permalink

        That’s actually intentional. The top-level Guidelines page is intended to be a one-page synopsis of the Guidelines. The sub-pages are used to add any needed clarification/elaboration.

        If there’s anything not covered on the sub-pages, please let me know and we’ll be sure to address it.

    • rclilly 6:46 pm on November 10, 2013 Permalink

      Lance, while I agree that we need to remain aware that theme developers are humans, and that reducing friction in the review process is highly desirable, it doesn’t appear that the current guidelines present too big of a barrier to entry. The theme reposistory should be a sacred place where only themes that meet the guidelines should be allowed entry. We need to be able to trust, without subjective voting up or down, or having to do research, that any given theme in the repo has conformed to a clearly established set of guidelines and it’s presence in the repository is justified.

      Rather than lower the barrier to entry, I believe it’s in everyone’s best interests, including aspiring theme developers, to have to learn what’s required to get a theme approved and then do that. If help is needed to meet one or more guidelines then education is in order, not a dismissal of the guidelines.

    • alex27 7:20 pm on November 10, 2013 Permalink

      While I agree that guidelines may by intimidating to new themers, I don’t think that’s a bad thing. If nothing else, it shows good practices and gives something to strive for, puts a (moderately) high bar. For me undergoing the process of theme review was and still is a great learning experience, and I’m happy when I someone points issues with my themes to me. And theme repo is all the better for it.

    • nofearinc 8:04 pm on November 10, 2013 Permalink

      I tend to avoid conflicts and long discussions as much as possible, but occasionally I’m happy that we have those conversations in public.

      If we focus on the specifics, I completely disagree that this is an edge case for two reasons. First, I have sites that have long titles and take care of medical/bio latin terms, eCommerce stores with some long ID numbers of products etc. Especially for responsive themes where the content area is with a variable width. Not to mention that it’s in the guidelines, which we already mentioned.

      The tricky part though is that I fully agree on the fact that the reviewing process is too tight and people have different views on how this should work. We could see some examples in the comments above by Otto, Chip, Lance and Cais. My statement is a mix of the ones above, or rather – I believe that part of the guidelines are irrelevant, such as “Page With Comments Disabled” or “Clearing Floats” from the test data where I personally see too much regulations and specific cases, and there are too many definitions with “sufficient” and other subjective words that the most pedantic reviewers use to close themes. Part of them lead to annoyed theme authors leaving the repository for good or starting long discussions in the tickets or the mailing list.

      All groups related to the Foundation are actively trying to get people on board, encourage contributors in all aspects and actively update and enhance regulations to make that possible. Restricting authors for tiny subjective details or hundreds of guidelines is not quite constructive from my perspective, as I would agree with Lance here that the basics (spam, security etc) should be the REQUIRED and everything else is “should be taken care of in the next updates” or something.

      As for the “edge cases” which are the current official topic, my personal goal is to allow for people to get all the best options in the open source world. That means – Linux stack, WordPress website, themes and plugins from the official directories, etc. We teach WordPress to students, charities, even foster children where the line between $0 and $1 is infinite. Everyone could get premium themes/plugins and tools/services later, but it’s important to provide working and reliable products for students and newbie users (and starting developers from countries with economical issues). So far getting a free theme on a site, using it for 2 years and ending with a title breaking the UI on a popular blog of a non-technical user is embarrassing and disappointing, especially by the very official theme.

      The last thing I usually mention every few months is that WordPress is already considered a CMS and people already try to utilize it as an application platform, whilst we still try to enforce dozens and dozens of blogging-related regulations. There is no way in the current theme directory to list/apply with business/CMS themes (as there is for BuddyPress ones) and let developers focus on real business websites rather than blogs with optional templates for business sites.

      • tskk 8:37 pm on November 10, 2013 Permalink

        Just as the issue of long title is important to you, page with comments disabled is important for someone else :)

    • Emil Uzelac 9:26 pm on November 10, 2013 Permalink

      Not to mention that lowering the standards will bring less work for reviewers and more for WPORG support. Process isn’t perfect but it works :)

    • Japh 10:11 pm on November 10, 2013 Permalink

      Interesting post, Lance. It’s certainly important to be sure we question the status quo from time to time.

      I agree that there need to be occasional exceptions to the rules, but I also think that generally the rules need to be there. On ThemeForest, our WordPress Theme Submission Requirements are just that, requirements. We deliberately didn’t call them “guidelines”, because while there may be the occasional exception, by and large we need them to be met to help ensure a certain level of quality and compatibility.

      We’ll also be updating them shortly based on some of the feedback we’ve had, which is also an important part of the process.

      Quality and compatibility with the rest of the ecosystem are some of the primary drivers for keeping this level of checking in place, and I don’t think those are acceptable casualties in the pursuit of a more frictionless process.

      • Japh 5:14 am on November 11, 2013 Permalink

        I should also clarify that I think ThemeForest, and other commercial theme providers, are a poor example for this. If money has been exchanged, there’s a different level of expectation.

    • Andy Peatling 2:36 am on November 11, 2013 Permalink

      Great post Lance. I think your post and comments here highlight some fundamental differences of opinion when it comes to the vision of the theme directory.

      My recent experience was a dramatic shift from a few years prior, and resulted in my frustrated tweet linked in the comment above. Here’s how it came about:

      I remember being so excited and energized from releasing my first WordPress theme. I was instantly bitten by the bug. It was the catalyst for my obsession with WordPress and everything I have worked on since. My first theme was poor, but I learnt a ton from all of the feedback, it made me a better designer and WordPress developer.

      I have been teaching my dad programming and WordPress over the past year. I knew having him build and release a theme would provide the same boost and energy needed for him to become as obsessed with WordPress as I am.

      It was tough work from day one.

      I taught him the absolute basics for a functioning WordPress theme. He made sure all base functionality worked correctly, I gave it a double check, we uploaded it.

      Instant fail.

      We were presented with a laundry list of small problems that needed to be addressed before he could even upload the zip file. For someone starting out with WordPress this was incredibly off-putting. He admitted he would have given up there if I hadn’t have stepped him though it. There were a few things we missed that did need to be fixed, but most of the items on the list I would have considered minor issues and nothing that stopped the theme from functioning at a respectable level.

      We fixed issues, re-uploaded, and failed the test a few more times. Zipping up on a mac and the auto-testing script do not play well. Finally we got the zip uploaded. We were into the review process.

      Over the course of four reviews we interacted with three different people. Each person re-reviewed the theme and came up with a whole list of new things that needed fixing each time. I cannot highlight enough of how infuriating and demoralizing this is. It is an absolute momentum killer and sucks the life out of the person who is new and trying to learn. Without me my Dad would never have made it through these steps, which is a terrible shame because all of the items in the review were not blockers and could have been updated later (more on the updated later bit in a sec).

      After a week or so of frustrating back and forth we finally got the theme in the directory. At this point I thought all was lost for being bitten by the WordPress bug. The opposite was actually true, my Dad’s theme was downloaded more than a thousand times in the first three days. He could not have been more excited and couldn’t believe that thousands of people were using something he had built. Now he loves WordPress and has come on leaps and bounds since.

      So despite the pain of going through all of the steps, he still eventually experienced the same rush I did all those years earlier. If I had not been there showing him how to fix all the minor issues, he would never have made it here, and almost certainly would not be working with WordPress still (he may even have given up on the dream of being a web guy entirely).

      Having said that, he has not updated the theme since. I just asked him why. He said — “I have no enthusiasm to go through that process again, it’s too demoralizing”. I think that speaks volumes.

      • Andy Peatling 2:43 am on November 11, 2013 Permalink

        Based on the experience with my dad it’s clear to me that the current process is turning off potential new WordPress designers and developers that need that early encouragement to keep persisting with the platform.

        For me, encouraging new designers and developers into the WordPress community should be one of the primary goals of the repository. Allow new theme developers to feel the rush and excitement of people using something they have built as soon as possible. There is nothing else like it.

        Yes there will be a lot of junk, but as Lance said put the power in the hands of the end-users. The cream will rise to the top and new folks won’t be put off.

        • Justin Tadlock 5:11 am on November 11, 2013 Permalink

          I’m right there with you, Andy. I’ve talked with numerous theme authors who are or have been in the same boat as your dad.

          I’ve got about a 2,000-word essay on this subject. I’ve just been trying to narrow it down to the essentials and decide whether I even want to post it at all.

          • Lance Willett 4:11 pm on November 11, 2013 Permalink

            Please post it, Justin—everyone’s voice needs to be heard. Especially if they aren’t well known or new to the community.

        • alex27 9:57 am on November 11, 2013 Permalink

          I don’t think that cream will rise to the top, unfortunately. As it is, it’s very hard to find good (visually and code wise) themes and from my experience – people just don’t bother. The reason too much junk/very basic/generic themes.

        • Chip Bennett 1:39 pm on November 11, 2013 Permalink

          I don’t think the Theme Directory – at least in its current form – is the best or appropriate place for that. I agree that the project needs a way to encourage new developers to make contributions, but that encouragement shouldn’t come at the expense of end user experience with Themes installed from their dashboard – Themes that have the implied endorsement of WordPress itself.

          Just as I would like to see some second-level curation for beautifully designed Themes, perhaps we need some sort of “step below” repository to fill this need as well: somewhere to encourage/facilitate new developers to contribute their work to the project – somewhere that isn’t integrated into end users’ dashboards. Because while I agree that it is laudable and desirable to encourage such contributions, the Themes that WordPress core offers to end users should be of the utmost code quality.

          It’s not a good experience for end users to install Themes from their own dashboard – again, Themes with the implied endorsement of WordPress core – that then adversely impact their experience with core, or that interfere with their installed Plugins. It is frustrating for end users, reflects poorly on WordPress itself, and creates needless support issues for core, Plugin, and Theme developers.

          Ultimately, encouraging new designers and developers into the WordPress community is a laudable goal, but the primary goal of the Theme Directory must be to enhance and facilitate a great end-user experience. Any other goals will necessarily be subordinate to meeting end users’ needs.

      • tskk 3:05 am on November 11, 2013 Permalink

        Update process is not as rigorous as initial process.
        Even the initial process now is not same as a few months back, as now reviewers get rewarded and are eager to help new themes in. Now all the power is with theme authors. Now only reason for theme to not get in is that theme authors are either lazy or stubborn.
        Link to your dad’s theme please, let see it :)

        • Justin Tadlock 5:22 am on November 11, 2013 Permalink

          Now only reason for theme to not get in is that theme authors are either lazy or stubborn.

          That’s not entirely true and is the type of attitude that has been and continues to be detrimental to the theme review community.

          There are some major philosophical differences in viewpoints between not just theme authors and reviewers but between the various reviewers on our team.

          I’ve got numerous theme design/dev ideas that I know wouldn’t get through the review process. Either that or I’d have to spend multiple days arguing in the theme reviewers mailing list to make people less familiar with the WordPress code base understand. So, I simply don’t bring them up and stick to some of the one-size-fits-all rules we have.

          That has absolutely nothing to do with being lazy or stubborn.

          • alex27 7:14 am on November 11, 2013 Permalink

            Maybe it’s time to bring everyone on theme review team up to speed about general philosophy, any guidelines are secondary to that.
            I think you should upload your more creative themes – the attitude among reviewers has changed a lot lately, so it might not be as difficult process as you think. It would also help if theme authors described their ideas and out-of-the-box design/dev decisions upfront in the ticket (theme descriptions tend to be a bit ambiguous in that regard), not only after reviewer comes back with a bunch of issues.

          • nofearinc 10:03 am on November 11, 2013 Permalink

            I’ve even seen cases where reviewers (not admins) step onto tickets of other reviewers, adding additional subjective details to be verified. From the outside it looks like there is a superior level of reviewers who supervise and monitor the others, it demotivates regular reviewers as well.

            • Justin Tadlock 10:29 am on November 11, 2013 Permalink

              I’m guessing this is directed at me since you replied to my post. Or, maybe you meant to reply to someone else??

              We’ve always held that in-ticket replies are the appropriate way to handle things rather than taking discussion to the mailing list first.

            • nofearinc 10:54 am on November 11, 2013 Permalink

              Yep, that’s an addition to your comment about:

              I’ve got numerous theme design/dev ideas that I know wouldn’t get through the review process. Either that or I’d have to spend multiple days arguing in the theme reviewers mailing list to make people less familiar with the WordPress code base understand. So, I simply don’t bring them up

              And I’m not talking about in-ticket replies, but a review after another review for subjective details that are under consideration.

            • Justin Tadlock 11:30 am on November 11, 2013 Permalink

              Sorry, I don’t follow.

            • nofearinc 12:11 pm on November 11, 2013 Permalink

              I’m saying that not only is the theme review process long and thorough, but a second reviewer could chime in and add more things to be fixed. Demotivating for the author and the first reviewer, and most of that could be subjective and not necessary.

            • Chip Bennett 2:00 pm on November 11, 2013 Permalink

              Demotivating for the author and the first reviewer, and most of that could be subjective and not necessary.

              …and this is why I could buy into a change in philosophy, with respect specifically to the Theme Unit Tests, in which the Theme Unit Tests are treated as *recommended* rather than *required* – since the level of subjectivity in the Theme Unit Tests is definitely higher than the level of subjectivity in the rest of the Guidelines.

              There are other opportunities to make some of the code quality guidelines more explicit, but at some point, we needlessly restrict coding-practice decisions. Theme options handling is one example. (This is also the reason that personally I don’t push for the official WordPress Coding Standards to be incorporated into the Guidelines, as much as I see that as the ideal.)

            • nofearinc 2:11 pm on November 11, 2013 Permalink

              Chip, are you willing to start a long (and probably painful) thread on the guidelines and the test data? I would personally love to see more specifics that would reduce the subjectivity, and probably some official (like in the Codex) prioritization of everything.

              If I have to guess, there are about 10-20 blockers for a theme, around 100 recommended issues and 100+ “nice to have” things. If you see any future in that sort of separation with some regulations about how many “recommended” things are acceptable, that would be great – and definitely progressive after the awesome theme review incentive program that revolutionized the queue processing drastically.

              Another thing that would help is some internal regulation for reviewers. If people take over someone else’s review, there is something wrong. And there are no guidelines for that, who is to blame or what would be the correct flow to reduce the tension and simplify the process (at least IMO).

            • Chip Bennett 2:55 pm on November 11, 2013 Permalink

              Chip, are you willing to start a long (and probably painful) thread on the guidelines and the test data? …If I have to guess, there are about 10-20 blockers for a theme, around 100 recommended issues and 100+ “nice to have” things.

              I’m not sure if that depth of discussion/debate would be beneficial. It might be better to take a broad brush, and say either the Theme Unit Test criteria are all required or else all recommended. In all honesty: if the code review is thorough enough, the Theme Unit Tests almost become an afterthought. If I’m doing a full review, my time is spent 95% in code review, Theme-Check, and install error-checking; and 5% on the front end/Theme Unit Tests. If 805 of review subjectivity comes from 5% of the review process, perhaps the most effective way to deal with that 80% is simply to reduce the criticality of the Theme Unit Tests as a whole.

          • Lance Willett 5:53 pm on November 11, 2013 Permalink

            @chipbennett

            perhaps the most effective way to deal with that 80% is simply to reduce the criticality of the Theme Unit Tests as a whole.

            Yes, please—that’s the whole point of my post. Can we make it happen by updating the Review page and the review team philosophy to make them not required?

            • Chip Bennett 6:13 pm on November 11, 2013 Permalink

              Discussing this among the admins currently, likely to be followed by specific community discussion.

        • Chip Bennett 1:52 pm on November 11, 2013 Permalink

          Now all the power is with theme authors. Now only reason for theme to not get in is that theme authors are either lazy or stubborn.

          I don’t agree. While the process is orders of magnitude better, I’ll never pretend that we’re perfect. Different reviewers bring different personalities, different languages, different levels of review experience, different levels of code expertise, different levels of design/aesthetic expertise, and even different interpretations of the Guidelines. The end result can still be frustrating for developers.

          The Theme Review Team is as big as it is, because it needs to be. Theme review takes more than the half-dozen active people that we used to have in order to be done properly and to keep up with the influx of submitted Themes. But all of those Reviewers come with vastly different experience levels. The only way for Reviewers to improve is to let them conduct reviews, and then educate them through the review process. That’s why I spend almost all of my time now auditing reviews instead of doing my own reviews.

          I think it’s important that we as reviewers take the same approach with the developers who have submitted Themes: they’re new to the review/approval process as well. As reviewers, it is our job to help them through that process, with the end goal of seeing their Theme approved and listed in the Theme Directory. That paradigm shift has been one of the biggest improvements to our efforts, and is bearing fruit. I see far more comments along the lines of “wow, the Theme reviewer was really helpful, and I really learned a lot getting my Theme reviewed and approved”, where before, most comments exemplified the frustration inherent in Andy’s aforementioned Tweet.

      • Frank Klein 9:52 am on November 11, 2013 Permalink

        First of all I’m sorry about the negative experience that your dad had, Andy. I respect everybody that learns a new skill and that puts his creations out there for everybody to see.

        But I cannot agree with your approach to the review process. As you said yourself, you did your first theme a few years ago and it was bad.

        This is exactly why the WPTRT has been created: to bring the quality of themes WP.org to an acceptable standard. And I consider that the team has been very successful at it.

        The WordPress.org repository is there to provide users with great, free to use themes. It’s not there to provide new designers or developers with a fuzzy feel good feeling.

        Of course this can be off putting for newcomers, but lowering the standards just so that sub standard themes make the cut is not a good solution. Moving the goal posts only masks the problem, it doesn’t solve it.

        If you want to see what a low barrier of entry brings you to, then check the Plugin section of the website. I don’t want themes to become the new plugins.

        For me the question is: how can we make sure that developers have enough resources to learn about theme development best practices and about the theme review process in general so that we can avoid such frustrating experiences with the first review?

      • Frank Klein 9:53 am on November 11, 2013 Permalink

        First of all I’m sorry about the negative experience that your dad had, Andy. I respect everybody that learns a new skill and that puts his creations out there for everybody to see.

        But I cannot agree with your approach to the review process. As you said yourself, you did your first theme a few years ago and it was bad.

        This is exactly why the WPTRT has been created: to bring the quality of themes WP.org to an acceptable standard. And I consider that the team has been very successful at it.

        The WordPress.org repository is there to provide users with great, free to use themes. It’s not there to provide new designers or developers with a fuzzy feel good feeling.

        Of course this can be off putting for newcomers, but lowering the standards just so that sub standard themes make the cut is not a good solution. Moving the goal posts only masks the problem, it doesn’t solve it.

        If you want to see what a low barrier of entry brings you to, then check the Plugin section of the website. I don’t want themes to become the new plugins.

        For me the question is: how can we make sure that developers have enough resources to learn about theme development best practices and about the theme review process in general so that we can avoid such frustrating experiences with the first review?

        • Andy Peatling 6:29 pm on November 11, 2013 Permalink

          But I cannot agree with your approach to the review process. As you said yourself, you did your first theme a few years ago and it was bad.

          This is exactly why the WPTRT has been created: to bring the quality of themes WP.org to an acceptable standard. And I consider that the team has been very successful at it.

          That is the difference right there though. He didn’t hack this theme together with no knowledge. I taught him the right way to build a theme, starting with the basics. We used the theme check plugin and everything worked great. Surely that should be enough to get a theme accepted with little issue (assuming no security, spam etc issues)?

      • Chip Bennett 1:27 pm on November 11, 2013 Permalink

        I taught him the absolute basics for a functioning WordPress theme. He made sure all base functionality worked correctly, I gave it a double check, we uploaded it.

        In all honesty, this would have been my same experience had I attempted to upload the first iteration of my own, personal-use Theme. I didn’t know what I didn’t know about Theme code quality. I was self-taught, having ported my old 2005-ish Blogger Theme to WordPress when I made that jump, based only on poking through the Codex to hack my way through template tags.

        I enjoyed the process, and learned a lot. But would that Theme have been an appropriate level of code quality to distribute via the official Theme directory? Certainly not. That principle is embodied in a philosophy espoused by Matt, who has said that we’re not looking for all Themes for the directory, but rather the best. And as tightly as the official Theme directory is integrated into end users’ WordPress admin, that’s exactly as it should be.

        So, I can empathize with your father; I’ve been through the same learning curve – and I wouldn’t change that for anything.

        We were presented with a laundry list of small problems that needed to be addressed before he could even upload the zip file. For someone starting out with WordPress this was incredibly off-putting. He admitted he would have given up there if I hadn’t have stepped him though it.

        Were you or your father aware that the Theme Review Team maintains a Plugin – Theme Check – that can be used during development and prior to Theme submission, and will output all of the same warning/required/recommended/info comments, in greater detail? If you weren’t aware of that Plugin, is there a way that we can better communicate its existence to aspiring Theme developers?

        There were a few things we missed that did need to be fixed, but most of the items on the list I would have considered minor issues and nothing that stopped the theme from functioning at a respectable level.

        Again, we’re not aiming for “functioning at a respectable level”; we’re aiming for Themes that are well- and tightly-integrated with WordPress core, and that inter-operate well with Plugins, to provide the best-possible end-user experience.

        Over the course of four reviews we interacted with three different people. Each person re-reviewed the theme and came up with a whole list of new things that needed fixing each time. I cannot highlight enough of how infuriating and demoralizing this is. It is an absolute momentum killer and sucks the life out of the person who is new and trying to learn.

        This was a known problem, and one that we’ve directly addressed – ironically, around the time of your aforementioned Tweet. We (thanks to Otto and Nacin) implemented some needed infrastructural changes that allowed us to keep reviews for a given Theme in a single ticket instead of generating a new ticket for each Theme revision in an on-going review. We also implemented a procedural change that placed more focus on reviewers working with developers to ensure that a submitted Theme eventually becomes an approved Theme.

        The old process really didn’t work the way we needed it to. The focus was on closing tickets instead of on approving Themes. We’ve fixed that, and it’s working much better now.

        Without me my Dad would never have made it through these steps, which is a terrible shame because all of the items in the review were not blockers and could have been updated later (more on the updated later bit in a sec).

        Ensuring that the reviews performed by over 100 volunteer reviewers will be a never-ending effort. It is one of the primary reasons that we keep the Guidelines as straight-forward, explicit, and objective as possible: to try to eliminate as much subjectivity as possible. And even then, some reviewers still interpret some of the Guidelines differently. It’s our job as admins continually to try to educate reviewers, and work toward more-consistent reviews. Having a process that is largely under control now has freed us up to put more time and effort into ensuring review consistency.

        And we’ll keep working on that. All I can ask is for some patience and understanding that Theme Review Team efforts come entirely from volunteers – across a wide spectrum of experience levels – who are merely attempting to make their own contributions to the WordPress project.

        If I had not been there showing him how to fix all the minor issues, he would never have made it here, and almost certainly would not be working with WordPress still (he may even have given up on the dream of being a web guy entirely).

        Having said that, he has not updated the theme since. I just asked him why. He said — “I have no enthusiasm to go through that process again, it’s too demoralizing”. I think that speaks volumes.

        Please encourage him to submit an update. Perhaps it would give you both a chance to see how the process and system have improved – and/or an opportunity to provide the team with more constructive feedback.

        • Andy Peatling 6:39 pm on November 11, 2013 Permalink

          Thanks for taking the time to give feedback Chip.

          In all honesty, this would have been my same experience had I attempted to upload the first iteration of my own, personal-use Theme. I didn’t know what I didn’t know about Theme code quality. I was self-taught, having ported my old 2005-ish Blogger Theme to WordPress when I made that jump, based only on poking through the Codex to hack my way through template tags.

          I enjoyed the process, and learned a lot. But would that Theme have been an appropriate level of code quality to distribute via the official Theme directory? Certainly not.

          The difference is that the theme was not hacked together and was certainly better quality than my first theme. It followed all the general best practices. It wasn’t a hacked together theme.

          Were you or your father aware that the Theme Review Team maintains a Plugin – Theme Check – that can be used during development and prior to Theme submission, and will output all of the same warning/required/recommended/info comments, in greater detail? If you weren’t aware of that Plugin, is there a way that we can better communicate its existence to aspiring Theme developers?

          We used this plugin, everything worked great and checked out before we started the directory upload process.

          Again, we’re not aiming for “functioning at a respectable level”; we’re aiming for Themes that are well- and tightly-integrated with WordPress core, and that inter-operate well with Plugins, to provide the best-possible end-user experience.

          And I think that is the source of the difference of opinion here. I think that is a good goal to aim for, however I don’t feel it should be at the expense of new folks being able to experience their theme being downloaded early on.

          I feel like there must be a solution that allows someone new to the community more approachable access to the directory, while still maintaining the accessibility of great themes to end users?

          The old process really didn’t work the way we needed it to. The focus was on closing tickets instead of on approving Themes. We’ve fixed that, and it’s working much better now.

          That is great to hear, continuity of reviewer would have helped a ton in my Dad’s situation.

          And we’ll keep working on that. All I can ask is for some patience and understanding that Theme Review Team efforts come entirely from volunteers – across a wide spectrum of experience levels – who are merely attempting to make their own contributions to the WordPress project.

          Definitely, I completely understand that. None of this is a stab at the volunteers, more a questioning of the process itself. I think there are ways that can take more weight off the shoulders of volunteers.

          Please encourage him to submit an update. Perhaps it would give you both a chance to see how the process and system have improved – and/or an opportunity to provide the team with more constructive feedback.

          I’ll ask him again and let him know the process has changed. :)

          • Samuel Wood (Otto) 7:09 pm on December 3, 2013 Permalink

            We used this plugin, everything worked great and checked out before we started the directory upload process.

            For reference, when I wrote Theme Check, I did it with the specific goal in mind of having the exact same code run on the upload process as in the plugin itself. While initially there were a few minor differences there, those are almost completely gone (I think there’s only two or three left).

            What runs in Theme Check is the exact same set of checks that runs on the WordPress.org theme uploader. Same code. Maybe it is not as up-to-date all the time, since I have to update it manually, but if you pass Theme Check, then you *will* pass the uploader.

    • Jen Mylo 5:03 pm on November 11, 2013 Permalink

      To that end, I would love to see something in the theme directory about what is/isn’t guaranteed for the themes we host on .org. It’s an unending source of FUD for users what they can expect/rely on us making sure of for them with the review process for the .org directory.

      • Chip Bennett 5:27 pm on November 11, 2013 Permalink

        I’m sure we can make that happen. Can you provide any specifics regarding the FUD, so we know what to address?

        • Emil Uzelac 8:36 pm on November 11, 2013 Permalink

          Warranty and Liability comes in mind, the basics :)

    • Ian Stewart 5:44 pm on November 11, 2013 Permalink

      Would I give up on theming if I started today and was uploading my first theme to the official directory? I’m not sure. I’m pretty persistent but if it can be a pain for professional WordPress developers I imagine that it can’t be too great for new folks.

      It’d be interesting to see some stats. How many themes are uploaded once but never have tickets made eventually? We won’t know what those looked like but it’d be interesting to do a visual review of screenshots from themes that had one ticket but never went live. (A bunch would be spam, sure.) My hunch — like Andy’s — is that we lose out on a lot of really great WordPress themes and amazing community members at this point.

      +1 to things like making the Theme Unit Tests a recommended item rather than a required one. My guess is that 80% of users of all themes won’t be bothered by a lot of them and that most themes that fail them will fail the “preview” stage. Who doesn’t look at the preview/demo? Let that decide. The good stuff will rise to the top. Even then a lot of great themes will still be useable. I don’t think I’ve ever seen a custom-made one-off theme that passed the Theme Unit test. And I bet they’re used by happy publishers and read by happy readers who would never notice some of the small things on there.

      Also, I’m sure no one but the most theme-obsessed people know about Theme Check. :) The upload page could maybe have a short checklist. Something like this:

      Whoa there, pardner! Before you upload your theme:

      1. Run a Theme Check
      2. Review the guidelines
      3. Run the Theme Unit Test (optional)
      4. Eat a healthy sandwich

      • nofearinc 5:47 pm on November 11, 2013 Permalink

        I might be wrong, but Theme-Check is running on every upload automatically, no?

        • Ian Stewart 5:54 pm on November 11, 2013 Permalink

          The idea is to encourage users to run it themselves first — for a better experience. As noted above …

          We were presented with a laundry list of small problems that needed to be addressed before he could even upload the zip file. For someone starting out with WordPress this was incredibly off-putting. He admitted he would have given up there if I hadn’t have stepped him though it.

          Were you or your father aware that the Theme Review Team maintains a Plugin – Theme Check – that can be used during development and prior to Theme submission, and will output all of the same warning/required/recommended/info comments, in greater detail? If you weren’t aware of that Plugin, is there a way that we can better communicate its existence to aspiring Theme developers?

          I think the better way to communicate this would be on the Theme Upload page as the first item in a short checklist. (That, yes, should include something funny like “Whoa, pardner” and “Eat a sandwich” — working with WordPress should be fun and not a chore.) Working with Theme Check before you package theme code with your hopes and dreams in a ZIP archive is better than uploading and finding out you’re a failure.

        • Chip Bennett 6:13 pm on November 11, 2013 Permalink

          Yes, they’re the same warning/required checks in the uploader as in Theme Check.

      • Chip Bennett 6:15 pm on November 11, 2013 Permalink

        @Otto42 can you make something like this happen on the Theme Uploader page?

        • Samuel Wood (Otto) 10:19 pm on November 11, 2013 Permalink

          We can add any form of wording or text you want to the uploader page. Just come up with what you want it to look like and get everybody to agree or iterate on it a bit.

          Make a meta ticket for it too once you have something we can put on there.

    • Drew Strojny 2:48 am on November 12, 2013 Permalink

      I’d like to echo some of the sentiment already posted by a few folks on here. Like Andy, Ian, Justin, and others, I got started with WordPress themes way back in the dark ages. I decided to try my hand and building a theme. After a month or so I submitted it to the repository and was accepted! I’m sure the code was terrible, but I was nonetheless really excited to see my theme getting downloaded and used across the web.

      This experience really stoked my proverbial fire when it came to building more themes and making my first theme better. As a few years passed, we went on to actually grow a business around WordPress themes. If I had been rejected that first time, who knows what would have happened. I may have just given up and moved on to something else, or maybe I would have stuck with it, and the world would have had a better theme.

      I do know that we stopped submitting to the directory when the new review guidelines went into place. Chip and I have actually talked about this in depth, and I don’t blame the theme reviewers at all. They’re just following the rules and doing their job.

      Why did we stop? For me personally, the process stopped being fun. It was demoralizing and incredibly frustrating. I just simply didn’t agree with the review philosophy. Call me stubborn, but I felt strongly that some requirements weren’t in the best interest of our users. Eventually, I just stopped caring. We were more focused on premium themes at that point, so we just let our existing themes rot on the vine. Since then, we haven’t submitted an update or a new theme in years.

      Ironically enough, we’re now thinking about diving back into the fray, and we’d really like to get some more free themes into the directory. It’s how we started, and I’d love to continue giving back to the community (and getting some marketing) through the WordPress.org repository. I’m hopeful that the process has improved, and I look forward to seeing how things unfold when we move ahead with it.

      I think both sides are seeing this from different angles:

      The “stick to the guidelines” group sees this as a way to improve the WordPress ecosystem and the average user experience. Better theme guidelines lead to better themes, and better experiences for WordPress users.

      The “stop being so strict” group sees this as a choke point for developer interest and growth. After all, if we constantly slam the door in the face of new WordPress theme developers, we slowly starve innovation from the inside out.

      I think both of these come from the right place. Both groups care deeply about WordPress and WordPress themes. I don’t know what the right answer is, but I really do believe (from personal experience) that too much dogma from the gatekeepers about what’s right and wrong for a WordPress theme discourages innovation.

    • Bryan Petty 7:43 am on November 13, 2013 Permalink

      “too much dogma from the gatekeepers about what’s right and wrong for a WordPress theme discourages innovation” — this is basically where my thoughts land, except I would replace “innovation” with “participation” entirely.

      This is one aspect of WP.org that obviously is not run like an open source project normally would (just look at the heated debate going on here). Being a community project, I wholeheartedly agree with Lance on “security, license, no spam” just for gate-keeping purposes only. Why is it such a problem to let the community as a whole decide whether the the item is junk? It’s not like there isn’t a rating and review system in place. It would make submissions quicker and easier to process, and give the TRT more time to work on more constructive and productive projects (like improving the theme repo search, filters, additional tools, and better UI for finding the best themes in the repo – and yes, filtering out the poorly rated ones too).

      It’s quite possible that a theme designer is new to all of this, and really actually just needs some good, quality criticism from the community. Of course their theme is missing critical components and functionality, it’s their first theme. But if they can’t even get it accepted on WP.org for quick and easy installation for family, friends, colleagues, and the community here to install and review, we’ve failed. The TRT doesn’t have the time to help theme designers properly fix every issue they find, and we shouldn’t be expecting some level of perfection from everyone immediately up front.

      Besides, the best way WordPress can recruit more theme reviewers from the community is to actually let the themes be reviewed directly on the theme repository rather than requiring manual theme installation directly from Trac before themes have even been vetted for security. Get them past that first crucial step, then open it up for the community in the most convenient way possible.

      • Chip Bennett 12:47 pm on November 13, 2013 Permalink

        This is one aspect of WP.org that obviously is not run like an open source project normally would (just look at the heated debate going on here).

        Actually, I would counter that the Theme Review Team sets the example among WordPress community-contributor groups with respect to openness. I don’t think you’ll find discussion like this taking place many other places.

        hy is it such a problem to let the community as a whole decide whether the the item is junk? It’s not like there isn’t a rating and review system in place.

        Because, not to put too fine a point on it: the WPORG review and ratings system is broken and doesn’t work, and is entirely insufficient to replace what we accomplish through the current Theme Review Guidelines.

        …and give the TRT more time to work on more constructive and productive projects (like improving the theme repo search, filters, additional tools, and better UI for finding the best themes in the repo – and yes, filtering out the poorly rated ones too).

        The Theme Review Team has zero control over any of those things.

        The TRT doesn’t have the time to help theme designers properly fix every issue they find, and we shouldn’t be expecting some level of perfection from everyone immediately up front.

        I disagree. WordPress end users who find and install Themes directly from their Admin Dashboards – Themes that come with the implied endorsement of WordPress itself – deserve to have those Themes be as well-coded as absolutely possible, to ensure that those Themes don’t interfere with core, interfere with their installed Plugins, or lock them in to a given Theme.

        If the solution to providing a means of encouraging and facilitating new developers to contribute Themes to the project is a second repository of some sort, then that’s something that people above our pay grade can decide and implement. I’m sure we’d support such an effort wholeheartedly. But I am adamantly against anything that would adversely impact the average end user installing Themes from the official Theme directory.

        As Matt says: we’re not looking for *all* Themes; we’re looking for the *best* Themes.

        Besides, the best way WordPress can recruit more theme reviewers from the community is to actually let the themes be reviewed directly on the theme repository rather than requiring manual theme installation directly from Trac before themes have even been vetted for security.

        The most critical security vetting takes place before initial upload, and Themes are verified at the code/file level in Trac before ever being installed locally for review. As for community review: again, the current WPORG rating/review system is broken, and not reliable for any meaningful vetting or replacement for what the Theme Review Team currently does.

    • Ryan Hellyer 10:19 am on November 13, 2013 Permalink

      I think that themes which don’t make the cut should still be allowed in the repository, they just shouldn’t be actively promoted.

      • Zulfikar Nore 1:55 pm on November 13, 2013 Permalink

        In my experience the themes that do not make the cut are the ones that are poorly coded – i.e. they either break something, interfere with core or they are a security hazard.

        Promoted or not those themes just don’t make the cut full stop – they are not fit for the purpose and should never be included in the repository.

        Yes, where the above is not the issue then lets have a more relaxed approach while still maintaining some quality control and keeping end user satisfaction at the forefront.

      • Lance Willett 4:14 pm on November 13, 2013 Permalink

        Yes, I agree (in terms of Theme Unit Test passing).

    • StyledThemes 10:23 pm on November 16, 2013 Permalink

      Wow, this was a long read, lol. Anyway, I went for coffee and started to think more about what Lance brought up of good points, but judging from the ongoing discussion, it appears there is more to just simply submitting a theme and going through the unit test and review.

      I still believe the lack of focus on design quality is part of the whole picture because it seems as though it’s all about the code. Code is important, don’t get me wrong, but that is only 50% of any theme, where the other 50% is design. We seem to forget (or ignore) that people who come to check out, download, and use the themes are not coders and they don’t care or even think about it…they just want the theme to work, but they are also visual, which means they want a theme that also looks awesome and has great features.

      …Downloads are high on many but actual usage is extremely low…I’m going to guess less than 10% average.

      Anyway, this is probably a whole another topic I’m sure, but I’m starting to think about writing up an idea of how to greatly improve on the many facets with my own ideas of how themes are provided to the WordPress user out there. Call it an observation with possible solutions in the eyes of a Designer/Developer/End-User of WordPress.

      To be honest, I see a HUGE potential for the themes repository at wordpress.org and I just might consider giving a lot more of my time to help out more than just simply designing and submitting themes….That’s saying a lot from someone who comes from 6+ years working the Joomla! platform, and now committing to WordPress, lol.

  • Chip Bennett 11:28 pm on November 4, 2013 Permalink
    Tags: Guidelines   

    WP-Admin Theme Promotion 

    It has recently come to our attention that many Themes are using some…aggressive promotion techniques from within the WP-Admin:

    • Embedding videos and external IFrame content
    • Redirecting to a Theme Info page on activation
    • Promoting the Theme (or an upsell commercial version of the Theme) via Admin Notices
    • Etc.

    This sort of promotion is not appropriate. Adding a Theme info page is fine. Adding a Theme info page that promotes other of the developer’s Themes is fine. But redirecting to either of those pages on Theme activation is not. Adding an admin notice generated by the TGM Plugin Activation library, to notify users of companion Plugins that can enhance the Theme experience, is fine. Adding an admin notice to promote a commercial version of the Theme, or other Themes, is not.

    Embedded or external content of any kind is strictly prohibited, due to potential security vulnerability and user bandwidth issues. Linking to those resources at ThemeURI from a Theme info or settings page is fine.

    Please discuss in the comments, as it has just been pointed out to us that these issues impact a number of highly visible Themes. We need to ensure that we correct these ASAP, and ensure that we are handling them consistently when reviewing Themes.

     
    • tskk 11:32 pm on November 4, 2013 Permalink

      I do redirection to theme options page upon activation, is that okay?

      • Chip Bennett 11:35 pm on November 4, 2013 Permalink

        At the moment, though it is less than ideal. I would like to improve overall quality in that regard in the future. Themes should be able to work, out of the box, without needing users to save any options to the database. If you need help with that, let me know.

        (And it is for your own benefit as well, since the Theme previewer doesn’t work properly for Themes that require options to be saved to the database – and in the future will break entirely, once Otto implements improvements that won’t even *let* preview Themes save options to the database.)

        • Samuel Wood (Otto) 10:17 pm on November 6, 2013 Permalink

          Note: These “improvements” to the previewer are an idea only at present. We’re a long way from that. But still, it’s good to keep that as a goal, so that breakage is minimal when we do get there.

      • Aubrey Portwood 2:24 am on November 5, 2013 Permalink

        They should be able to get to it from themes.php once it’s activated, as they can click Customize, Edit CSS, and (insert Options Page Name)…right?

    • tskk 11:37 pm on November 4, 2013 Permalink

      My themes have all defaults set, doesn’t need user to set any options. So i guess its okay :)

      • Chip Bennett 11:38 pm on November 4, 2013 Permalink

        And if that’s the case, there’s really no need to redirect to the Theme options page. :)

        • tskk 11:42 pm on November 4, 2013 Permalink

          Want them to know it exists in case they never go there and see that there is a pro version since i don’t advertise on the front end with default images.

          If its okay, i would like to continue please.

          • Chip Bennett 12:14 am on November 5, 2013 Permalink

            If the purpose of the redirection is to draw attention to the upsell commercial version, that’s not okay.

            • tskk 12:16 am on November 5, 2013 Permalink

              Not entirely, its to show them the available skins, layouts etc. Can’t describe them all in theme description.

            • Chip Bennett 12:25 am on November 5, 2013 Permalink

              I’ll go back to what I said in another comment: users are smart. They know where to look for Theme options. They’ll go to the Theme options page on their own, if only to check out the available options.

            • tskk 12:30 am on November 5, 2013 Permalink

              I have to explain to them how to set a featured image so many times. Experienced users knows what a theme options page is, but a complete new user?

              If there are no technical reasons, we should let redirecting to theme options to account for complete new users and also to be a little considerate to theme authors. We depend a bit on pro sales.

              Its a win win for both.

            • Schwarttzy 12:40 am on November 5, 2013 Permalink

              I’m in the same boat TSKK, I too have emails coming in on simple things like how to set a featured image. But I have rolled over and decided to go with the flow.

            • Aubrey Portwood 2:17 am on November 5, 2013 Permalink

              I don’t think that user ignorance (for lack of a better word) is a good reason to show notices throughout the WP Admin, re-direct people upon activation, or help users find out how to set featured images. If that is the case, the place they got the theme at WordPress.org should deal with it there (support).

            • Aubrey Portwood 2:36 am on November 5, 2013 Permalink

              I think it’s about not interrupting the user’s intent. Redirection does, the user simply intended to “Active Theme” not “…and redirect me to the options page.” That’s why I think re-direction is not okay. But, on the options page, if you want to promote a paid theme, I think that’s fine as long as it does not interrupt intent.

            • tskk 7:03 pm on November 9, 2013 Permalink

              @Aubrey, I would argue that the intent of the user who activates the theme is to use that theme and redirecting to theme’s user guide or theme options page is actually aiding that user’s intent and not interrupting it.

          • Justin Tadlock 12:39 am on November 5, 2013 Permalink

            I can count the number of times on one hand how many users have asked where the theme options page was in 5+ years now. Three of those times was when my theme didn’t actually have an options page. Users are pretty dang smart.

            I’d like to avoid any sort of redirect after activating the theme. That’s not consistent with the normal WordPress theme experience. It seems to me that it could potentially be even more confusing.

            Not to mention that if your theme is adding the theme options place in the appropriate place, that link is shown directly alongside the other appearance-related links and the theme screenshot.

    • Emil Uzelac 11:59 pm on November 4, 2013 Permalink

      Let’s not discuss too much. Theme(s) with such problematic issues should be suspended immediately.

      • Schwarttzy 12:05 am on November 5, 2013 Permalink

        That has the possibility of knocking out over half the most popular themes in just the first two pages… I’m not on board for that.

        • Zulfikar Nore 12:08 am on November 5, 2013 Permalink

          There should be no favoritism!

          • Schwarttzy 12:15 am on November 5, 2013 Permalink

            I’m not playing favoritism, I think you could shut a lot of themes and end up causing a bigger problem than it really is at the moment.

            • Zulfikar Nore 12:28 am on November 5, 2013 Permalink

              Sorry Schwarttzy – that was meant to be “We” should not play favoritism. Was not implying that you are :)

        • tskk 12:09 am on November 5, 2013 Permalink

          Pretty harsh, especially when they don’t even know they should not embed videos.

          • Zulfikar Nore 12:16 am on November 5, 2013 Permalink

            Embedding was always a no, no!

            It shouldn’t take them long to rectify the issue and upload a revised version – we can then give those themes priority and get them back asap.

          • Chip Bennett 12:21 am on November 5, 2013 Permalink

            To be fair: the question of embedding videos and IFrame content has been brought up on the mail-list several times. We have been quite consistent in communicating that Themes must be 100% self-contained, and not bring external content into the WP-Admin area.

          • Aubrey Portwood 2:37 am on November 5, 2013 Permalink

            I also think if it has been discussed and outline somewhere (even though it’s hard to find)…rules are rules.

        • Emil Uzelac 12:28 am on November 5, 2013 Permalink

          I know what you are saying, but this is nothing new, we have been talking about stuff like this for some time now. Some of the popular authors/themes from the same list were already in similar situation and they did it again. No excuses!

          • Schwarttzy 12:30 am on November 5, 2013 Permalink

            You have been approving some of those themes with those problems if I’m not mistaken.

            • Emil Uzelac 12:46 am on November 5, 2013 Permalink

              Yes you stand correct, but we don’t do full review on previously approved themes.

      • Zulfikar Nore 12:07 am on November 5, 2013 Permalink

        +1

      • Justin Tadlock 12:43 am on November 5, 2013 Permalink

        +1 I’m on board with that. We’ve been pretty clear about this sort of thing for a long time now.

        • tskk 12:45 am on November 5, 2013 Permalink

          Not all theme authors read mailing list.
          If a theme has embedded videos, its reviewer’s fault., why punish theme author for reviewer’s fault? Give them time to fix instead of suspending them right away.

          • Emil Uzelac 12:49 am on November 5, 2013 Permalink

            I respectfully disagree. This was done purposely :)

          • Zulfikar Nore 12:51 am on November 5, 2013 Permalink

            I don’t think all are reviewer’s mistakes. I’ve picked up tickets where the author had been advised that what the theme is doing/adding is not allowed. They’d remove and the theme would be approved only for the to go and add it back in.

            I’ve see this done on theme url and the upsell issue to – during review the upsell info is removed but come the update review the info is back again!

            • tskk 12:53 am on November 5, 2013 Permalink

              Throw those sneaky sneakies under the bus, i have no problem :)

          • Aubrey Portwood 2:28 am on November 5, 2013 Permalink

            This is a quality control issue the way I see it. Before and after the fact. Otherwise mistakes couldn’t be “learned” from and both reviewers and theme authors couldn’t learn better and quality could never be maintained. I am a new author and new reviewer, but if I messed up, I’d like to learn about it so I can keep up with WordPress quality.

      • Aubrey Portwood 2:21 am on November 5, 2013 Permalink

        I don’t know about “immediately”, but maybe some kind of notice that within X days/months they must submit a modified version of the theme, or, then, it could be removed.

      • Bryan Hadaway 7:59 am on November 5, 2013 Permalink

        To be honest, I think you should immediately be suspended from an admin position for consistently having an irresponsible and vitriolic attitude towards these kinds of things, especially discussing issues in and of itself, the very heart and purpose of a community that you constantly undermine.

        This is a community, not a dictatorship and you’ve shown many times now that you’re more interested in fast and loose snap judgments based on personal ego or opinion than discussing and asking questions for the greater good of the community.

        Yes, we should discuss, much much more. It’s more important to educate than punish, shouldn’t there be a notice and grace period for any new guidelines that weren’t scrutinized at the time of someone’s theme being approved or scrutinized the next time they update their theme instead of just blindsiding them?

        This isn’t a personal attack, I simply don’t think you represent the community interest very well as an admin. I know you give back and volunteer a lot of time reviewing and answering questions and so on, but I don’t think you should have admin privileges if you’re so against discussion, which is integral to the decision process.

        Thanks

        • Justin Tadlock 8:58 am on November 5, 2013 Permalink

          It’s more important to educate than punish, shouldn’t there be a notice and grace period for any new guidelines that weren’t scrutinized at the time of someone’s theme being approved or scrutinized the next time they update their theme instead of just blindsiding them?

          From what I understand, some of these theme authors were told that they couldn’t do this sort of thing the first time around. They removed those things. Then, once approved, they re-added them, knowing that we don’t do full code reviews on previously-approved themes. This is what I’ve been able to gather from reading the comments anyway (though not mentioned directly in Chip’s post). If this is the case, they’ve already been educated. If not, there’s no problem with some sort of grace period.

          As for embedded external content, that’s a security issue. That needs to be dealt with swiftly and immediately. Any security issues have always (from my understanding) resulted in an automatic suspension until the issue could be corrected. This isn’t meant to punish theme authors. It’s meant to protect users.

          • Bryan Hadaway 11:07 am on November 5, 2013 Permalink

            I agree. I don’t suspect that a lot of theme authors sneak stuff back in, I doubt most are also reviewers and know the ins and outs to even know that they can “trick the system” in the first place, but I don’t doubt that some have done so.

            And this is exactly why we need to discuss these things. There are lots of variables to discuss and reasonable measures for solutions that should be considered. Let’s not discuss it and pull out the ban-hammer on everyone immediately is never the right thing to do. Obviously, security issues are an exception of course.

            Really though, let’s look at the root causes for this issue, to me, it’s 2 things:

            1. Lazy diff reviews. Whenever I do diff reviews I actually check to make sure some random thing didn’t get thrown in there. Not to say that I’m a perfect reviewer cause stuff gets by me all the time that an admin catches. It’s a neverending learning process for us all.

            2. As a theme developer and a theme reviewer I have the foresight to be helpful to my reviewer and give them the courtesy of listing out the bullet points of the updates. Most developers just upload and run.

            We might start requiring theme developers to leave a comment reasonably covering the updates they’ve made in the new version. If they fail to do so the reviewer requests the list of changes and the review is on hold until that’s cleared.

            It’s actually really simple and straightforward. That way, we’d avoid surprises and if the developer doesn’t mention the pink elephant and we see a pink elephant in their update, it’ll be easier to investigate further and make sure everything is on the up and up.

            So, those are my thoughts, address the issue at its root, preventative instead of curative.

            Currently, all my own themes or themes that I represent are in the clear from all these issues aside from:

            http://make.wordpress.org/themes/2013/11/04/wp-admin-theme-promotion/#comment-33058

            Which appears to be a discussion for a later date, perhaps about admin redirects in general.

            Thanks

          • Emil Uzelac 7:35 pm on November 5, 2013 Permalink

            @Justin Tadlock that was the case exactly :)

        • Emil Uzelac 7:33 pm on November 5, 2013 Permalink

          @Bryan Hadaway No Theme was suspended, it was my opinion that’s all.

          You do have serious issues against me, Otto and few others around and not just in this post. My opinion hurts nobody, but your reckless words do.

          • Bryan Hadaway 9:44 pm on November 5, 2013 Permalink

            Actually, my words are always carefully chosen and exactly appropriate to what I want to say in response to whatever it is I’ve just read. I have no problem with you (Emil the person), I don’t know you. But Emil (the WP admin)…

            I also have no problem with you sharing opinion, that’s in fact what I’m encouraging. While I may disagree with you, I respect it when you join a discussion and do in fact actually have an opinion to share.

            However, when you (as an admin) encourage that we stop talking about something or not discuss it too much, that’s really not an opinion or helpful, it’s counter-productive. And that is an opinion.

            I probably wouldn’t be so concerned when you said things like:

            “Let’s not discuss too much. Theme(s) with such problematic issues should be suspended immediately.”

            Except you are an admin, and that does mean people will look to you for guidance more and give weight to what you say more than others, hence the need to be more responsible in guiding the community.

            The other admins, while I might disagree with as anyone might disagree with anyone else in this list on any other given day, never discourage discussion and quite the opposite.

            That’s the issue.

            • tskk 10:43 pm on November 5, 2013 Permalink

              Suspending themes is a topic open for discussion, otherwise he would have suspended them.

            • Bryan Hadaway 11:23 pm on November 5, 2013 Permalink

              @tssk – That’s not the point. Anyways, I’ve said my piece, back to the discussion.

              Thanks

        • Chip Bennett 4:08 pm on November 7, 2013 Permalink

          We make a concerted effort to provide a medium in which all stakeholders can speak openly, express their opinion, and contribute to decision-making. I think that same courtesy should be extended to the admins who will eventually make those final decisions, and anything said in a forum such as these discussion topics, whether from an admin, a reviewer, or a developer, should be treated as an expression of opinion/discussion.

          We have two competing issues here: how to deal with currently approved Themes using inappropriate promotion (and especially those that were explicitly instructed accordingly during initial review/approval, only to restore promotion post-approval), and how better to clarify the guidelines and educate Theme reviewers/developers going forward, so that our approach is more consistent while remaining fair to end users and to developers.

          While no action has been taken, I concur with Emil’s sentiment that Themes that have been instructed during review to remove promotional functionality, only to restore it after initial approval, deserve immediate suspension. That sort of behavior disrespects the efforts and goodwill of the Theme Review Team.

          Usually, any sort of similar bait-and-switch tactics result in immediate suspension without warning, and even blackballing. But instead we are taking this approach. Even though we have chosen to take this approach, Emil’s opinion and sentiment are no less valid.

          Ultimately, for the sake of open discussion, give the benefit of the doubt that anything said in discussion threads such as these are merely expressions of opinions – even if said by an admin.

    • design311 12:03 am on November 5, 2013 Permalink

      The less clutter the better I think, I prefer themes with an option page but nothing else. If a theme info page is a help page with tips & tricks about the theme I guess that’s fine but I don’t see why promoting other (commercial) themes of the author should be allowed. The user is already using a theme of the author so why should he even promote another theme?

      • Chip Bennett 12:19 am on November 5, 2013 Permalink

        We try to give a bit more leeway to the developer in links in the Theme’s admin page, because those links aren’t public-facing, and thus can’t be as readily abused for spam/SEO purposes. And a little bit of promotion is reasonable, considering Themes are being distributed for free.

        What I have a problem with is the WP-Admin being made into a virtual billboard. We have to find a reasonable balance. I make no qualms that, in such matters, I think first and foremost from the perspective of what most benefits the *end user*.

        Users are smart. They know where to look for a Theme options page, and I imagine that most/all users do go to the Theme options page on their own, if only to explore the available Theme options. Thus, I have full confidence that users will find the extra information that the Theme developer has added in the Theme options or info page.

    • Zulfikar Nore 12:06 am on November 5, 2013 Permalink

      If only all themes would standardize and use the Customizer!

      Plus the only link out should be the standard theme url and nothing else.

      • Aubrey Portwood 4:38 am on November 5, 2013 Permalink

        What if there are premium options? What if there are other themes by the company? What about development and getting involved? I think outbound links should be okay, just not thrown out around the WP Admin.

        • Chip Bennett 6:00 pm on November 5, 2013 Permalink

          What are “premium options”?

          Carried to the logical conclusion of the “presentation vs. functionality” paradigm, the vast majority – if not all – of valid Theme options would fit perfectly fine in the Theme Customizer.

          I agree in spirit with ZGani: ThemeURI and AuthorURI should be sufficient. But I would like to have the flexibility for developers to add reasonable other, non-public-facing links. Part of this discussion is to determine where the line of reasonableness lies – understanding that the default, fallback position is: if all else fails, we will be forced to limit developers to ThemeURI and AuthorURI.

          • Aubrey Portwood 6:37 pm on November 5, 2013 Permalink

            What I mean is that I think that people do go to the Appearance menu wanting to find out more about the theme too. They go there, of course, to configure the theme, but they may also go there to find out more things, like is there a premium version.

            But, I think you’ve convinced me. You’re right, they can always visit the developers site outbound link and I think that users are also smart enough to go there.

            So, yeah, I think I agree with a more stringent control of promotion after-all, where the user goes to configure the theme because they can also go to the developers outbound link too.

            I guess where I was coming from was the idea that I wanted to add a link so that developers and users can vote on new features for my own theme, etc in the options panel. I guess there is a desire to want to put a link to somewhere in the options panel, not for developers (they can go to the developer site, they know where that is), but for the person who just installed it. I feel like they don’t know that I want them to tell me about what they want, and where they can do that.

            It would be nice (and I know this is a bit off topic) if users had options in the Appearance menu (next to the theme they activate) to links like “Development” or “Premium Options”, etc that we could control. It just, now, links to the options panel.

    • Justin Tadlock 1:03 am on November 5, 2013 Permalink

      On promotional pages

      This may be a little off topic, but since we’re discussing promotion-related stuff:

      I’m not a fan of promotional pages at all and thought it should’ve been one of those things we done away with a long time ago. It really doesn’t add much to the theme user’s experience. As a commercial developer, I’ve probably left many $1,000s on the table by not adding this sort of thing to my own themes, but I’ve never added it because I don’t see any actual benefit for the user in terms of using WordPress. By and large, it’s clutter.

      I have no problem with promotion, but adding an entire screen to the admin is overkill.

      I’m not exactly pushing for us to outright ban this either, just throwing an opinion out there.

      • tskk 1:10 am on November 5, 2013 Permalink

        If someone wants to provide a theme with no credit link, no pro version and its advertising, then they are free to do so.

        why are we forcing our ideals on others.

        Users who want extremely clean themes can use these clean themes, users who don’t mind a little advertising in lieu for features that are available in cluttered themes can use cluttered themes.

        Let the user be the judge jury and executioner.

        • Zulfikar Nore 1:17 am on November 5, 2013 Permalink

          I’m not against some sort of promotion or a little clutter – what I don’t agree with is having that promotion/clutter shoved in my face if and when I choose that theme.

          Out of 14 themes I believe I’ve only added to one theme a “Go Pro” page and a basic one at that too and like Justin stated, I do not see any benefit to the end user let alone myself.

          Sure, let user choose the theme they use – also let them discover you on their own ;)

          • tskk 1:21 am on November 5, 2013 Permalink

            Everyone who buys a pro version of the themes in directory see’s the benefit.

            Like i said you have your philosophy and i have mine, lets not force ours on others :)

        • Justin Tadlock 2:28 am on November 5, 2013 Permalink

          Now, go back and read the actual words in my comment as they were written. Nowhere in my comment did I say anything about forcing any ideals on anyone. In fact, I went as far as saying that I didn’t expect us to push this at all.

          Since we’re on the subject though:

          The WordPress.org free themes directory is not a promotional tool for commercial ventures. That’s your own thing. And, it is our **duty** as the theme review team to uphold the ideals of Matt, whoever else owns WordPress.org, and the greater WordPress user community, regardless if those ideals conflict with some theme authors’ ideals.

          Obviously, it’s a reality that commercial sites and WordPress.org are going to cross paths. I’ve been doing this for a long time and have one of the oldest- and longest-running commercial theme/plugin sites in the WordPress ecosystem. I’m well aware of how things work and making sure I’m not crossing a line between actual usefulness and using WordPress simply as a promotional tool for my own gains (a line that I think many are crossing).

          There’s nothing wrong with promotion (as I said before) but there’s a big difference between elegantly promoting your own commercial interests and shoving an entire advertisement page into a user’s admin.

      • Aubrey Portwood 2:33 am on November 5, 2013 Permalink

        I don’t agree. The reason it’s open source is because anyone can remove these page(s). But, it should not hider any function. As long as it’s in a page of it’s own and not modifying anything outside of it, like notices on other Admin pages, etc, I think you can add a promotional page.

        If it has a lot of clutter, they can, again, just have it removed. That’s why it’s GPL, right?

        • Justin Tadlock 3:02 am on November 5, 2013 Permalink

          This doesn’t have anything to do with the GPL. We’re talking theme review team and WordPress.org policy.

          • Aubrey Portwood 4:32 am on November 5, 2013 Permalink

            I just don’t think that banning this kind of thing is totally necessary. My point about GPL means that this clutter can be removed anytime via the editor in WordPress.

            • Chip Bennett 5:54 pm on November 5, 2013 Permalink

              Our point is that end users shouldn’t have to worry about *needing* to get into the editor to remove such clutter from Themes installed from the official WPORG Theme directory.

            • Aubrey Portwood 9:01 pm on November 5, 2013 Permalink

              GPL has it’s place. The editor is there for a reason.

              It’s a trade-off: go ahead and non-aggressively, securely, and non-abusively promote your theme in the WP Admin (even it’s own page- which I think is more courteous), and we will graciously accept your theme for others to use and make WordPress.org more awesome.

              Don’t like it? Remove it, you can.

              I still think that a promotional page in Appearance is okay.

            • Towfiq I. 10:34 pm on November 20, 2013 Permalink

              Not everyone has coding knowledge you know…

    • Aubrey Portwood 2:44 am on November 5, 2013 Permalink

      I’m new to reviewing themes, but what are the options to “fix” these ASAP?

    • Rohit Tripathi 4:46 am on November 5, 2013 Permalink

      I Agree completely. I have noticed this in quite a few themes. Such agressive promotion, retards the quality of themes and user experience. Must be prohibited.

    • Aubrey Portwood 5:14 am on November 5, 2013 Permalink

      I think it’s pretty clear that whatever the theme author adds to WordPress it just shouldn’t interrupt the user.

      Admin notices interrupt the user, re-directing after activation interrupts the user, ad-like images are distracting and interrupt, adding parent menu items outside of Appearance is distracting and interrupt (because they aren’t in the right place), etc. Anything interruptive to the users intent should be prohibited. I don’t think it has to go beyond that, other than security and bandwidth issues.

      Promotional items, I think, should be okay. Because the user might go looking for any premium options and I think it’s intuitive to look in the Appearance menu where you installed the theme. I don’t think they need to be gaudy an waste the users bandwidth with images, etc. Plus we want to encourage developers to release free versions of their themes. If people want to pay, let them pay, as long as not paying doesn’t disable anything.

      On iframing stuff, of course that is a security issue. That means vids are out. Text, HTML, that’s it unless it’s a small functional icon or something.

      Anything a theme adds to WP Admin should allow the user to intend to do things, not automatically do it for them. I agree users are smart enough to go to Appearance when dealing with theme stuff, so it should remain there and only there.

    • Towfiq I. 5:57 am on November 5, 2013 Permalink

      +1

    • nikeo 6:41 am on November 5, 2013 Permalink

      Hi Chip and everyone,
      Thanks for recalling us this. I realize that my theme (Customizr) does not respect two rules:
      1) Embedding a video,
      2) Redirecting to a Theme Info page on activation

      Sorry if those rules had been brought up on the mail-list several times. I should have checked it more thoroughly and I really missed these ones.
      Even if the video and the redirection are not done on commercial purposes in my case, I fully agree with the potential security and bandwith issues. I also understand the will to avoid any kind of redirection on the activations/updates hooks.

      Why did I do that? Since I received many questions by email and on the forum I decided to create an additional information screen for the users of the theme (not including any commercial stuffs).
      On activation it provides some basics informations about how to use the theme and find some help. On theme updates it gives the changelog and some details about new features. Those screen includes an introduction video of the theme.

      I will make my theme compliant with those rules ASAP. Can you please tell me :
      1) Will the theme be suspended for that? (Well I hope not!)
      2) What is the delay for me to do those changes? I am about to release a new version of the theme this week, I will include those modifications.

      • Chip Bennett 4:27 pm on November 5, 2013 Permalink

        I’m not personally in favor of any blanket suspensions. I would prefer that any issues be noted in the most recent ticket for impacted Themes, and let developers have a reasonable amount of time to resolve those issues.

    • ThemeZee 11:09 am on November 5, 2013 Permalink

      In my opinion the problem is that a simple one line notice after activating the theme is actually not a big problem, but people always exaggerate and some themes really turn the WP Admin to a billboard.

      Since the guidelines should be easy to understand and follow I would also agree to completely prohibit user redirection and any theme promotion on the WP Admin screen except the theme info/options page.

      I’m an upsell theme author and currently promote the upsell version on the theme options page only (and I hope this will still be fine after that discussion).

      And when it really happens that theme developers remove features before the first review and add them secretly with theme updates afterwards I really think it the review team has the right to suspend such themes.

      • Chip Bennett 4:26 pm on November 5, 2013 Permalink

        Part of the purpose of having such a discussion as this one is to ensure that we’re all considering the bounds of appropriateness *now*, rather than resorting to a knee-jerk, blanket ban *later*.

        I have no problem with Theme developers promoting their work. We just need to ensure that we balance it with respecting the end users’ admin interface.

    • esmi 12:20 pm on November 5, 2013 Permalink

      I cannot think of a single reason why any of the “promotion techniques” mentioned above are needed to use a theme effectively. Themes should be submitted to the Repository because their authors want them to be used. Not so that they can just act as advertisements for commercial products. I support anyone earning an income from WordPress 110% but let’s not get silly. The WPORG Theme Repo is not a billboard and many theme authors manage to run a successful commercial theme business without ramming it down users’ throats.

      So I’m all in favour of prohibiting this kind of advertising in the Guidelines. If a situation did arise in the future where there was a definite need to use one of these techniques, what’s to stop the theme author raising it as an “edge-case” on the theme review mailing list? That has always been an option and, I assume, always will be. So there’s no dictatorial coup here. Only a move towards (hopefully) greater transparency.

      Where such themes already exist in the Theme Repo, perhaps the authors could be contacted via email and given a grace period of x weeks to either remove the features via a theme update or contact the theme review team?

      As for theme authors re-instating features that were initially removed so that the theme could pass a review, I’m also in favour of an immediate suspension.

      • Emil Uzelac 7:52 pm on November 5, 2013 Permalink

        Thanks Mel. As Justin mentioned above this was the intentional repeat. Still no Theme was suspended and discussion continues. :)

      • Aubrey Portwood 10:05 pm on November 5, 2013 Permalink

        I am a person who thinks “Themes should be submitted to the Repository because their authors want them to be used,” but I don’t think that promotion is bad. Aggressive, yes, but moderate, no.

        When you say “prohibiting this kind of advertising in the Guidelines” I just cringe at the idea of prohibiting, instead of being flexible. I mean, yeah, we prohibit themes from not being GPL, but that is because we don’t want to prohibit the people that install them from doing what they want with them. We want more freedoms with quality control. If authors want to promote other things I think that it should be allowed within certain guidelines.

        I think promotion is totally okay.

        And, we did allow themes onto the site. We gave the okay. That’s an integrity issue, we can’t just say, oh wait…never-mind, we changed our minds, you’re out. Suspensions are just totally not okay with me. I like the idea of some kind of notice, or a sticker on themes that no longer follow new guidelines to warn installers and developers. Users also don’t deserve to just see themes they like just disappear either.

    • tskk 11:16 pm on November 5, 2013 Permalink

      How much clutter is clutter is highly subjective matter, I propose that only an admin, Chip or Emil and not a reviewer, decide on that matter just for sake of consistency , just to take the luck( bad luck of ending up with a highly stringent reviewer ) part out of equation.

      It will only take a 2-5 minutes of their time per theme and there are not many themes out there that fall in this category( Its mostly theme shops, and they all have same options panel. Reviewing one theme from their collection, will be sufficient )

    • Himanshu Parashar 11:50 am on November 6, 2013 Permalink

      In my opinion such type of advertising should be banned completely as promotion should not be main concern while submitting work to WordPress. We are here to contribute towards the community, ease the task of people who use the wordpress instead of make money from those commercials.

      • tskk 1:18 pm on November 6, 2013 Permalink

        Since we are here only to contribute to community, lets ban credit links, author urls and theme urls too.

    • wpweaver 5:20 pm on November 6, 2013 Permalink

      I brought up the whole thing of upsell on the Theme Reviewers list a few weeks ago. I thought promotion had gotten a bit excessive. But here are my thoughts.

      Developers with upsell versions of their themes must be allowed to continue to have reasonable upsell promotion in their theme admin page(s). But nothing except that one link on the visitor side.

      To me, the line between okay and too much is easy – anything that requires active intervention on the part of the site admin is too much. No “Dismiss” buttons to close advertising. No decreased functionality unless the user takes some action. No pop-ups. No active scrolling boxes floating on the side. Just simple links, including self-contained image links. Ideally, nothing that interferes with interacting with any theme options.

      While this is still a bit subjective, I think a standard of not allowing “active” promotion is easy enough to define. And maybe something like not over 20% of the total theme admin pages can be devoted to upsell. No embeds, no videos, just links.

      On the other hand, one can argue that this is a user choice issue. If a theme has too much promotion, the users will not choose that theme.

      I think one needs to look no further than many Plugins with pro versions to see upsell taken to the limits. It is so common to see a plugin with a tiny portion of the admin page devoted to some setting for the free version, and 80% of the rest of the page devoted to upsell. That crosses the line. But plugins can’t be the only mechanism for upselling.

      And this leaves that one item that I thought had been left as allowed on the Theme Reviewers list – an extra menu item on the Appearance menu that can open a page wiht links to other themes and add-ons by the theme author. I personally think that is one step over the line, but if it remains allowed, I will likely use it in the future.

      But there are a lot of popular themes with upsell versions. And I think that everyone is a winner with this model. Most of these free versions are very good themes that work just fine without the upsell version, but would likely not be available without the ability of the theme author to make a little profit on their works via the upsell mechanism. This has long been recognized as a legitimate path and need to remain one of the options for theme developers.

      And for existing themes with embeds and videos – things that have clearly been banned for a long time – suspend them, perhaps after a week’s notice to the author. At the least, add a note the the last approved version that the theme must remove these before any revision is allowed. (Reviewers do look at the previous ticket, right?) That would have the least impact on any existing users.

    • Emil Uzelac 9:09 pm on November 6, 2013 Permalink

      First and foremost, authors should promote their pro themes, however it needs to be determined to what degree and to find out “how much is too much?”.

      Contributing to WordPress while having a pro version upgrade is not a “crime”, but we should have clearer guidelines about that.

      My idea (in that perfect world) would be:

      • Designated Promo Areas (set amount, yes, no?)
      • On/Off by User (if user doesn’t want to see promos, they should be able to turn them off)
      • Removable by Developer (hook/unhook)

      Would this satisfy all?

      • tskk 9:19 pm on November 6, 2013 Permalink

        Also if we go for on/off switch now, a few months down the line, someone will say it should be disabled by default.

        • Emil Uzelac 9:27 pm on November 6, 2013 Permalink

          You’re right, I am sure that this can happen down the line, but if we set some guidelines it can be avoided.

          • tskk 9:37 pm on November 6, 2013 Permalink

            Yes, lets quantify “how much is too much” and avoid the switch altogether.

            • Emil Uzelac 10:48 pm on November 6, 2013 Permalink

              Agreed

            • tskk 10:58 pm on November 6, 2013 Permalink

              Does 1:7 (lite to pro) overall( all tabs combined, if any) option fields and a banner sound good?

            • Chip Bennett 3:28 pm on November 7, 2013 Permalink

              That gets risky. Arbitrary-yet-rigid ratios/percentages are fraught with unintended consequences, and such specificity can be very difficult to evaluate/enforce.

      • Chip Bennett 3:53 pm on November 7, 2013 Permalink

        In the short term, I would be fine with a Theme/Developer promotion to a *tab* on the Theme Options admin page (and/or in the Theme Options page contextual help tab) being the designated promotion area; but since my ideal world envisions a day in which Theme Options pages are replaced entirely by the Theme Customizer, that wouldn’t work as a designated promotion area in the long-term.

        I wonder if this is something that could be incorporated into any future effort to allow Themes to use parsable readme.txt files, similar to the Plugin readme.txt? Developers could add a Commercial/Upsell tab to the readme, that could be displayed in the Theme directory, and/or in the WP-Admin, in whatever way the content of such a readme might conceivably be incorporated. Then, the readme.txt could be considered as a valid, designated Promo location.

        If we can determine a reasonable, designated promotion location, I see no particular need to require that it be on/off configurable/filterable.

        • Justin Tadlock 8:20 pm on November 7, 2013 Permalink

          I was going to bring up the readme.txt once we start getting things up running similar to plugins. Here’s an example of how I handle my commercial service:
          http://wordpress.org/plugins/clean-my-archives/

          There’s a short paragraph explaining that I offer professional support outside of WordPress.org. It’s not a billboard. It’s just plain and simple information.

          I feel like that’s the best way to offer something usable back to the community while also promoting my commercial service without shoving it in the user’s face.

    • tskk 9:17 pm on November 6, 2013 Permalink

      On/Off and hooks will be complicated and most of us use available options frameworks.
      If how much is too much is decided by a constant and not a variable will be good enough for me.

    • stuartwider 7:59 am on November 7, 2013 Permalink

      The real issue / concern here seems to be dealing with themes interfering with admin interface **outside** of the theme options page, iframes and redirects – which I agree should not be allowed.

      So to keep things workable I suggest staying within the scope of Chip’s initial post on this thread, rather than widening it out to theme options page upsell links which could end up being highly subjective.

      I’d say one suggested simple guideline could be

      • any upsell links must be kept wholly within the context of the theme option page / customize options.

      That way the theme is polite.

      • Chip Bennett 3:02 pm on November 7, 2013 Permalink

        Just a thought, but perhaps a good balance would be to allow Theme/Developer promotion within a *tab* on the Theme Options page (or via the Theme Options page contextual help)?

        *Personally*, I agree with Justin that a separate promotion page under Appearance is too much, but we have allowed it as a reasonable concession for developers to promote their work. But a separate tab on the Theme Options page itself would be minimally obtrusive.

        That said: thinking long term, in my ideal world, eventually *all* Theme options would be incorporated into the Theme Customizer, which would render a separate Theme Options page redundant and unnecessary. So, at that point: where would Theme developer promotion go?

        • tskk 3:25 pm on November 7, 2013 Permalink

          Tab becomes Section

          • Chip Bennett 3:25 pm on November 7, 2013 Permalink

            I would argue that Theme/Developer promotion has no place in the Theme Customizer UI.

            • tskk 3:29 pm on November 7, 2013 Permalink

              Theme/Developer promotion = pro only option fields or something else?

        • wpweaver 5:57 pm on November 7, 2013 Permalink

          I think confining to a single tab within theme options is too confining. Many people will never even bother to look at that tab.

          I do have a single “pro” tab that changes to new options if the extension is added.

          I also have an unobtrusive banner at the bottom of the overall theme admin page, and, most importantly, context sensitive information that allows the customer extra information about extensions in places that help them decide if the extension is useful to them.

          But a single location it too little. I would much rather have a soft overall percentage guideline.

          • tskk 6:34 pm on November 7, 2013 Permalink

            Yes, a percentage will be much preferable. A guideline and not a rigid rule.

            Ex : Lets say footer section has some options, some free some pro, it makes more sense to list them all at one place rather than put pro options in a separate tab.

            If the percentage is reasonably large, most themes will never breach it.
            If a reviewer feels the pro options are excessive, he can do the math and discuss it with author and admin.

            Profitable themeshops/authors = better, beautiful and more themes for users.

        • Aubrey Portwood 7:24 pm on November 8, 2013 Permalink

          I think this is great! Didn’t even think about it.

      • ThemeZee 9:53 pm on November 7, 2013 Permalink

        I would also prefer the guideline that upsell links have to be within the context of the theme option page.

        But there should be no rules on how many tabs and where exactly promotion links can be and where not. That’s just too many restrictions which are difficult to follow and to review.

        And options page are different. My theme options page comes with a sidebar which contains various links to theme documentation, changelog, online theme translation, theme info page and also upsell links.

        So far no user has ever complained about these links on the sidebar and I see no point why these should be removed and moved to a single tab.. They’re really not obtrusive at all..

        Therefore I’m really against any guidelines which restrict theme developers how they shape their theme options pages – that’s just too much.

        As long as there are no security reasons theme developers should have the freedom on theme options to promote upsell versions as they like. For me it’s just about letting the user know that there is an upsell version available. I don’t think you can gain any more sales with annoying popups but when some developers want to do that I think they should be allowed on the theme option pages.

        • Aubrey Portwood 7:25 pm on November 8, 2013 Permalink

          I agree, there should be some clear guidelines on upsell/promotion. I think this discussion is helping us get there though :)

    • stuartwider 8:05 am on November 8, 2013 Permalink

      I’m in agreeance with ThemeZee. Theme authors are free to design their options pages how they like, and should also be free to design links into their options pages as they like.

      To make the a rule about tabs and limit links within tabs assumes everyone uses tabs for anything useful that needs to be linked, which is definately not the case.

      Also, not all theme options are suitable for the theme customiser, so not all theme options will reside in there in the future (unless its design is changed in the future to be more encompassing..which would kinda make it just a move from one options page to another..but with more features).

      I see no reason why polite notices within the theme customiser sections should not be used to inform users that extra options are available. That seems perfectly acceptable to me.

      Lets not ‘throw the baby out with the bathwater’. Just concentrate on dealing with the obviously annoying techniques which are the reason why this thread was started in the first place. They are the low hanging fruit which are easy to deal with.

    • StyledThemes 10:00 pm on November 8, 2013 Permalink

      I just came across this discussion and I have a feeling I should ask this…in my themes, I do mention in the theme description that if the person wants more features, that there is a pro version of the theme. So to be clear, is this ok, or should I be removing that part and uploading an update to each of my themes? I just want to make sure I’m on the same page as the reviewers and admins when it comes to releasing themes and more themes over time.

      • Chip Bennett 5:12 pm on November 10, 2013 Permalink

        Mentioning commercial options (upsell/commercial Theme version, paid support, etc.) in the Theme description is certainly fine, IMHO.

        • StyledThemes 6:21 pm on November 10, 2013 Permalink

          lol…thanks Chip, I was getting paranoid there for a while. It’s a daily learning process.

    • CyberChimps 9:27 pm on November 25, 2013 Permalink

      From Trent at CyberChimps:

      Is there a final decision on this issue?

      I am strongly opposed to the idea preventing us from redirecting users to the theme options page. Many first time users have no idea what theme options are, it is intuitive and natural for them to get sent to the theme options page upon activation.

      If users suddenly activate a theme and it doesn’t take them to the theme options then they may never even realize the theme even has options.

      If we’re going to make a rule on this, I think we should simply specify that it can only be to the theme options or customizer.

    • Tikendra Maitry 12:16 pm on January 14, 2014 Permalink

      After going through complete discussion thread, I am still not clear about the statement made in post or we can say in new guidelines:

      “Adding a Theme info page is fine. Adding a Theme info page that promotes other of the developer’s Themes is fine.”

      I have two queries:

      1. Am I still allowed to have a separate theme info page along with the details of my other theme with respective WPORG theme link, Demo link and upsell theme link?

      In my opinion its complicated/confusing to have a tab for it, having a separate page is much better as if user want(if he likes the theme) he can go and check that info page for theme details and other themes.

      2. If someone have upsell version of his theme then is he allowed to show setup insctruction link and upsell version link on the theme “option page only”?

  • Chip Bennett 3:40 pm on November 1, 2013 Permalink
    Tags: , Guidelines   

    Theme Review Points of Emphasis 

    Here are some of the things I’ve been looking for specifically when performing the final audit of approved Themes waiting to be made live. These are the most-frequent issues when reopening a ticket for an approved Theme. Please consider these as “points of emphasis”, to help improve the consistency of our reviews.

    Prerequisites – these should be verified before even looking at Theme code

    • ThemeURI/AuthorURI: the first thing I do is check ThemeURI/AuthorURI for appropriateness.
    • If ThemeURI is a commercial Theme shop, or if the Theme is Up-Sell, I verify the commercial-Theme license, to ensure that it is 100% GPL/compatible
    • Credit Link: I then verify that the Theme has only one credit link, in the footer, that the URL is either ThemeURI or AuthorURI, and that link text and attributes are not SEO-seeded
    • Licensing: next, I check everything bundled with the Theme, verify that copyright/license attribution has been included, and that all licenses are GPL-compatible – fonts, images, jquery scripts, iconsets, everything. If it’s bundled with the Theme, it either needs to be copyrighted as part of the Theme, or include copyright attribution and be distributed under a GPL-compatible license

    Code Quality

    • header.php: verify that HTML <title> tag includes only the call to wp_title(). Any additional content, if required, must be added via wp_title filter.
    • header.php: verify that no scripts or stylesheets are hard-coded in the document head (except for the main stylesheet, and IE-conditional stylesheets)
    • header.php (usually): verify that calls to wp_nav_menu() include the ‘theme_location’ parameter, and do NOT include the ‘menu’ parameter
    • functions.php: verify that all function calls are placed inside of callbacks, hooked into explicit actions. No functions should execute directly from functions.php.
    • functions.php: verify that the Theme doesn’t call Plugin-territory remove_action() calls, such as removing the WordPress version generator from wp_head
    • functions.php: verify that Theme does not add function_exists() conditional wrappers for core functions introduced more than two prior major WordPress versions (currently: for any core function introduced prior to WordPress 3.5)
    • Template files and custom page templates: verify that Theme uses new WP_Query for secondary loops, and pre_get_posts to modify the main query, rather than query_posts()
    • Theme Options: verify that Theme options are being stored as a single array, are being sanitized on input, and escaped on output
    • Theme Options: verify that Theme options do not include “Plugin territory” options such as analytics/tracking code

    Addressing these issues would cover about 99% of tickets currently being reopened after approval.

     
    • Rohit Tripathi 7:49 pm on November 1, 2013 Permalink

      This is really helpful, as my reviews were stuck at this stage. Thanks for this useful piece of writing.

    • dohman 8:52 pm on November 1, 2013 Permalink

      this is great chip. thank you!

    • gladtools 1:17 pm on November 5, 2013 Permalink

      Wonderful. Bookmarked! Time to create my first GPL theme for WordPress lovers. =)

    • Siobhan Bamber (siobhyb) 6:54 pm on November 8, 2013 Permalink

      Great info. :)

    • Lance Willett 4:01 pm on November 10, 2013 Permalink

      This is amazing, Chip. Can we make these the blockers for theme review and simplify the rest? I’ve been thinking long and hard about my own strict standards for themes on WordPress.com and how much better off our theme collection might be if we were a bit more open.

    • nikeo 5:02 pm on November 10, 2013 Permalink

      Very helpful checklist for a theme developer.
      Bookmarked.
      Thanks

    • Qamar 6:38 am on November 14, 2013 Permalink

      Thanks for the useful checklist.

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel