WordPress.org

Make WordPress Themes

Tagged: Guidelines Toggle Comment Threads | Keyboard Shortcuts

  • Chip Bennett 2:48 pm on February 26, 2013 Permalink | Log in to leave a Comment
    Tags: Guidelines, Theme Name   

    Clarifying Guidelines for Theme Name 

    The current guidelines for Theme Name are as follows:

    • Themes are not to use WordPress in their name. For example My WordPress Theme, WordPress AwesomeSauce, andAwesomeSauce for WordPress would not be accepted. After all, this is the WordPress Theme repository.
      • Themes are not to use the term Theme in their name, such as: AwesomeSauce Theme. Same reason as above … it’s a Themerepository.
      • Themes may use the WP acronym in the Theme name, such as WP AwesomeSauce.
    • Themes are not to use version-specific, markup-related terms (e.g. HTML5, CSS3, etc.) in their name.
    • Themes are not to use related terms (e.g. Blog, Web Log, Template, Skin, etc.) in their name.
    • Themes are not to use Theme author/developer credit text in their name. For example AwesomeSauce by John Q. Developer(makes for a much better credit link); or, SEO/SPAM-seeded text, such as: AwesomeSauce by Awesome Free WP Themes (this is just not going to pass).
    • Themes are not to use related Theme names (e.g. WP Twenty Eleven, Twenty Eleven WP, The Twenty Eleven, etc.) in their name.

    In light of recent discussions, I think this would be a good time to clarify these guidelines. Please discuss below if you have any comments, questions, or feedback related to the Theme Name guidelines.

    WordPress

    The requirement not to use the term WordPress in a Theme Name should be obvious; all Themes hosted in the directory are WordPress Themes.

    Generic Terms

    The following Guidelines relate to the use of generic terms:

    • Themes are not to use version-specific, markup-related terms (e.g. HTML5, CSS3, etc.) in their name.
    • Themes are not to use related terms (e.g. Blog, Web Log, Template, Skin, etc.) in their name.

    These are the guidelines that I think are the least articulate, and need clarification.

    The intent is to avoid generic terms related to design elements, features/functionality, or intended use of the Theme. Whether that’s markup (HTML5, CSS3), design (responsiveness), features/functionality (photo galleries, jQuery masonry), or intended use (“Tumblogging”, real estate, business), terms related to these aspects are better left to the Theme description and, where applicable, filter tag keywords.

    The purpose of a Theme name is to ascribe an identity to the Theme through the uniqueness of that name.  It is perfectly fine to invoke design elements or intended use of the Theme through the Theme Name, but it should be done using a creative/unique term, rather than a generic term. The intent of the related Guidelines here is to emphasize this point, and to help avoid naming conflicts and disagreements that arise from the use of generic terms.

    Developer name

    As with the WordPress term, I think this one is self-explanatory.

    Reserved Core Theme Names

    The WordPress Core team has chosen a naming convention to use for the annually updated Theme distributed with core. Thus, it makes sense to ensure that this naming convention is reserved for core.

     

    • Rob van Linda 2:58 pm on February 26, 2013 Permalink | Log in to Reply

      Hello there,

      I normally work with Joomla but started to play with WordPress about a week ago (http://robvanlinda.de and http://wp.webdesign-labor.de) and I don’t understand why I shouldn’t put my name or terms like “responsive” in my theme name?

      Isn’t it entirely up to me to choose the name? It is my creation and I do what I want with it, right? As long as I don’t do something illegal I will do exactly what I want to do and even will mention WordPress in the description.

      Best regards,

      Rob

      • Chip Bennett 3:06 pm on February 26, 2013 Permalink | Log in to Reply

        Isn’t it entirely up to me to choose the name? It is my creation and I do what I want with it, right? As long as I don’t do something illegal I will do exactly what I want to do…

        Of course it is, and of course you may.

        But that doesn’t mean that said Theme will be approved to be hosted in the official WordPress Theme directory. Regardless of what you do with your own creation via your own distribution medium, for the official Theme directory, we need to, can, will, and do define and enforce guidelines regarding those Themes. Among those guidelines are the ones being discussed here: Theme Name. We don’t want the official Theme directory to be a magnet for marketing efforts, and we want to avoid conflicts/clashes over terms used in Theme names. So, we do need to have reasonable guidelines in place along those lines.

        • Srikanth 3:19 pm on February 26, 2013 Permalink | Log in to Reply

          I recently submitted a theme called “xyzthemeshop_business” somehow missing this no developer name rule. credit text is xyzthemeshop.com
          So will it be allowed?

          • Chip Bennett 4:56 pm on February 26, 2013 Permalink | Log in to Reply

            “xyzthemeshop_business”? No, I wouldn’t think so.

            A more acceptable construct might be “XYZ Business.” (But does that really sound like a great way to identify your Theme uniquely?)

            • Srikanth 5:14 pm on February 26, 2013 Permalink

              I was thinking XYZ_Business will be unique name since no one will get to use the XYZ. Something along the lines of Domino’s Pizza, CiCi’s Pizza etc.

    • Paul 3:01 pm on February 26, 2013 Permalink | Log in to Reply

      I think the last paragraph is pretty clear. The theme name should not be like a search engine keyword phrase that would make sense. Like “WPAjaxTheme”. But rather “Ajaxio” or something like that.
      “QueryPosts” would be rejected but not “QyPosts”. Be creative.

    • stuartwider 10:39 am on March 1, 2013 Permalink | Log in to Reply

      Hi Chip,

      Just for clarification for myself (and possibly others who are reading this) could you tell me which of the following names would pass or fail if they came to you in a theme review?

      Here’s the scenario…

      Imaginary theme shop ‘JollyMax Themes’ submits a ‘responsive’ theme to the directory and comes up with the following possible two word names…

      Jolly Responsive
      Jolly Respond
      Jolly Response
      Jolly Responsivo

      and single term names…

      Respond
      Response
      Responsivo

      Note I do not intend using any of these names at any time – these are just examples for clarification of the gray areas.

      • Chip Bennett 2:42 pm on March 1, 2013 Permalink | Log in to Reply

        I would say that, based on the clarified intent of the Guidelines, that none of them would be acceptable. However, since we already allowed a Theme named “Responsive”, then fairness would dictate that the term “responsive” is now fair-game for other Theme names.

        So, replace “responsive” with any other term that falls under “design elements, features/functionality, or intended use” and I would say none would be approved. But because we’ve set a precedent with the term “responsive” itself, we must be fair to all developers, and allow that term’s use in Theme names.

        • stuartwider 7:36 pm on March 1, 2013 Permalink | Log in to Reply

          I haven’t really been watching the development of theme guidelines up until recently but it seems to me that the clarification above of “Themes are not to use related terms (e.g. Blog, Web Log, Template, Skin, etc.) in their name” is actually stepping beyond its original intent, which I would guess was originally just there to prevent themes from stating the obvious in a name.

          I’m not sure the original guideline intent would have been to prevent theme authors from indicating design or features using generic terms such as responsive either. (The actual term ‘Generic terms’ is not mentioned anywhere in the existing guidelines as far as I can see).

          It appears to me that the clarification might be actually be a reinterpretation or retrofitting based on current discussions on the theme reviewers list, but not the intent of the guideline when it was originally created.

          If there is a consensus in the theme review community now to only allow original and creative names that do not use common words, generic terms or terms related to design or use, then the guidelines needs to be changed.

          I’m not convinced yet though from watching the theme reviewers list that there is the consensus on this issue, or that the existing guidelines need to be changed. I just think that the original intent of the guidelines need honored.

          My own view is that terms that indicate intended use and design are useful for theme users and should be fine in names, and that to prevent their use would be restrictive.

          I would say that as long as the intended use and design terms don’t cause confusion with a theme that is already in the repository, and dont hog an entire generic namespace then they should be allowed to be used.

          • stuartwider 8:10 pm on March 1, 2013 Permalink | Log in to Reply

            Further thoughts…

            Rather than reinterpreting the guidelines to be more restrictive with words (which will end up being a very long ever expanding and subjective list, and a stick for everyone to hit themselves and others with), maybe, think in terms of useful guidelines for namespacing and how names can be constructed as to be unique within the repository.

            I’d say its more desirable to encourage useful unique names for themes, rather than worrying about which specific generic or common usage words might be used in them.

            • Chip Bennett 9:14 pm on March 1, 2013 Permalink

              I would be fine with simply saying, “First come, first served” on all names/namespaces, and if someone chooses a “generic” term, we won’t field objections to other Themes that use that same term, as long as the overall Theme name is different. (With some common sense, of course: “Foobar” and “WP Foobar” are, for all intents and purposes, the same name.)

    • stuartwider 9:36 pm on March 1, 2013 Permalink | Log in to Reply

      Chip,
      First come first served sounds reasonable,
      as does no objection to themes using the same generic terms as long as its different overall.

      If a ‘first come first served on generic terms / different name overall’ guideline were put in place then everyone would know before right from the outset that if they use a generic term for their name then others may use that term also in their names. It makes it a level playing field, and everyone knows from the outset so theres nothing for anyone to get upset about in the future. It also resolves the ‘Responsive’ name question neatly.

  • Chip Bennett 12:51 pm on February 19, 2013 Permalink | Log in to leave a Comment
    Tags: Guidelines, Theme Branding   

    Theme Branding/White-Labeling Guidelines 

    Recently some questions have come up on the mail-list that I think warrant extended discussion here. Those questions essentially revolve around Theme branding vs. “white labeling”: should footer credit links be required to be user-configurable (i.e. disabled) via Theme option? Should Themes include “branded” default logos or demonstration content, such as slider content, Twitter feeds, etc.?

    Rather than making decisions (or creating new Guidelines) on the fly, let’s discuss those questions, and the issue of branding vs. “white labeling” as a whole, here. What I would envision coming out of this discussion would be a clarification of the Guidelines, to indicate more clearly what we’re currently requiring/enforcing, under a “Theme Branding” heading (or similar) that would envelop the existing “Credit Links” requirements.

    For example: logos. Some Themes add a “logo” Theme option, but set the default as a text-as-image Theme Name “logo”. This is obvious branding, and obviously an instance where the user would rather have the Theme default to displaying the user’s configured Site Title, rather than a Theme-branded text-as-image “logo”. But a different developer may want to display a generic/arbitrary logo by default, to demonstrate the Theme’s custom logo feature. So: we should discuss where/how we want to draw the line of appropriateness.

    In a discussion such as this one, my default position is: with all else equal, which decision is in the best interest of the end user? But it is equally important to consider the needs and interests of developers, as well. Guidelines should not be onerous or unreasonable for developers. I would contend that, when initially activating a Theme – whether on a new site or a site with established content – an end user will not want then to have to go through the Theme to “disable” the demo/branding content. So, I think it is reasonable to require that all default/demo imagery be generic/non-branded/”white-labeled”.

    To take a counter example: footer credit links. Should developers be required to make footer credit links user-configurable (i.e. able to be disabled) via Theme option? I don’t think so. We put enough requirements around the form/display of footer credit links to ensure that they are appropriate, that I think requiring them to be user-configurable via Theme option crosses the line into being too onerous. (Consider all the Themes that have no Theme options; should we force developers of those Themes to incorporate all the overhead of Theme options, just for footer credit links?) What might be more reasonable, however, would to to recommend that footer credit links be user-configurable, via Theme option, custom filter, template-part file, etc.

    Feel free to discuss from both high and low levels: from principle to guideline. But, please try to avoid the, “but Theme X does this” type of arguments. That we are discussing the need to clarify the Guidelines implies that existing Guidelines have been interpreted differently, resulting in different review comments for different Themes. Our aim here is to find consensus regarding the correct approach to handling these issues, regardless of how these issues have been handled consistently or inconsistently in the past.

     

    • Srikanth 1:01 pm on February 19, 2013 Permalink | Log in to Reply

      My opinion is that theme user should not have to go and disable even the generic logo, Themes should display site name as default.

      • Chip Bennett 1:06 pm on February 19, 2013 Permalink | Log in to Reply

        Keep in mind that we try to give as much deference as feasible to the developer’s Theme design aesthetic. That “generic logo” could reasonably be a part of that design aesthetic. I could see it being reasonable at least to recommend that Themes display Site Title by default, rather than a generic default logo.

        • John Saddington 2:10 pm on February 19, 2013 Permalink | Log in to Reply

          i love that you’re considering how much the “generic” may play a part of the overall design layer – that’s really thinking critically and openly about the variety of use-cases. I like this.

          But this “humble submission” and deference gives a lot of flexibility which is going to be hard to use for any development of a concise and explicit guideline and/or policy. Just top-of-the-head thoughts here.

          • Chip Bennett 2:24 pm on February 19, 2013 Permalink | Log in to Reply

            If anyone bangs the explicit, objective requirements drum, it’s me. :) But those who say that we cannot make the guidelines so rigid that Themes become cookie-cutter have a valid point. A Theme could be designed to incorporate both a logo and Site Title simultaneously, or a Theme could be designed to incorporate both, but not simultaneously, or a theme could be designed to incorporate only a logo, or a Theme could be designed to incorporate only a Site Title.

            I’m not convinced that we should require developers to use any one of those alternatives, to the exclusion of any of the others.

    • Srikanth 1:24 pm on February 19, 2013 Permalink | Log in to Reply

      Okay, site title as recommended and generic logo if they must have a default logo.

      Theme authors can take the user upon activating the theme to a welcome tab of theme options page where they can tell what all awesome features the theme has and explain that they can upload a logo, set a fav icon etc

      • Srikanth 1:37 pm on February 19, 2013 Permalink | Log in to Reply

        Also if a generic logo is set by default, there should be an option to show site title instead of any logo. Not all of them will have a logo :)

        • Chip Bennett 1:41 pm on February 19, 2013 Permalink | Log in to Reply

          I still think that is a bridge too far. We already require that Site Title be incorporated in some manner, and I think it would unnecessarily restrict design aesthetic to require that any custom logo also be able to incorporate Site Title.

          • Srikanth 1:44 pm on February 19, 2013 Permalink | Log in to Reply

            I mean there should be an option to disable logo entirely and choose to have site title

            • Chip Bennett 2:04 pm on February 19, 2013 Permalink

              I know what you mean, but I think that such a requirement would be going too far.

          • Srikanth 2:29 pm on February 19, 2013 Permalink | Log in to Reply

            Okay, lets consider this scenario :

            User installs a theme.
            Theme displays default logo (either generic or brand name).
            User can upload his/her logo and it will replace default logo.

            But if user doesn’t have a logo, what then? will he be forced to use the theme with default logo? forced to change the theme?

            Even if site title is somewhere else on the site, he/she will still be forced to live with default logo?

    • Stephen 2:27 pm on February 19, 2013 Permalink | Log in to Reply

      I am new to this community. Here is my 2 cents.
      1. Logo (generic or not) should be allowed as long as it can easily be removed to replaced (i.e. upload).
      2. Credit link is the credit for theme author. We should not require theme option to remove it. However I believe it should be in template file (i.e. footer.php) not through hooks, functions.
      I am more concerned about repo has become marketing site flooded with lite versions.

    • Zach Russell 2:58 pm on February 19, 2013 Permalink | Log in to Reply

      Chip,
      I completely agree with you the first topic. It really doesn’t make sense to put your own logos/images in with the default theme because 99% of the time, it will be replaced with the site’s logo or text anyway. I think it is kind of a waste of time to put effort into something that will be changed almost immediately.

      From the footer link’s perspective, I am torn. As a developer, I want to have my name on everything I do, and footer links make sense for that. Giving an easy way to filter out credits is also the most user-friendly way to do this, especially through a theme options page. I am also an SEO, and from that perspective, I am kind of torn. By putting links that would be more or less universal across all sites can pose some issues from a “keyword spamming” stance. We all remember when EDUBLOGS got blacklisted by Google for a similar reason, even if they weren’t intentionally spamming. Just some food for thought.

    • Frank Klein 3:28 pm on February 19, 2013 Permalink | Log in to Reply

      Concerning the Credit link, I don’t recommend requiring this to be disabled as an option. If someone doesn’t want the link to display, there are easy ways to remove it (for example some custom CSS via Jetpack).

      Concerning the logo discussion, I think that we should not restrict developers, however when using a custom logo, there should be an option to simply not display a logo at all. This would avoid developers having to change their Themes to work with a title, and it would allow users to get rid of the default logo quickly if they don’t have a custom one available.

      Concerning the other “branded” elements, I’m strongly against any demonstration content that comes bundled with the Theme code. However I recognize that such content is useful to show all the Theme’s features and help users figuring out how the Themes works.

      One possibility might be to point users to XML files with demo content (available for download on the Theme URI website for example). This would allow the users starting a site from scratch to easily import content, while taking into account those users who already have existing content.

    • Bryan Hadaway 3:52 pm on February 19, 2013 Permalink | Log in to Reply

      1. Configurable Footer Credit

      Since most themes do not have theme options to begin with (as I first pointed out in the mailing list) nor should they ever be required to, I think this point is moot.

      The hard-coded theme author credit is a respected staple of free WP themes and users have always been free to remove them as they please under the GPL.

      While, I’m sure we can all agree that we should never obscure or obfuscate the credit link to make it purposefully difficult to remove nor should we hide its removal behind a paywall misleading the user to believe the only way to remove is to upgrade, it is also not our (as theme authors) responsibility nor obligation to educate or provide convenience to users in removing our credits. This crosses the line of what should reasonably be expected from a free theme.

      This is no different than educating them on how to change fonts, colors and other styles, which no free theme author is required to cover such support. Since we’re allowed to hard-code our cred links, themes do not have to have theme options (in fact WP wants us to move away from this anyways) and we’re under no obligation to teach our users how to hack the themes and it would be ridiculous for any of this to ever change, we simply cannot allow this to happen.

      2. Demo Content

      This seems like an easy one. NO HARD-CODED DEMO/PLACEHOLDER CONTENT ALLOWED. NO SPAMMY DEMO/PLACEHOLDER CONTENT ALLOWED.

      However, if it’s merely demonstrating configurable options and does not contain promotional language, URLs etc then it’s fine. Why should it not be branded if relevant to the theme? A theme name in and of itself IS branding.

      I’ve seen the arguments both ways from users, pretty much 50/50:

      1. “How do I get my site to look like the demo?”

      2. “How do I remove the demo content?”

      This is definitely dangerous territory because theme features and methodologies vary drastically here in 2013 between one another.

      So you’re very right in your concern that what’s a good guideline for one theme that would benefit its users might be bad for another theme and its users.

      That’s why I don’t think the discussion should be about whether demo content is allowed or not, or even whether it should be enabled/disabled by default, because this will all vary between themes.

      As long as demo content is not hard-coded, the only additional guideline should be what can the demo content contain.

      Thanks, Bryan

    • Justin Tadlock 5:00 pm on February 19, 2013 Permalink | Log in to Reply

      Configurable footer credit links

      No, to this. We’ll be requiring that themes add theme options, something I’d like to see a lot less of. How footer credit links are done is something that’s been established over many years as a WordPress theme standard. There’s no point in trying to change that.

      Also, if the theme is internationalized, there’s already the gettext hook that allows this to be filtered.

      Default logos, Twitter feeds, etc. (not related to content)

      For header logos, Twitter widget feeds, and things of that nature, I don’t see an issue with branded items. These are user-configurable items that are going to be changed. They just have to be configurable via the admin.

      Branded content-related items

      For things relating to the content such as a slider image or thumbnail, branding shouldn’t be allowed unless it’s configurable via a theme option. A generic image is okay.

      Let’s look at thumbnails as an example. Suppose I added a “Theme Hybrid” branded default thumbnail to display on archive-type pages when a user didn’t set a thumbnail. I’d be potentially advertising my site on 100s or 1,000s of pages on that user’s site. That’s just a bit too far and shouldn’t be allowed. As a theme author, I’d be forcing my users to create specific content, and that’s outside the scope of what a theme should be allowed to do.

    • mercime 7:06 pm on February 19, 2013 Permalink | Log in to Reply

      For reference, this conversation arose from theme author’s post at http://lists.wordpress.org/pipermail/theme-reviewers/2013-February/011836.html

      One of the issues mentioned and in contention is that not of a tasteful text credit link back to the author’s site but that of the theme author’s LOGO at the footer of the theme. Which is why I posted => “User should be able to replace/remove Cyberchimps logo located in the footer. ” at http://themes.trac.wordpress.org/ticket/11163#comment:2

      If the theme author is going to add his/her company logo at the footer of the theme, the user should be able to remove it without going through the ringer.

      Good points made above – User advocacy
      Srikanth – http://make.wordpress.org/themes/2013/02/19/theme-brandingwhite-labeling-guidelines/#comment-29351
      Stephen- http://make.wordpress.org/themes/2013/02/19/theme-brandingwhite-labeling-guidelines/#comment-29350

      • Chip Bennett 7:12 pm on February 19, 2013 Permalink | Log in to Reply

        But the appropriateness or tastefulness of a text link vs a logo link is entirely subjective. Who is to say that a logo isn’t more tasteful/less obtrusive than a text link?

        And why should removing a logo footer credit link be treated any differently from removing a text footer credit link?

        • Bryan Hadaway 10:07 pm on February 19, 2013 Permalink | Log in to Reply

          Exactly, doesn’t make any different how a credit link is implemented as long as it’s not breaking any guidelines or intruding on the theme, making it not function correctly etc.

          In the specific example of CyberChimps, what’s the difference between text that says CyberChimps or a graphic that says CyberChimps? Indeed, purely subjective as to preference. Either way, they’d both need to be removed the same way as with any other theme since the beginning WP themes, manually.

      • mercime 2:14 am on February 20, 2013 Permalink | Log in to Reply

        Theme author’s logo/image is obtrusive i.e., intruding, compared to text credit link in the footer. The issue is not a credit link but using an image as a credit link. There’s a big difference. It’s as simple as that.

        Do you really believe a user wants the image of a monkey or anyone else’s logo in the footer throughout his/her site? No way.

        Another good point by Srikanth below – http://make.wordpress.org/themes/2013/02/19/theme-brandingwhite-labeling-guidelines/#comment-29383

        • Srikanth 3:00 am on February 20, 2013 Permalink | Log in to Reply

          Credit links should be pretty straight forward : “Designed by xyz.com” or “Powered by WordPress & xyz theme”

          WordPress traffic is quite expensive, try buying all the traffic you are getting for free here and it will cost you a lot.

          No need to get greedy and plaster the user’s site with brand logo’s, pretty soon WordPress foundation will come along and say no more up-sell’s. They already have a theme team and they are submitting quite a few themes themselves.

          Lets not give them an opportunity to get rid of us, something is better than nothing :)

          • mercime 3:44 am on February 20, 2013 Permalink | Log in to Reply

            >> pretty soon WordPress foundation will come along and say no more up-sell’s.

            That’s not likely to happen because of logo in footer :-) Careful, someone might take you seriously and lambast you with something or the other, lol.

            I say protect the users from monkeys, leaves, jungles or whatever logo/image-credit-links in the footer.

        • Justin Tadlock 7:24 pm on February 20, 2013 Permalink | Log in to Reply

          I actually think the logo (in this particular instance) looks more professional than a basic text link.

        • Bryan Hadaway 1:32 am on February 21, 2013 Permalink | Log in to Reply

          You’re still only demonstrating subjective points.

          The funny thing is most of the users love that little monkey, I get more requests for “How can I add my CyberChimps affiliate link to the footer logo?” then how they can remove it.

          But, that’s just to rebuttal your subjective point which is irrelevant and so is my response to it.

          You can say that you think an image credit link is uglier than a text credit link, that’s your OPINION. You can’t decide that everyone agrees with that and imply it as factual or objective.

          You’ve already been disproved:

          http://make.wordpress.org/themes/2013/02/19/theme-brandingwhite-labeling-guidelines/#comment-29413

          Perhaps some people like image based credits and hate text based ones? I don’t know, there hasn’t exactly been a study on this, I only know how I feel and you only know how you feel and handful of others here (which we come no where near representing the common WP user mind you).

          In any case, this is really ALL irrelevant.

          This discussion isn’t about image credits, it’s about two separate subjects:

          1. Should users be able to remove credits (regardless of the style of credit) without hacking the theme.

          Which can only mean that authors would now have to build this into themes or WordPress would have to build something into itself and credits would then have to use a WP function.

          All crazy, never going to change.

          2. Should branding be allowed in themes (regardless of where).

          I think the answer to that will remain yes, but the guidelines will be more specific on what are considered appropriate branding images.

    • CyberChimps 9:53 pm on February 19, 2013 Permalink | Log in to Reply

      The two main issues at hand here are:

      Issue 1: Branding demo content, and the ability to put a theme shop / theme name / or logo on default images.

      Many themes including CyberChimps offer feature sliders, portfolios, Twitter feeds, etc. To show these features off on the Preview section on wordpress.org we have to load defaults.

      Example of a default slider image: http://wp-themes.com/wp-content/themes/ifeature/images/branding/slide1.jpg

      The core issue here really is are we allowed to put our brand on default images?

      From a user standpoint branding helps them identify themes by authors or theme shops they trust, it also shows them the potential functionality of theme, and it also indicates to them that they need to replace this content when they use the theme.

      The con is if a user doesn’t change the default images then they will carry over the branding of the default images.

      Personally I believe we should be able to brand our themes as long as it doesn’t contain a link, violate the credit rules or limit the functionality of the theme or mislead users. We should be supporting theme shops and theme authors so they continue to contribute. If we ban branding from .org then we are literally forcing attribution to a single footer link. I’m not sure I see why that’s necessary.

      I believe we should all be able to market and brand our themes as being made by us, and released under the GPL for the greater good. Taking the ability to brand our themes away is a slippery slope that may discourage theme shops from releasing more themes on .org.

      Issue 2: Footer credit links.

      Again I believe we should be able to use logos instead of text, and I do not believe there is any valid or logical purpose for theme authors to provide a theme option to easily disable the credit link.

      Themes are released on .org under the GPL for the greater good, anyone can edit them however they want, including removing the credit link. Are we really going to punish theme authors for using frameworks, hook systems, functions, or other logical programming techniques because you have to edit the core file or hook? These methods don’t exist to be deceptive, they exist because they allow us to organize our code more efficiently. A user can easily remove the hook, or edit the core file if they want to. There is nothing stopping them, so why should we be forced to provide a theme option to do this for them?

      Furthermore, if we do ban branding on .org, and implement this credit removal theme option then we’re really telling theme authors they get no credit for their themes if you release them on .org.

      Given all the issues facing the WordPress community and ThemeForrest right now, we should be opening standards to get more people contributing themes under the GPL and via WordPress.org, not making rules to phase out attribution, and credit.

      • Justin Tadlock 3:14 am on February 20, 2013 Permalink | Log in to Reply

        Any branding within the *content* should be strictly forbidden for the reasons I stated earlier. I’d argue that a post-thumbnail/slider-image is a part of the user’s content and should contain no marketing/branding/advertising material at all (with the exception of a theme option to configure these things).

        I have no issues with branding elsewhere, to a degree anyway. I’m even fine with a tasteful image (subjective, I know) instead of a text link in the footer.

        For your particular theme, Eclipse, this all seems fine to me. The branded images are configurable via theme options, so it’s not something the user is stuck with without having to change their content.

        • memuller 11:14 pm on February 23, 2013 Permalink | Log in to Reply

          In short:
          Keep branding the theme with footer, text-based credits, and allow developers to brand anything else as they see fit and include demo content (branded or not), as long as it’s the user choice to allow this, and this choice can be easily reverted (and remade).

          In both cases, the developer community will survive and deal with this, since for us, it’s a simple rational choice – we either do these thing if they’re worth the trouble, or we won’t. For the user, however, it’s not that easy – an undesired logo or a bad experience with demo content can be harmful regardless of any other factors.

          …now, for some boring stuff:

          About the use of logos and branded content as credits:
          @frank, @justin: mostly agreed.
          @cyberchimps: I think the issue here is that, even if some uses of logo/images as footer credits can be tasteful and valuable, the act, by nature, is obtrusive, since images *are* obtrusive.
          What if the theme offers different colors – will the logo change to match then? What about layout responsiveness? If the user tries to remove the image via CSS, won’t it be easier for him to break the layout?
          To avoid inflating the guidelines and theme review processes with worries about issues like these, I think images as credits on the footer should not be allowed, unless it is presented as an option to the user, and that option is disabled by default. That is, the user can *chose* to user your logo/whatever as a form to give credit.
          That empowers the user, and is a good heuristic for theme developers – if you think adding this theme option is not worth the hassle, then it indeed isn’t.

          About branded and demo content:
          @cais: mostly agreed.
          @brian: agreed, but I would still add that enabling such content should be a user choice. That’s easy to do in a nice way – when first enabling the theme, it can prompt for this choice; there can be a theme option for this, or a dashboard widget for loading specific content parts (eg. loading only the default taxonomies, or a specifit content type). Again, I think its a good heuristic for developers – if your theme is complex enough to use demo content in a useful way, you likely won’t mind the trouble.

      • Frank Klein 6:58 am on February 20, 2013 Permalink | Log in to Reply

        In order for a user to recognize an author or Theme shop by only looking at a logo, you’d have to build up some serious brand recognition first, which you do by branding your themes. So it’s a chicken-and-egg problem.

        I don’t agree with your argument on trust either, the whole point of the Theme review is to ensure that all Themes available on .org are trustful, regardless of the author.

        I’m squarely against the any branded content that comes with the theme. I don’t think that banning branding from .org will discourage Theme shops from releasing Themes on .org, because .org provides them with access to a huge audience to which they can distribute light versions of their themes. If shops release on .org it’s because it makes business sense, not for the greater good.

        As far as the credit logo is concerned, I think that tasteful is difficult to define. But I think starting with a maximum size of this logo is a good starting point.

        • Justin Tadlock 7:18 pm on February 20, 2013 Permalink | Log in to Reply

          A maximum size would be hard to define for a credit logo too. This is something that should fit in with the design of the theme, not some review team’s “standard” logo size.

          A little bit of common sense sometimes goes a long way. Of course, you wouldn’t put a 500px-high logo within a footer with 16px text.

    • stuartwider 10:00 pm on February 19, 2013 Permalink | Log in to Reply

      Footer links:
      I’d say l agree with Justin. As long as its not intentionally obfuscated and hard to remove I don’t think that there needs to be an option specifically to remove it. I dont think it matters either if its a text link or a image link.

      Users themselves have the choice whether they want to use a theme, and if they see a text link or image link at the bottom that they dont like then they have the choice not to use the theme. They have ultimate subjective say over the aesthetics of the theme by voting with their feet… (or download clicks in this case).

      Default Logos, demo content etc
      Sometimes these things are very necessary in order to demonstrate the features of the theme in the theme preview and how the theme works. As long as they easily configurable in the admin and not overtly promotional in nature I see no reason why demo content should not be branded elements. The user will remove them anyway in the theme options (no difference whether the elements are generic or branded) and in doing so learn how the theme works. Using generic elements vs branded elements makes no difference.

      What classifies as generic content vs what is branded content is also subjective anyway, so why add another decision making headache?

      There are already themes on the repo which are good examples of how to do this tastefully, so lets not throw the baby out with the bath water and allow the developers a little credit.

      Theme users are quite robust creatures and will not be harmed in any way if they just happen to see a cyberchimp, internet-dolphin or web-ferret tastefully displayed on the demo content of their newly downloaded theme. They will just go Appearance > Header and upload their own e-Platypus.

    • Srikanth 11:13 pm on February 19, 2013 Permalink | Log in to Reply

      Large percentage of users don’t even know how to set a featured image, forget about replacing a hook.
      No need to provide a theme option, but link should be plain html.

      Thats why i think, all this should be opt in, you can take the users to welcome tab upon theme activation and explain to them about the features like logo upload and what not. Experienced users will take full advantage and ordinary Joe will not walk around with huge billboard advertising your company for free.

      When i activated a theme for review recently, that’s what i saw : a giant billboard advertising the company with no user content at all, that too when i was testing it with theme unit data.

      This whole review team idea was created to protect users.

    • Paul 11:33 pm on February 19, 2013 Permalink | Log in to Reply

      how about the screenshot image, can that be branded, as in have a watermark logo or similar. or even the URL of the theme author on it?

      • Daniel 11:37 pm on February 19, 2013 Permalink | Log in to Reply

        Well it already in guidelines:

        “screenshot.png

        Recommended 4:3 W:H ratio, size 600x450px (2x the previous 300x225px, to account for Retina displays).
        Maximum size: 600x450px
        Should be a “reasonable facsimile” of the Theme after it is initially activated with default options”

        • Paul 11:42 pm on February 19, 2013 Permalink | Log in to Reply

          that doesn’t mention anything about branding

          • Daniel 11:45 pm on February 19, 2013 Permalink | Log in to Reply

            Are you talking about putting a watermark over the image (Like how Istock put their photos up)?

    • d5creation 4:50 am on February 20, 2013 Permalink | Log in to Reply

      I don’t see an issue with branded items (Such as Theme Logo, Slide Images) if these are user-configurable items via the WP-Admin easily. But these should not be linked.

    • Edward Caissie 4:08 pm on February 20, 2013 Permalink | Log in to Reply

      Although I have no real issues with user configurable “branded” demonstration content (read: header logos, slider images, etc.) … or whatever you want to call it. I do see it as something that should be addressed, at a minimum, in the theme’s ‘readme.txt’ file and how it can be “easily” disabled and/or removed.

      Simply put, just because it is configurable does not mean it is easy to configure. If “branded” content is used it must be easy for the end-user (think: one-click / push-button simple) to not use this “branded” demonstration content.

      Similarly, I see the footer credit in a text link as more or less a non-issue; but, if it’s “shiny” (like a logo) then once again I would strongly recommend instructions to easily hide / remove / replace with a text link be included, again at a minimum, in the theme’s ‘readme.txt’ file.

      As a caveat to this idea on the footer credit as logo, if the theme already implements theme options then an option to change the “logo” credit link to a text link would be acceptable rather than explaining how to remove it.

      • Bryan Hadaway 1:38 am on February 21, 2013 Permalink | Log in to Reply

        Regarding branded content:

        Maybe it’s as simple as a few extra guidelines:

        “If your theme utilizes demo content to demonstrate key features, it must provide ample documentation for users on how to either remove or replace demo content with their own.”

        “Demo content may match the overall look and feel of the theme, basic branding and colors, but may not contain promotional language or URLs.”

        Cased closed?

        • Srikanth 2:24 am on February 21, 2013 Permalink | Log in to Reply

          Opinions are still split, dunno how it is resolved in such cases…

      • @mercime 11:28 am on February 21, 2013 Permalink | Log in to Reply

        @cais Thank you for articulating those points so very well. Just outstanding.

    • Thomas 11:13 am on February 21, 2013 Permalink | Log in to Reply

      What about a guideline which requires own demo images to provide short information how to remove or replace it directly in the image?

      Since I got a lot of questions from users how to change the personal picture in my business card theme, I simply added a short line to my default image: http://wp-themes.com/wp-content/themes/zeebizzcard/images/default_header.jpg

      For example demo slider images should include a line “Learn more how to configure the slideshow and place your own images here at readme.txt” or something similar. The user sees immediately he is looking at demo content and get more information how to replace or remove it.

      In my opinion most users never ever look in the readme.txt by themselves, so any information putted there never gets read ;)

    • Chip Bennett 3:14 pm on February 23, 2013 Permalink | Log in to Reply

      All: let’s please keep the scope of the discussion on the Guidelines.

  • Chip Bennett 3:26 pm on February 15, 2013 Permalink | Log in to leave a Comment
    Tags: , , Guidelines   

    Child Theme Support 

    I have just added a draft section to the Theme Review Guidelines, to cover requirements for Child Theme support/facilitation for hosted Themes:

     

    • Themes are required to facilitate the use of Child Themes. A “basic” Child Theme (i.e. a style.css with Template header tag and @import() of the Template style.css), when activated, should function exactly as the Theme itself functions.
    • Themes are required to include functional and resource files in a manner that facilitates the use of Child Themes:

     

    Based on discussion on the mail-list, consensus appears to be that facilitating end user use of Child Themes is beneficial, so this discussion is the first step in incorporating Child Theme support into the Guidelines.

    Please discuss. Do you agree/disagree that Child Theme support should be added to the Guidelines? Are the above Guidelines sufficient? What should be added/removed/changed? What about pluggable/filterable functions?

     

    • Srikanth 3:31 pm on February 15, 2013 Permalink | Log in to Reply

      I would agree with the above as required and anything else optional. Don’t want a lot of additional burden.

      • Chip Bennett 3:34 pm on February 15, 2013 Permalink | Log in to Reply

        Agreed. We don’t want to add onerous burden. We simply want to ensure that developers are accounting for Child Themes, which primarily boils down to proper use of get_template_directory_uri() vs get_stylesheet_directory_uri().

        • Srikanth 3:38 pm on February 15, 2013 Permalink | Log in to Reply

          Yes, Beginners like me would be happy to cater to new bloggers and leave the complicated stuff to heavy hitters :)

    • nofearinc 3:34 pm on February 15, 2013 Permalink | Log in to Reply

      Looks good to me. Maybe there should be an option for very large themes with ‘fat’ frameworks to explicitly warn people that due to theme options or anything else child themes are not supported, but the rule should be required as defined above.

      • Chip Bennett 3:38 pm on February 15, 2013 Permalink | Log in to Reply

        Do you foresee particular issues with Child Theme support with Themes that incorporate framework (i.e. code library) code? Is there any particular reason that such Themes should be exempted from this guideline? My initial reaction is that I don’t see any reason to allow for such an exemption, but I am always looking for unintended consequences.

        • nofearinc 3:51 pm on February 15, 2013 Permalink | Log in to Reply

          I’m just trying to be safe when a large framework (similar to PageLines) is getting ready to be released for free and reach hundreds of thousands of downloads and is self-sufficient (theoretically). It’s not 100% required, but sometimes the changes could take a significant time for a product that’s ready and working without a further need of files being changed.

          • Edward Caissie 4:04 pm on February 15, 2013 Permalink | Log in to Reply

            Within reason, if a “large framework” is being released and the Theme Author thinks its Child-Theme friendliness may be in question then perhaps it should be the recommendation to have some sort of documentation included / referenced to help alleviate any pain points.

            I do not see any requirements for “exemptions” as the Theme Author (hopefully) knew what they were doing when they created and chose to release their “large framework” and within reason should have taken into account Child-Themes by default.

            • nofearinc 4:16 pm on February 15, 2013 Permalink

              your ‘documentation’ was my ‘explicitly warn people’ idea. I don’t say it must be a rule, I’m raising the question for discussion as I’ve personally encountered themes that are not child theme compatible, working properly and switching between get_template_directory_uri/get_stylesheet_directory_uri is not enough. We could just drop that option and discuss again in the mailing list IF any theme falls in that scenario.

            • Chip Bennett 4:19 pm on February 15, 2013 Permalink

              My concern there is: is this truly a special case, or did the framework developer simply fail to account for Child Themes? Is there some extenuating circumstance about the Theme that would preclude the use of Child Themes?

            • nofearinc 4:23 pm on February 15, 2013 Permalink

              the simple case in point is:

              1. a theme has already been built with numerous options
              2. every popular option that most child themes cover (logo type/position, footer, credits, whatever) is covered by theme options
              3. switching to get_stylesheet_directory_uri() is breaking the current design in a way that it’s not trivial to convert it (might take like a couple of days, or 2 weeks, for full compatibility).

              Probably an edge case, but since usability and UX are trendy and more and more themes incorporate option frameworks, that doesn’t sound that absurd to me.

            • Chip Bennett 4:26 pm on February 15, 2013 Permalink

              The part I’m struggling to grasp is: how does switching from get_stylesheet_directory_uri() to get_template_directory_uri() cause breakage for a stand-alone (i.e. Parent, i.e. Template) Theme? For a stand-alone Theme (i.e. not a Child Theme), both functions return the same URL.

              So, any potential breakage would have to derive from some other development element/criterion on the Theme.

            • nofearinc 5:48 pm on February 15, 2013 Permalink

              Chip, it’s not that it’s breaking the theme if you do the switch. There are just random stylesheets applied after the so called style.css where the child theme can’t take over the restyling or there is a router responsible for managing the template generation.

              With that said, point 1 contradicts point 2, or rather executing point 2 won’t lead to a child theme support.

              Again, it might be an edge case, there are just too many ways implemented in themes and frameworks out there for styling and template generation that are not fully compatible. We might reject all of them for that ‘freestyle’, the question is should we do it if it’s unlikely for people to ‘inherit’ it with a child theme.

            • Justin Tadlock 6:05 pm on February 15, 2013 Permalink

              There are just random stylesheets applied after the so called style.css where the child theme can’t take over the restyling

              The only thing that we’d need to worry about is if the child theme’s style.css is loaded. The other stylesheets are irrelevant in terms of this discussion. They’re a part of the theme design. Nowhere is it required nor should it be that a child theme must be able to overwrite all elements of a parent theme.

              or there is a router responsible for managing the template generation.

              As long as the template are using the proper template-loading functions, I don’t see a problem here.

            • nofearinc 6:09 pm on February 15, 2013 Permalink

              Justin, I do agree with you, but most people expect that a child theme could override everything.
              We should leave all doubt out of the door and either set strict rules, or just elaborate on what could a child theme do. Does that make sense?

            • Chip Bennett 6:27 pm on February 15, 2013 Permalink

              But we also require that all stylesheets other than style.css be enqueued, rather than hard-coded. So, a Child Theme can always dequeue any subordinate stylesheets (or dynamic CSS functions, or scripts, for that matter).

            • Justin Tadlock 6:38 pm on February 15, 2013 Permalink

              Justin, I do agree with you, but most people expect that a child theme could override everything.

              Most of my users don’t expect a child theme to be able to override everything. I’ve been doing child themes a lot longer than most people here, and I can count on one hand the number of users who have asked about something like that.

              We should leave all doubt out of the door and either set strict rules, or just elaborate on what could a child theme do. Does that make sense?

              1) A child theme must be able to overwrite any parent theme template (not any file, just templates).

              2) A child theme’s style.css file must be loaded using the get_stylesheet_uri() function.

              Both of these things are already covered under the Theme Review requirements, so we already have the rules in place.

            • nofearinc 6:42 pm on February 15, 2013 Permalink

              I do agree with both last statements by Chip and Justin. The child theme can indeed dequeue if needed.

    • ZaMoose 3:39 pm on February 15, 2013 Permalink | Log in to Reply

      We should create aliases within the code for `get_parent_theme_uri()` and `get_child_theme_uri()` to adhere to the WordPress-should-be-read-as-close-to-English-as-possible goal.

    • Edward Caissie 4:05 pm on February 15, 2013 Permalink | Log in to Reply

      Just grabbing my mailing list reply …

      Those guidelines look fine.
      I like the idea of how a “basic” Child-Theme is spelled out, and I think you covered the use of the the `template` versus `stylesheet` usage.

    • @mercime 5:48 pm on February 15, 2013 Permalink | Log in to Reply

      You got my YES vote :-)
      Thanks Chip.

    • Justin Tadlock 5:57 pm on February 15, 2013 Permalink | Log in to Reply

      As far as I’m concerned, the guidelines already require and have required for a long time that themes be child-theme ready. We already require all functions and hooks to be used properly.

      The only four functions you must worry about are:

      • get_template_directory()
      • get_template_directory_uri()
      • get_stylesheet_directory()
      • get_stylesheet_directory_uri()

      If you’re using a stylesheet function in your theme, you’re probably doing it wrong and shouldn’t pass the current guidelines. Of course, that’s a generalization, but it’s usually a good rule of thumb to go by.

      • Chip Bennett 6:28 pm on February 15, 2013 Permalink | Log in to Reply

        I agree ,and I’ve made related comments in Theme reviews. Most of the time, the developer just didn’t know why one should be used rather than the other, and was happy to make the change.

        This discussion is mainly an effort to formalize what you and I (and probably others) have interpreted from existing guidelines.

  • Chip Bennett 12:49 am on January 17, 2013 Permalink | Log in to leave a Comment
    Tags: Guidelines, Screenshot   

    Clarification of Screenshot Guidelines 

    The current guidelines for the Theme screenshot read as follows:

    • Recommended 4:3 W:H ratio, size 600x450px (2x the previous 300x225px, to account for Retina displays).
    • Maximum size: 600x450px
    • Should be a “reasonable facsimile” of the Theme after it is initially activated with default options

    I think a bit of clarification is in order, with respect to Themes designed to be used with a custom front page (i.e. front-page.php). I think that, in this case, the intent of the guidelines includes discretion to account for the design intent of the Theme. To that end, I would like to clarify that appropriate screenshots include the custom front page (front-page.php) display, even if that display requires the user to configure Settings -> Reading in order to display it.

    Bear in mind that the original purpose of this guideline was to prevent undue marketing via the screenshot, either with unavailable “dummy” content displayed, or a screenshot that was a company/Theme logo, or that displayed something other than the Theme itself. A screenshot that displays the Theme’s front-page.php view is nothing like any of those mis-uses of the screenshot, and is a legitimate representation of the Theme.

    What are your thoughts? Should the guidelines formally be clarified in this regard?

    Edit

    I forgot to mention: there is also an open Trac ticket to incorporate functionality to let Themes declare that they are designed to use a static front page, and “opt in” to that configuration as the default. If/when that ticket gets implemented, we’ll need to have this clarification anyway.

     

    • Emil Uzelac 1:05 am on January 17, 2013 Permalink | Log in to Reply

      Most definitely +1 from me!

    • Amy Hendrix (sabreuse) 1:05 am on January 17, 2013 Permalink | Log in to Reply

      Maybe something like “Should be a ‘reasonable facsimile’ of the Theme as it appears at activation, showing either the blog page or a static front page”?

      I agree that the point was to avoid either totally uninformative images — logo-only screenshots or the like — or those that would take a ton of elaborate setup rather than looking something like they’d look out of the box. Showing the theme with a static front page displayed is totally within the spirit of the guidelines.

    • Edward Caissie 1:05 am on January 17, 2013 Permalink | Log in to Reply

      I think it’s a good idea to add this clarification regarding what different “views” the screenshot can show.

      What also might be considered is “composite” screen shots that shows “responsive web design” (RWD) style themes such as a desktop/tablet/mobile collage? Personally I find that concept to be acceptable but something that can be referenced in this case may also help. For example, a collage style screenshot may only be used with a RWD style theme, etc.

      Also to consider in the screenshot guidelines is the past idea of having multiple screenshots … if that is going forward(?) then the guidelines should be taking that into account as well.

      • Emil Uzelac 1:17 am on January 17, 2013 Permalink | Log in to Reply

        No doubt in my mind that (RWD) screenshots are good and +1, however we should also add that if (RWD) is in the screenshot, Theme should follow some type of guidelines in that regard as well.

        Basically if one claims to have (RWD) Theme should be Responsive “all the way”, not just partially.

        If needed, I’ll gladly put some guidelines for that :)

      • Chip Bennett 1:31 am on January 17, 2013 Permalink | Log in to Reply

        Under the current, one-screenshot limitation, I am against having “composite” screenshots. It’s partly an aesthetic thing (all the screenshots look similar when searching Themes, allowing the user to scan more easily the differences among the displayed Themes), and partly because allowing composites would necessitate another layer of bureaucracy in the screenshot guidelines.

        However, I’m hopeful that the multiple screenshot idea will move forward in the near future, since it would make it much easier for us to support multiple views for Themes: not just responsive layouts, but also color schemes, and other configurable aspects of Themes.

        • Emil Uzelac 1:37 am on January 17, 2013 Permalink | Log in to Reply

          multi-screenshots is what I was referring to as well.

        • Edward Caissie 3:12 pm on January 17, 2013 Permalink | Log in to Reply

          I agree adding a “composite” screenshot guideline would definitely also add a layer of bureaucracy (that we do not need) but I also see it as something needed given the intent of authors to continue with RWD.

          I also believe it would be better served by multiple screenshots being available in themes but until that is added to core this better idea really serves no purpose. Which leads to how do we get the “Multiple Screenshots” back on (core) trac? Such as possibly getting this reversed: https://core.trac.wordpress.org/changeset/20590

    • Frumph 1:08 am on January 17, 2013 Permalink | Log in to Reply

      Standard is 4:3 640×480 ratio which most screen grabs use because well, it’s a standard.

    • Chip Bennett 1:48 am on January 17, 2013 Permalink | Log in to Reply

      Updated post to add a link/reference to this Trac ticket:
      http://core.trac.wordpress.org/ticket/19627

    • Kirk Wight 3:44 am on January 17, 2013 Permalink | Log in to Reply

      I like Chip’s original idea: let’s state the screenshot must be from either the blog or front page view upon activation.

      I also think it’s another layer of complication to allow composites or RWD views before we actually have multiple screenshots.

    • Konstantin Obenland 5:48 pm on January 17, 2013 Permalink | Log in to Reply

      I on’t know how much it’ll add to the topic of this discussion, but could serve as food for thought:

      A user test on wp.com showed that a lot of people chose themes based on content images in the screenshot. Which obviously led to disappointment when they were not there after activation.

      We started an effort, led by Lance, to update screenshots for “blog” themes, to not show any images that do not come with the theme. The goal is the same as this guideline’s goal: to not misrepresent what the theme will look like on activation.

      • kwight 1:17 am on January 18, 2013 Permalink | Log in to Reply

        Just curious what you mean by blog themes… as opposed to portfolio themes or similar, which can show images in their screenshots?

        If a theme supports featured images, having a screenshot that demonstrates that makes sense to me, rather than ensuring no content images are visible. It sounds like wanting users to be pleasantly surprised, rather than possibly disappointed, neither of which is ideal.

        Of course, it’s another situation that can be resolved once we have multiple screenshots per theme.

    • Justin Tadlock 5:04 am on January 21, 2013 Permalink | Log in to Reply

      The major point here is that the screenshot should not misrepresent the theme.

      I saw a reviewer knock a screenshot the other day because a menu or widget wasn’t turned on by default but was in the screenshot. These are things that a user will configure anyway with just about every theme.

      We just need to use a little common sense. This type of rigidness is what turned me off of the theme review team way back before I joined. Sure, we need standards, but when it comes to a theme’s screenshot, we don’t have to nit-pick every detail.

  • Chip Bennett 6:19 pm on January 7, 2013 Permalink | Log in to leave a Comment
    Tags: 3.6, Guidelines,   

    Coming in WordPress 3.6: Post Formats UI Improvements/Changes 

    See the make/core post here:

    http://make.wordpress.org/core/2013/01/07/wordpress-3-6-the-post-formats-ui-feature

    If anyone has any particular input into the what/how of improvements/changes to or standardization of Post Formats, please contribute there.

    We’ll do our best to stay on top of any proposed changes, so that we can give as much advance notice as possible to Theme developers, for anything that would impact Theme development or the Theme Review guidelines.

     

  • Chip Bennett 3:21 pm on December 14, 2012 Permalink | Log in to leave a Comment
    Tags: , Guidelines   

    query_posts() 

    While the clock has started ticking on the 3.5 release grace period for Guidelines updates, I would like to discuss formalizing one other _doing_it_wrong() issue that has been implicitly enforced for some time now: use of query_posts().

    Would anyone be opposed if we formally added query_posts() to Theme Check as a required stopper?

    To understand why query_posts() is always inherently _doing_it_wrong(), see @nacin‘s WordCamp presentation You Don’t Know Query, and this great WordPress StackExchange answer by @rarst.

    In short, if you are creating secondary queries, you should use WP_Query(), and if you’re modifying the main query, you should filter pre_get_posts.

    Thoughts?

     

    • Andrew Nacin 3:23 pm on December 14, 2012 Permalink | Log in to Reply

      I’d say recommended, until WordPress itself declares that query_posts() is`_doing_it_wrong().

      • Chip Bennett 3:25 pm on December 14, 2012 Permalink | Log in to Reply

        What would the benefit be of making it only *recommended*?

        Whether core flags the function itself as _doing_it_wrong() or not, it is always a bad practice, leads to unexpected results, and causes problems for the end user.

        • scribu 3:37 pm on December 14, 2012 Permalink | Log in to Reply

          Using the ‘pre_get_posts’ filter incorrectly can also lead to unexpected results and cause problems for the end user.

          It’s actually easier to use query_posts() correctly than to add all the appropriate checks to a callback hooked into ‘pre_get_posts’.

          • Daniel 3:40 pm on December 14, 2012 Permalink | Log in to Reply

            This is a good point. The ‘request’ filter was built for the specific reason to alter the main query and the main query only; only problem is its implementation is still not complete. I propose we don’t push this as required until we are sure we have a bulletproof workaround.

          • Chip Bennett 3:52 pm on December 14, 2012 Permalink | Log in to Reply

            True. But then, so can calling wp_nav_menu() incorrectly (e.g. by passing ‘menu’ instead of ‘template_location’). But we don’t allow Themes to use wp_list_pages()/wp_page_menu()/wp_list_categories() in place of wp_nav_menu(). Instead, we educate about proper usage of wp_nav_menu().

          • Konstantin Kovshenin 7:04 pm on December 14, 2012 Permalink | Log in to Reply

            Using the ‘pre_get_posts’ filter incorrectly can also lead to unexpected results and cause problems for the end user.

            That’s so true!

    • Konstantin Kovshenin 3:25 pm on December 14, 2012 Permalink | Log in to Reply

      I’d go for recommended too, but huge +1 on the initiative!

      • Chip Bennett 3:28 pm on December 14, 2012 Permalink | Log in to Reply

        My problem with *recommended* is that, when query_posts() is used, it is almost *never* used *properly*. So, in order to pass the review process, the reviewer will have to help the developer rehabilitate the use of query_posts(), instead of simply requiring the cleaner, proper implementation via WP_Query or pre_get_posts.

        Instead of teaching developers how to rehabilitate query_posts() usage, wouldn’t it be a far better use of our time to teach *proper* usage of best-practice methods?

        • Maor Chasen 8:29 am on December 21, 2012 Permalink | Log in to Reply

          I agree. I think that for some developers it will take a while to realize that query_posts() is not the correct method, and if we don’t make it required now, then by the time it is being marked as _doing_it_wrong() in core — developers will still use it. IMHO, there are things that you don’t postpone, and this one is among them. Because if we don’t, it’s not just that we’re not teaching developers how they *should* do it, but end users might suffer from endless bugs that will be directly caused by the misuse of query_posts().

    • Daniel 3:29 pm on December 14, 2012 Permalink | Log in to Reply

      The only problem I see is with pagination. Functions like next_posts_link() and previous_posts_link() work directly with the $wp_query and $paged globals so to get them to work one needs to alter the main query.

      • Konstantin Kovshenin 3:31 pm on December 14, 2012 Permalink | Log in to Reply

        That’s easy, just delete 404.php and pagination will work again, haha! How about wasted resources? :)

        • Daniel 3:32 pm on December 14, 2012 Permalink | Log in to Reply

          Is this a joke? 404 HTTP status is triggered in the page headers before templates are loaded.

          • Konstantin Kovshenin 3:35 pm on December 14, 2012 Permalink | Log in to Reply

            Of course it’s a joke, while I’ve seen a few people do it. You should never, never, never use query_posts. Period.

            • scribu 3:40 pm on December 14, 2012 Permalink

              You should never, never, never use query_posts(), unless there’s no better way to do it. That’s why it’s not deprecated in Core, yet.

            • Chip Bennett 4:01 pm on December 14, 2012 Permalink

              @scribu: examples of cases where there is no better way to do something than via query_posts()?

              That’s the paradigm shift I’m struggling with, here.

            • scribu 4:10 pm on December 14, 2012 Permalink

              The exact use-case that query_posts() was designed for: using a custom page template as an archive of posts:

              Just call query_posts() at the very beginning and pretend it’s an arhive. query_posts() takes care of completely replacing the main query and the effect is limited to that custom page template.

              You don’t have to do any workarounds for conditional flags or for pagination.

            • scribu 4:11 pm on December 14, 2012 Permalink

            • Chip Bennett 4:12 pm on December 14, 2012 Permalink

              You don’t have to do any workarounds for conditional flags or for pagination.

              So, pagination works “out of the box” on a custom page template where the default query is stomped by query_posts()?

            • Chip Bennett 4:18 pm on December 14, 2012 Permalink

              Also, I note that even you say that using WP_Query() is the better method for creating secondary loops:

              The new way (better, because it has less side-effects)…

              :)

            • nofearinc 6:05 pm on December 14, 2012 Permalink

              what’s the preferred way to handle pagination though? It’s indeed using the $wp_query global inside of the pagination definition and passing arguments from the outside is a bit odd. There is no valid way to overload the query variable used for the pagination functions.

      • Chip Bennett 3:34 pm on December 14, 2012 Permalink | Log in to Reply

        Isn’t that an argument in *favor* of using pre_get_posts instead of query_posts()? If you alter the main loop query *before* the query is set up, pagination just works.

        • Daniel 3:37 pm on December 14, 2012 Permalink | Log in to Reply

          That works for most cases with one exception I’m aware of: custom page templates. If you want to display a custom loop in a page template you need the main loop unaltered before the template is loaded to make sure the correct one is loaded. Otherwise the function is_page_template( ‘some-template.php ) may not return the correct value.

          • Chip Bennett 3:49 pm on December 14, 2012 Permalink | Log in to Reply

            If you want to display a custom loop in a custom page template, then instantiate a custom query, via new WP_Query().

            Pagination still requires a bit of a work-around, but I would contend that work-around is far less intrusive than what is required to ensure that the main loop query is replaced cleanly.

            • Daniel 4:14 pm on December 14, 2012 Permalink

              The paginate_links() function could be used which accepts custom pagination arguments, and simple prev/next links could be generated by setting all numbered pagination values to 0; though I see that more as a hack rather than a workaround and I wouldn’t like to see it as recommended.

            • Daniel 4:17 pm on December 14, 2012 Permalink

              What I would like to see is functions like next_posts_link() and previous_posts_link() accept query objects as optional parameters. I believe that would be a huge enhancement in core.

    • Edward Caissie 3:36 pm on December 14, 2012 Permalink | Log in to Reply

      I’m not seeing ‘query_posts’ currently mentioned in the guidelines and if that is the case and although use-cases would be rare and still not likely best practice I would say we proceed in our standard method of first RECOMMENDED NOT to use then proceed to REQUIRED NOT to use.

      • Chip Bennett 3:47 pm on December 14, 2012 Permalink | Log in to Reply

        No, query_posts() is not explicitly listed in the Guidelines. But then again, neither are dozens of other functions that we exclude, based on this principle (and similar principles expressed in the guidelines):

        Whether implementing required, recommended, or optional features, Themes are required to support proper WordPress core implementation of all included features.

        My contention is:

        1. Creating secondary loop queries is properly implemented via new WP_Query()
        2. Modifying the main loop query is properly implemented via filtering pre_get_posts.

        • scribu 4:15 pm on December 14, 2012 Permalink | Log in to Reply

          I agree with 1.

          I only partially agree with 2. You can do it, but it’s very easy to mess up, when using pre_get_posts, even if you use is_main_query().

          • Chip Bennett 4:20 pm on December 14, 2012 Permalink | Log in to Reply

            I only partially agree with 2. You can do it, but it’s very easy to mess up, when using pre_get_posts, even if you use is_main_query()

            But what are the vast majority of use cases for modifying the main query in publicly distributed Themes? Changing posts_per_page? Excluding a special/featured category? Something similar? Those are all straight-forward and easy in a pre_get_posts callback.

            • Sergey Biryukov 6:46 am on December 15, 2012 Permalink

              FWIW, $wp_query->is_main_query() returns true in the admin as well.

              So, if a theme exludes a category or alters posts_per_page using a pre_get_posts callback, it should also include an is_admin() check to prevent unintended side effects in the admin.

    • Frumph 5:00 pm on December 14, 2012 Permalink | Log in to Reply

      query_posts is a valid and acceptable method of adding additional loops on your home page; unless something has changed recently that I am not reading here

    • Justin Tadlock 5:35 pm on December 14, 2012 Permalink | Log in to Reply

      query_posts() should only be used in custom page templates designed to be an archive-type page of posts. That’s the only use case I can think of at the moment.

      Most themes shouldn’t have a need to touch the main query anyway. There are some valid reasons for themes to do so, but this is generally plugin territory.

      • Konstantin Kovshenin 5:36 pm on December 14, 2012 Permalink | Log in to Reply

        new WP_Query() + the_post() + wp_reset_postdata() is a good alternative.

        • Ryan Duff 5:58 pm on December 14, 2012 Permalink | Log in to Reply

          Except in cases you intentionally want to stop on $post. It’s an extremely fringe case though.

          • Ryan Duff 6:18 pm on December 14, 2012 Permalink | Log in to Reply

            I’d like to expound on this after I read up to the top… and say that this fringe case is something I’d never see happening in a public theme.

          • Andrew Nacin 8:16 pm on December 17, 2012 Permalink | Log in to Reply

            No, it specifically works for that case. the_post() stomps $post. wp_reset_postdata() restors it.

        • Drew Jaynes (DrewAPicture) 6:00 pm on December 14, 2012 Permalink | Log in to Reply

          +Like

        • nofearinc 6:01 pm on December 14, 2012 Permalink | Log in to Reply

          +1 for that

        • Frumph 6:33 pm on December 14, 2012 Permalink | Log in to Reply

          My understanding is that new WP_Query() adds to the stack overhead while query_posts uses the internal post cache.. makes a big difference, unless i’m mistaken

          • Konstantin Kovshenin 6:36 pm on December 14, 2012 Permalink | Log in to Reply

            Both do the exact same thing, but in addition to that, query_posts() also breaks things and causes kittens to die.

            • Frumph 6:39 pm on December 14, 2012 Permalink

              Hrm. I don’t like kittens dying. ..

            • Konstantin Kovshenin 6:42 pm on December 14, 2012 Permalink

              Just to clarify, there is no overhead because query_posts() is just a wrapper function that calls new WP_Query() so there really is no difference between the two, except the kittens of course.

              When you want to alter the main query, both new WP_Query() and query_posts() are overhead because they both fire secondary queries, when you wanted to alter the main query, in which case you should have used the ‘pre_get_posts’ action or the ‘request’ filter.

            • Frumph 6:47 pm on December 14, 2012 Permalink

              ..so the point in not using query_posts is what? if they’re both the same? .. I mean yeah if it’s the front page and the loop has already fired of course you should use pre_get_posts, but if you have the parser ‘reject’ use of query_posts if it was used as it should as secondary loops, then well .. what then?

            • Konstantin Kovshenin 6:58 pm on December 14, 2012 Permalink

              Frumph: The point is that while query_posts() is just a wrapper for new WP_Query() it also does that in a way that breaks things, which is why avoiding query_posts() and using WP_Query() is safer.

              However, correct me if I’m wrong, but the reason this was brought up is because query_posts() is used in many themes to replace the main loop, so we should educate developers towards pre_get_posts, not secondary loops.

            • Chip Bennett 7:04 pm on December 14, 2012 Permalink

              …use of query_posts if it was used as it should as secondary loops…

              Actually, secondary loops are exactly the wrong reason for using query_posts(). Per the Codex:

              query_posts() is meant for altering the main loop….
              …
              To create secondary listings…try making a new instance of WP_Query or use get_posts().

            • Konstantin Kovshenin 7:08 pm on December 14, 2012 Permalink

              Actually, secondary loops are exactly the wrong reason for using query_posts()

              query_posts() does not alter the main loop. In fact, get_posts(), new WP_Query() and query_posts() do the exact some thing in slightly different ways, so IMO saying query_posts() should be used to alter the main query is completely wrong, because query_posts() is fired after the main query has already been made, unless it’s called in functions.php :)

            • Chip Bennett 7:12 pm on December 14, 2012 Permalink

              query_posts() does not alter the main loop.

              Yes, it does: alter the main Loop – by replacing the query used to generate the data for that loop. :)

              I think that’s probably a semantic difference. The Codex says “alter” (the main Loop); in reality, the correct term is “replace” (the main Loop query. The end result, however, is the same: what gets output in the main Loop has changed.

            • Konstantin Kovshenin 7:14 pm on December 14, 2012 Permalink

              I think that’s probably a semantic difference.

              Exactly, which is why it’s so confusing and should be removed :)

            • Frumph 8:52 pm on December 14, 2012 Permalink

              That should probably be notated over to the codex editors yeah? .. hey whatever happened to our ‘best practices’ page someone was supposed to be working on?

          • Chip Bennett 6:38 pm on December 14, 2012 Permalink | Log in to Reply

            My understanding is that new WP_Query() adds to the stack overhead while query_posts uses the internal post cache.

            Just pass:

            'update_post_meta_cache' => false,
            'update_post_term_cache' => false,

            …as part of your argument array for new WP_Query( $args ) to eliminate that overhead.

            • Andrew Nacin 8:19 pm on December 17, 2012 Permalink

              No, definitely not. All query instances consult the same cache before deciding if additional calls to populate the cache is necessary.

              The flags `update_post_meta_cache`, `update_post_term_cache`, and `cache_results` should be immediate red flags in a theme. Chances are, they are doing it wrong, and trying to avoid one query but generating a bunch in the process (because some operation they are doing does consult meta or term data, even if they don’t realize it).

      • Hirak Santra 6:59 am on December 24, 2012 Permalink | Log in to Reply

        query_posts() can be used not only for custom posts. It can also bring data of a respective page by page_id or page_name.

      • Hirak Santra 7:01 am on December 24, 2012 Permalink | Log in to Reply

        query_posts() can not only bring data of posts page but also it can bring data from a page by page_id or page_name.

    • Chris Olbekson 6:47 pm on December 14, 2012 Permalink | Log in to Reply

      I would agree with the others that `query_posts()` should only be used in a page template that wants to work as an archive. It shouldn’t be used in an archive, header, widget, sidebar etc..

    • Andrew Nacin 8:43 pm on December 17, 2012 Permalink | Log in to Reply

      I went out on the WordCamp “circuit” and educated developers on query_posts() in three different cities. This was a carefully calculated initiative designed to boost developer education and awareness. I specifically gave the talk at three veteran WordCamp cities: Portland on the west coast, New York on the east coast, and in Europe (Netherlands). And, the talks have gotten quite a bit of play online after. The impact has been large.

      And yet, core still does not deprecate query_posts(), even though I added is_main_query() to core while on stage at WordCamp Portland. Why, despite recommending against its use, do we not argue for its alternatives?

      My goal was to focus on education and awareness beyond query_posts(). There are a lot of things WordPress developers do out of force of habit, without understanding what actually goes on under the hood. In the case of query_posts(), this was a particularly bad habit caused by lack of understanding.

      But, pre_get_posts may be the correct solution, but it isn’t a good one. It can break the admin. It can break secondary queries. And, it is not easy for developers to use. For a number of situations, query_posts() is sufficient, despite, in many of those situations, having edge cases. We led with a carrot, but if it tastes awful, is it really fair to continue with the stick? I my book, edge cases where it may not be perfect trumps side effects that break other things.

      I like to think I am very pragmatic when it comes to core’s development. I subscribe to “why walk when you can run” almost as much as the next 20-something, but learning to recognize when to walk instead of running is a major key to my own evolution as a developer of a large open source project. It is often important to let the core development process work at a more deliberate speed.

      So, I am often bearish on the adoption and evolution of newer APIs, and bullish on the deprecation of old ones. I could pushed the deprecation of query_posts() at any time since I first gave the talk in September 2011. That timeline includes three major releases, including one I led. Yet, despite kicking off this education initiative, I haven’t. That, I think, should speak volumes. That is why the theme reviewers should follow core’s lead on this.

    • Toru 5:13 am on March 25, 2013 Permalink | Log in to Reply

      I (or Japanese community while translating…) came a cross that on Codex’s http://codex.wordpress.org/Function_Reference/wp_reset_query
      word “deprecated” is used.

      Deprecated – only use query_posts if absolutely necessary (see query_posts: Caveats)

      I have not been able to follow much of the progress on this topic recently, but I believe Nacin’s above post was the final say for now.
      Can I check that Am I correct? In which case I feel this is very misleading line in Codex.

      Codex’s query_posts entry is however, I think very clear and in agreement with what has been discussed in this thread.

      Thanks.

  • Chip Bennett 6:40 pm on November 26, 2012 Permalink | Log in to leave a Comment
    Tags: Guidelines   

    WordPress 3.5 Guidelines Revisions 

    It is that time of year again: with the upcoming release of WordPress 3.5, the Theme Review Team conducts its periodic review of the Theme Review Guidelines, and proposes any changes, either as necessitated by the new WordPress version, or otherwise as-needed.

    The 3.5 release has little impact on Themes, and as such will be mostly invisible to Theme developers. One minor change will be support for HiDPI (i.e. “Retina”) screenshots. If there are any other 3.5-related changes that we need to account for, please post in the comments.

    Here is the starting point for the discussion regarding changes to the Guidelines:

    • Change Theme Screenshot (screenshot.png) maximum dimensions from 300x225px to 600x450px. (Fixed per comment below)
    • New guideline under presentation-vs-functionality: Themes must not bundle custom post-content shortcodes
    • Change guideline: reduce criticality for Content Sidebar feature from required to recommended. (Themes would still be required to implement core Settings API if Theme incorporates content sidebar feature.)
    • Change criticality of add_theme_support( ‘automatic-feed-links’ ) from required to recommended. (Modified per comments below)

    Please discuss in the comments, and recommend any additions or changes to these proposed Guidelines revisions.

     

    • Andrew Nacin 6:45 pm on November 26, 2012 Permalink | Log in to Reply

      Could you explain the reasoning behind automatic-feed-links?

      • Chip Bennett 6:49 pm on November 26, 2012 Permalink | Log in to Reply

        Sure. I have no particular preference one way or the other. That one is there for discussion, primarily.

        It was suggested to me – and I would tend to agree – that inclusion of RSS feed links is a) not exactly *presentational*, and b) easily enabled via Plugin. So, I’m throwing it out there for the Theme developer community to discuss and to decide. That way, we’ve documented our reasoning for keeping it or removing it.

        • Andrew Nacin 7:15 pm on November 26, 2012 Permalink | Log in to Reply

          I need to do some research to verify my recollection here, but as far as I know, the only reason why it is a theme-support thing is because prior to that line of code, themes would add them into header.php directly. This would cause a double-up. If it weren’t for that, we never would have had the opt-in, and we’d just always do it. I’m game for revisiting this in the future, but I think it makes sense for themes to continue to add the line.

          • Chip Bennett 7:18 pm on November 26, 2012 Permalink | Log in to Reply

            I would consider header RSS feed links to be analogous to the WP version generator and other similar meta data. I’m sure you’re right about the reasoning behind the add_theme_support() implementation. Perhaps a criticality bump from *required* to *recommended* (or *optional*), to help make the point that this functionality lies very close to the presentation-vs-functionality line?

            • Samuel Wood (Otto) 7:53 pm on November 26, 2012 Permalink

              I would say that you could put this in the category of if you use them, then you must use them correctly by using the theme support bit instead of putting them in the header.php manually yourself. But we would definitely say that using automatic-feed-links is recommended.

              I would also say that it is definitely not plugin territory. If anything, core should be doing it automatically, all the time, period. However, because themes traditionally used hard-coded feed links, there was no way to do that and be backwards compatible.

            • Samuel Wood (Otto) 7:55 pm on November 26, 2012 Permalink

              In other words, ban hardcoded RSS links in theme headers, and require use of automatic-feed-links for themes that add feed links (which, IMO, should be all of them).

            • Chip Bennett 8:17 pm on November 26, 2012 Permalink

              I’m with you, Otto. I don’t think anyone is advocating *prohibiting* automatic feed links; but rather more like what you said: adding feed links is *recommended*, *must not* hard-code feed links, and if adding feed links, *required* to use add_theme_support().

            • Vicky Arulsingam 1:03 am on November 27, 2012 Permalink

              I’d prefer it be bumped down to recommended.

              If a user has a plugin for this feature and feed links are added in the theme, would this result in the links being displayed twice?
              If this is the case then a recommendation/requirement to perform a ‘current_theme_supports’ check would be helpful

            • Andrew Nacin 2:49 am on November 27, 2012 Permalink

              They should remain required. Think about it this way: The theme *must not* hard-code feed links, and the theme *must* tell core that they are not hard-coding feed links. That’s really the only meaning of automatic-feed-links.

            • Samuel Wood (Otto) 2:49 am on November 27, 2012 Permalink

              Vicky: If both the theme and the plugin are using automatic-feed-links, then no, they would not be added twice.

            • toscho 11:19 am on November 27, 2012 Permalink

              Core should ask for opt-out and apply the feed links automatically. Legacy themes should not force theme authors to use non-presentational functions in their new themes.

            • Edward Caissie 3:19 pm on November 27, 2012 Permalink

              Quoting Otto:

              I would say that you could put this in the category of if you use them, then you must use them correctly by using the theme support bit instead of putting them in the header.php manually yourself. But we would definitely say that using automatic-feed-links is recommended.

              I agree this is the best method going forward on the implementation of automatic-feed-links

      • mrwweb 7:05 pm on November 26, 2012 Permalink | Log in to Reply

        I moved automatic-feed-links to my functionality plugin a year ago for this reason. If a site needs them, they shouldn’t disappear and reappear depending on the theme.

    • Chip Bennett 7:13 pm on November 26, 2012 Permalink | Log in to Reply

      Other things I’d like to discuss:

      • Timing for making do_settings_sections() required (as opposed merely to recommended) as part of Settings API implementation
      • Removing public-facing credit links, or making them follow Plugin rules: user-configurable, and disabled by default
      • Reformatting the Guidelines as a checklist (either replacing the existing Guidelines entirely, or creating a companion tool to aid reviews)

      • Ian Stewart 7:54 pm on November 26, 2012 Permalink | Log in to Reply

        Removing public-facing credit links, or making them follow Plugin rules: user-configurable, and disabled by default

        Can you elaborate on some of the reasoning behind this?

        • Chip Bennett 8:07 pm on November 26, 2012 Permalink | Log in to Reply

          I’m curious what the Theme developer community thinks about the idea. I think that there is an argument to be made that the negatives far outweigh the positives with respect to displayed-by-default footer credit links. It attracts an inordinate share of of Bad Things, and leads to an inordinately high number of headaches for reviewers and developers alike, under the false premise that such footer credit links help developers’ SEO.

          Obviously, there *is* real benefit to be gained, through actual humans seeing and following those links, but I have long-questioned whether that benefit outweighs the volume of crud Themes that get submitted solely in an attempt to spread footer credit links.

          I’m really just interested in finding out if the Theme developer community would be even partially amenable to the idea, or if it’s something that remains completely off the table for discussion.

          • Emil Uzelac 8:24 pm on November 26, 2012 Permalink | Log in to Reply

            As developer and TRT admin I strongly believe that this is not necessary. Credit Links are the “connection” between the site and the author and many of us here are making a living out of that.

            • Chip Bennett 8:41 pm on November 26, 2012 Permalink

              Agreed, and I don’t want to give the idea of wanting to throw the proverbial baby out with the bath water.

          • CyberChimps 1:16 am on November 27, 2012 Permalink | Log in to Reply

            I think it is a good thing that we are not letting themes into the repo that were submitted on the premise of generating SEO. If we remove the credit links we will be punishing honest authors, and lose the ability to spot the spammers more quickly. It is a lose-lose situation.

            The rules do not matter to spammers, there will always be spam submissions no matter what the rules are we shouldn’t punish honest authors from having a connection to their work.

          • Edward Caissie 3:30 pm on November 27, 2012 Permalink | Log in to Reply

            I would say we leave the credit links in, as is.

            My concerns are not so much in the continued efforts of spammers trying to “game the system” but more so for the developers and designers who may lose interest in updating and/or submitting new themes to the repository without any credit for their works.

            An option to “turn off” credits may be feasible, or even something to be suggested, but I would never get to the point of it being recommended.

            If “Code is Poetry”, how can you expect the poet to not openly sign their work?

        • Ian Stewart 8:18 pm on November 26, 2012 Permalink | Log in to Reply

          I think it’s an interesting idea. My two cents: I think an option is too much cruft for a problem that doesn’t really affect the user and that not allowing public facing credits will probably discourage submissions from designers — especially ones that aren’t quite aware that a theme developer community exists. I don’t think designers do it for the SEOs. I just think it’s natural for them to want to put a credit line on their work in the same way that an artist naturally tends to sign their work.

          • Ian Stewart 8:21 pm on November 26, 2012 Permalink | Log in to Reply

            I don’t think designers do it for the SEOs

            Though obviously some spammers with not-the-best themes are. :)

          • Chip Bennett 8:22 pm on November 26, 2012 Permalink | Log in to Reply

            Is there a way to provide the benefit (which is certainly deserved), without attracting the bad?

            • Ian Stewart 8:34 pm on November 26, 2012 Permalink

              Probably not.

            • Chip Bennett 8:36 pm on November 26, 2012 Permalink

              Is it something worth further consideration, to try to come up with a better alternative, or is it just something that we just have to continue to deal with, because it can’t be fixed?

            • Ian Stewart 8:40 pm on November 26, 2012 Permalink

              There may be some way to make it easier to spot/flag these themes beforehand (automatically diffing against the default themes and coming up with a percentage that flags a theme? Flagging first time themers that have some sort of commonality to theme?). I can’t think of any alternatives to it beyond getting better at spotting the bad guys and just dealing with the fact that there are bad guys.

            • Ian Stewart 8:41 pm on November 26, 2012 Permalink

              … sort of commonality to theme?

              s/theme/them

              For some reason that’s a common spelling mistake with me.

            • Chip Bennett 8:49 pm on November 26, 2012 Permalink

              I often “audit” the Priority #4 queue, for just this sort of review. I look for spammy/inappropriate credit links and landing pages, and obvious knock-offs of known Themes.

              Honestly, child Theme support helps greatly in this regard, since we can spot Twenty Ten and Twenty Eleven derivatives, and require them to be resubmitted as proper child Themes. That’s helped cut down on a good bit of the knock-off Themes. But a lot of the pattern recognition you describe is purely manual, and requires familiarity with Themes prone to being forked.

            • Emil Uzelac 9:29 pm on November 26, 2012 Permalink

              We can reduce the numbers from 4 priorities to only 2. #1 Previously Approved and #2 All others, this way the process would be much faster and we can “scan” for SPAM easier. Does that make sense?

          • Philip Arthur Moore 12:13 am on November 27, 2012 Permalink | Log in to Reply

            Big +1.

        • Daniel 8:40 am on November 27, 2012 Permalink | Log in to Reply

          I have a bad feeling an unintended consequence of this would be many developers not updating theor themes anymore to circumvent this guideline.

        • Konstantin Kovshenin 11:19 am on November 27, 2012 Permalink | Log in to Reply

          Will adding “nofollow” to such links help avoid the “Bad Things”? If it does we can make it a recommendation or even a requirement.

      • Ian Stewart 7:54 pm on November 26, 2012 Permalink | Log in to Reply

        Reformatting the Guidelines as a checklist (either replacing the existing Guidelines entirely, or creating a companion tool to aid reviews)

        I think this is a great idea.

      • kwight 8:08 pm on November 26, 2012 Permalink | Log in to Reply

        I’ve volunteered to help the Documentation team with the Theme Review handbook: http://make.wordpress.org/updates/2012/11/20/docs-team-intro/#comment-22

        I’m a little unclear as to how this relates to the current posted Guidelines; I’m hoping the handbook eventually /becomes/ the posted guidelines. Is this what you’re referring to, or are you suggesting an interim step?

        • Chip Bennett 8:10 pm on November 26, 2012 Permalink | Log in to Reply

          As I understand it, the Theme Review Handbook is more intended to be a “how to get involved with the Theme Review Team” kind of thing?

          • kwight 8:24 pm on November 26, 2012 Permalink | Log in to Reply

            Ah, perhaps I’ve misunderstood; so the Handbook is more of an onboarding tool, while the Guidelines exist separately in the Codex?.. Either way, I’m in, the current format could certainly be improved.

            I think it would be more effective for each guideline to have a What Why How approach: “What” is the guideline, “Why” is it required/recommended, and “How” is it implemented (actual code example). I think it would reduce a lot of confusion both for reviewers and submitters.

            • Chip Bennett 8:27 pm on November 26, 2012 Permalink

              I like that approach; the problem is that the Codex doesn’t necessarily present the best means to implement such an approach. We would have to have separate entries for the Guidelines themselves (essentially what we have now), and for the What/Why/How information; otherwise, it would be even *more* difficult for new Reviewers to read/parse the Guidelines.

              But, I am absolutely in favor of providing more code examples, wherever we can.

            • kwight 8:51 pm on November 26, 2012 Permalink

              True; in my fancy designer head, each of the What Why How would be a tab for each guideline, but AFAIK, that’s not possible with the Codex. If only the Codex was WordPress :|

              The best thing I guess, could be having a “more detail” link for each guideline that goes to a more lengthy What Why How page, with code examples.

    • Ian Stewart 7:41 pm on November 26, 2012 Permalink | Log in to Reply

      Change guideline: reduce criticality for Content Sidebar feature from required to recommended. (Themes would still be required to implement core Settings API if Theme incorporates content sidebar feature.)

      Could explain this one a bit more? I’m not quite clear what it refers to.

      • Chip Bennett 7:48 pm on November 26, 2012 Permalink | Log in to Reply

        In other words: Themes don’t *have* to include dynamic-content sidebars (whether as a traditional sidebar, or a footer sidebar, etc.) .

        This came out of a discussion about Appearance -> Widgets no longer displaying if Themes don’t call register_sidebar(). Dynamic Sidebars would thus be treated as analogous with Custom Backgrounds or Custom Header Images.

      • Ian Stewart 7:49 pm on November 26, 2012 Permalink | Log in to Reply

        Awesome. Thanks.

      • kwight 8:11 pm on November 26, 2012 Permalink | Log in to Reply

        +1. It would be great (particularly for stripped-down/minimalist themes) to not be forced in to implementing widget areas.

      • Danielx64 3:57 am on January 24, 2013 Permalink | Log in to Reply

        -1 for the sidebar removal, like I said on the mailing list, I wouldn’t be happy to download a theme only to find out that it doesn’t support widgets.

    • kwight 7:57 pm on November 26, 2012 Permalink | Log in to Reply

      Ack! I already changed the guidelines re: screenshots, after noticing the new hiDPI screenshot for Twenty Twelve works in 3.4.2. Since it’s stating a maximum, would be a problem keeping it like that unless something comes up?.. Let me know if I’ve really jumped the gun, I’ll set it back.

    • shawn 8:09 pm on November 26, 2012 Permalink | Log in to Reply

      New guideline under presentation-vs-functionality – anyplace I can get more info on these guidelines

    • shawn 8:11 pm on November 26, 2012 Permalink | Log in to Reply

      New guideline under presentation-vs-functionality: Themes must not bundle custom post-content shortcodes

      Any place I can get more info on this???

      • Chip Bennett 8:16 pm on November 26, 2012 Permalink | Log in to Reply

        What sort of information are you looking for? This is probably the best place to get it. :)

        • shawn 8:38 pm on November 26, 2012 Permalink | Log in to Reply

          Are we talking just shortcode(s) or any custom post content code….

          A clearer definition of presentation vs functionality guidelines standard for either themes or plugins in WP are not exactly up to common PHP standards. I would love to know what exactly the guidelines are.

          • Chip Bennett 8:45 pm on November 26, 2012 Permalink | Log in to Reply

            Are we talking just shortcode(s) or any custom post content code

            What other post-content code do you have in mind? As a general rule, if you’re manipulating post content in any way other than presentationally, that manipulation probably belongs in a Plugin.

            A clearer definition of presentation vs functionality

            In some regards, that is the million-dollar question. But for the purposes of Themes, 99% of the time it isn’t difficult to determine whether something is functional or presentational.

            Do you have any specific examples where you’re unclear about whether something is one or the other?

            • Sayontan Sinha 9:13 pm on November 26, 2012 Permalink

              Themes that are framework-based (like Hybrid) have a lot of bundled shortcodes. Are those acceptable? What exactly differentiates a “custom post-content” shortcode from a regular shortcode?

              Along the lines of the Hybrid question, is it acceptable if the author provides a shortcodes plugin which is simultaneously offered with the theme (I do so, mainly to help users transition out of the theme without impact).

            • shawn 12:36 am on November 27, 2012 Permalink

              Most of my custom post-content runs from generic class located in a theme plugin toolkit, themes decided what is run, when, on a case by case basis, this allow me to customize post types based on the needs the theme.

              The problem with this method as far as I am aware is that themes with dependencies like these cannot function in the theme repository, now that it is policy, has this changed?

              Do you have any specific examples where you’re unclear about whether something is one or the other?

              I am unclear about everything here, since most theme developers already separate presentation from functionality what I see happening is the creation of another theme dependency and I not sure I like it.

            • shawn 2:23 am on November 27, 2012 Permalink

              Since the purpose of Themes is to define the presentation of user content, Themes must not be used to define the generation of user content, or to define Theme-independent site options or functionality.

              Sorry if I sound confused but this new guideline completely caught me off guard, theme dev/designers agreed to this???

            • Chip Bennett 2:28 am on November 27, 2012 Permalink

              The presentation-vs-functionality criterion is not a new guideline. It has been an operating principle since the beginning of the Theme Review Team’s efforts.

              What part of it do you disagree with?

            • Chip Bennett 2:30 am on November 27, 2012 Permalink

              Themes that are framework-based (like Hybrid) have a lot of bundled shortcodes. Are those acceptable? What exactly differentiates a “custom post-content” shortcode from a regular shortcode?

              As far as I’m aware, Hybrid does not bundle post-content shortcodes, but rather uses a custom shortcode for user configuration of footer text, etc. Such “shortcodes” are perfectly acceptable.

              The differentiation is post-content. If the shortcode is used in the post content – i.e. if it is added by the user to the post content editor, such as or [ref] or [two-columns] – then it belongs in a Plugin rather than in the Theme.

            • Sayontan Sinha 6:09 am on November 27, 2012 Permalink

              As far as I’m aware, Hybrid does not bundle post-content shortcodes, but rather uses a custom shortcode for user configuration of footer text, etc. Such “shortcodes” are perfectly acceptable.

              The shortcodes that come with Hybrid are entry-title, entry-author, entry-terms and several others, which to me seem very much like post-content shortcodes. These are by design to be run where the global $post is available. Where else would you invoke these if not in the post content? Hybrid has a host of other shortcodes that can be used in comments.

              So if this is made a requirement, then all themes that have such existing shortcodes have to pull them from the theme, risking sites breaking as as a result.

              I see no reason for any Theme ever to bundle post-content shortcodes.

              Except that, as I mentioned, several themes already include them, and they are in very heavy use. Trying to cull the shortcodes from such themes will only result in frustration for the users of the themes. I thought the aim of the theme review team is to make things easy for users, while disallowing what already exists only serves the opposite purpose.

              Of course, one way could be to disallow new shortcodes, but forcing theme authors to remove every existing post content shortcode is going to the extreme.

            • Chip Bennett 12:49 pm on November 27, 2012 Permalink

              The shortcodes that come with Hybrid are entry-title, entry-author, entry-terms and several others, which to me seem very much like post-content shortcodes.

              Those sound like template shortcodes to me. Key point: where does the user use those shortcodes: in the Visual/Text post editor, or elsewhere?

              These are by design to be run where the global $post is available. Where else would you invoke these if not in the post content?

              You are misunderstanding “post-content” shortcodes. A “post-content” shortcode is one that the user places in the post Visual/Text editor, that lives in the database in $post->post_content, and that is parsed by do_shortcode() upon display.

              Hybrid has a host of other shortcodes that can be used in comments.

              And Justin explicitly says that the Theme’s shortcodes are not intended to be used in the post content:: “These shortcodes are not meant to be used with the post content editor. Their purpose is to make it easier for users to filter hooks without having to know too much PHP code and to provide access to specific functionality in other (non-post content) shortcode-aware areas.“

            • shawn 2:49 pm on November 27, 2012 Permalink

              What part of it do you disagree with?

              Practically all of it, with so much discussion and advances in development and understanding of UI/UX, to state the the purpose of a theme is to define the presentation of user content is shallow at best. What even worse is the intent of the statement (Themes must not used to…).

              Simply change a couple words in the statements purpose to read

              Since the purpose of Themes are to define how users interact with a websites content…

              We are having a different discussion about the rule(s) of what themes should be used for, presentation now becomes functional as functionality, as it should be is now defined by the theme!

              New old or whatever this is just sooooo wrong Chip!

            • Chip Bennett 2:56 pm on November 27, 2012 Permalink

              with so much discussion and advances in development and understanding of UI/UX, to state the the purpose of a theme is to define the presentation of user content is shallow at best.

              No. That is precisely the purpose of a Theme. WordPress is designed such that the Theme is the content presentation abstraction layer.

              What even worse is the intent of the statement (Themes must not used to…).

              Simply change a couple words in the statements purpose to read

              Since the purpose of Themes are to define how users interact with a websites content…

              We are having a different discussion about the rule(s) of what themes should be used for, presentation now becomes functional as functionality, as it should be is now defined by the theme!

              Perhaps it would be helpful to shift your paradigm from functionality to content. Properly designed Themes will support most functionality out-of-the-box.

              Asked a different way: what functionality do you think Themes should be defining?

            • Sayontan Sinha 10:34 pm on November 27, 2012 Permalink

              And Justin explicitly says that…

              So in summary it is okay to state something like “Don’t use these in your post content” in the comments, but it is not okay to state, “If you decide to stop using this theme you can use this alternative plugin”.

              The point that I have been trying to get you to see is that there are active themes with huge user-bases that have shortcodes built in them. Some theme authors actively try to make the transition out of their themes painless by providing plugins for various modules. Forcing them to pull the shortcodes out will affect a LOT of users. If this isn’t sufficient for getting an exception on existing themes with existing shortcodes, I don’t know what is.

            • Frank Klein 11:34 pm on November 27, 2012 Permalink

              As a general rule, if you’re manipulating post content in any way other than presentationally, that manipulation probably belongs in a Plugin.

              Exactly. I can see why this new proposed guideline is controversial, since a lot of developers think of themes as “website packages”, that bundle a very custom design with the necessary functionality – custom post types, short codes, etc. But the sole fact that this is practiced by a lot of themes shouldn’t matter for putting a guideline in place for future themes.

              I wonder how many of the heavy shortcode users will get the shock of their life when they switch themes and suddenly all their posts are littered with shortcodes that no longer work.

              It seems to me that most users don’t care about what comes with a theme and what comes with a plugin, all they care about is that it is there. So as developers we should make their life easier by allowing them to switch themes freely without losing any functionality.

              It isn’t that difficult to point users to the right plugin that adds the desired functionality to a theme. If someone is smart enough to use shortcodes, then he will get this too.

              Besides I hope that this will lead developers towards leveraging more existing plugins.S o instead of whipping up your own crappy SEO optimization code in functions.php, why not simply point users toward a great plugin like WordPress SEO? How different can the functionality of your portofolio post type be from that offered by Justin’s plugin?

              Relying on production-hardened, specialized plugins instead of cooking up your own is the way of the future. Not only will this free up time for theme developers so that they can focus on building the best theme possible, but it also over time improve portability and establish de facto standards.

            • shawn 3:58 pm on November 28, 2012 Permalink

            • Justin Tadlock 5:35 pm on November 29, 2012 Permalink

              Just a note about Hybrid Core: Its shortcodes are intended for use in templates. This is stated in the file listing the shortcodes as well as in my theme documentation on my site. Most users aren’t even aware that there are shortcodes in the themes because they are not advertised as a feature. Basically, to even know the shortcodes exist, you must read the notice that they’re not to be used in the post content.

              With that said, I do have some ideas about de-registering the shortcodes specifically when the_content() is called just to outright avoid any potential issues. Not once have I had an issue with this from my users though.

      • kwight 8:31 pm on November 26, 2012 Permalink | Log in to Reply

        Content shortcodes should be plugin territory, so that users don’t lose the shortcode functionality when changing themes.

        • Rizqy Hidayat 3:30 am on November 27, 2012 Permalink | Log in to Reply

          So what ‘s the actual meaning of *content shortcodes*? is it shortcodes in the editor or somekind like what?

          • Chip Bennett 12:51 pm on November 27, 2012 Permalink | Log in to Reply

            Yes: a “post-content” shortcode is a code that the user places in the post content, via the post Visual/Text editor. Shortcodes used elsewhere in the template are fine, because they don’t affect user content upon switching Themes; they’re merely Theme customizations.

      • Sami Keijonen 6:53 am on November 27, 2012 Permalink | Log in to Reply

        What comes to Hybrid Core shortcodes, they are only used in template files. Never in post editor. There is a big difference for me at least.

        • Sayontan Sinha 6:06 pm on November 27, 2012 Permalink | Log in to Reply

          Do you mean “they are only used” or do you mean “they are only *supposed* to be used”? I don’t believe there is anything preventing a user from going ahead and using these shortcodes in the post content.

          • Sami Keijonen 9:39 pm on November 27, 2012 Permalink | Log in to Reply

            Basic, non developer user don’t even know these shortcodes exists. And there haven’t been any question about using them in post content in themehybrid support forum or having problems when changing theme. Chip already pointed out all the others aspects about “post-content” shortcodes.

            But yes you can use them in post content like any other shortcode.

          • Chip Bennett 10:08 pm on November 27, 2012 Permalink | Log in to Reply

            Intended use is what matters here. The shortcodes included with Hybrid are not intended to be used in the post content. End users can do myriad things with any Theme outside of the developer’s intent; such is not our concern (see: software freedoms).

            • Sayontan Sinha 10:53 pm on November 27, 2012 Permalink

              Basic, non developer user don’t even know these shortcodes exists. And there haven’t been any question about using them in post content in themehybrid support forum or having problems when changing theme.

              This argument can be made for any theme. Bear in mind that I am not suggesting that the shortcodes be removed. I am merely saying that shortcodes either don’t matter to users at all because they aren’t aware of them, or the users make fully conscious decisions to use them.

              End users can do myriad things with any Theme outside of the developer’s intent; such is not our concern

              If that is the case, then a simple disclaimer somewhere (like the options panel) should suffice, telling users that some shortcodes are distributed with the theme and that if the users use those shortcodes they run a risk of a lock-in. After all, that takes care of the theme author’s intention. Maybe this could even be built into the core: the way it states on the themes page that a theme uses widgets, there could be something to state that a theme uses shortcodes.

              Not to belabour my point, but nobody seems to be getting that there are themes out there that have shortcodes in active use. Pulling the plug on the shortcodes simply leaves all users of such features in the lurch. And not allowing shortcodes even if there is a separate plugin offering all of them seems even more counter-intuitive.

            • Chip Bennett 11:37 pm on November 27, 2012 Permalink

              …or the users make fully conscious decisions to use them.

              I question whether such decisions are truly “fully conscious”; I don’t think most users realize what will happen to their post content if and when they switch Themes.

              Not to belabour my point, but nobody seems to be getting that there are themes out there that have shortcodes in active use. Pulling the plug on the shortcodes simply leaves all users of such features in the lurch.

              Of course we know that there are approved Themes that bundle shortcodes. Changing the Guideline doesn’t mean that those Themes are suddenly going to get suspended or anything. (Our aim is to *improve*, not to *degrade*, the user experience.) But that doesn’t mean that we shouldn’t or can’t say, “henceforth, no more.”

              And not allowing shortcodes even if there is a separate plugin offering all of them seems even more counter-intuitive.

              I don’t think there is any need to “grandfather” Themes that currently have shortcodes. I don’t see any problem with providing a transition for existing Themes with shortcodes. In your next update, make them pluggable in your Theme, and instruct users to install/activate the Plugin. Then in the subsequent update, you can safely remove them from your Theme.

            • Sayontan Sinha 11:57 pm on November 27, 2012 Permalink

              I question whether such decisions are truly “fully conscious”; I don’t think most users realize what will happen to their post content if and when they switch Themes.

              Themes are supposed to prefix their custom functions with a slug. I have always extended this to mean that their custom shortcodes should be prefixed with a slug. At least that is what I have practised always and I have even made a suggestion to this effect on the WPTRT list. If that is the case, using a shortcode from the theme becomes a very conscious choice, particularly since there is no UI provided to insert the shortcode.

              In your next update, make them pluggable in your Theme, and instruct users to install/activate the Plugin. Then in the subsequent update, you can safely remove them from your Theme.

              You are assuming that all users upgrade whenever a new version is available. I am pretty sure that there are several users who skip 5-6 versions before upgrading even if a theme is stable and from an active developer (I have even seen instances where people wait several months before upgrading).

              Regardless, if a rule is being set, there should be clear cut distinctions in the review guidelines between what is a permissible shortcode vs. what isn’t, with specific examples. Very often with other vague requirements I have had to go back and forth with a reviewer because his/her interpretation didn’t match mine.

            • Chip Bennett 12:25 am on November 28, 2012 Permalink

              If that is the case, using a shortcode from the theme becomes a very conscious choice, particularly since there is no UI provided to insert the shortcode.

              That still doesn’t make it a “fully conscious” choice, unless the user has been explicitly told “your post content will not display properly if you switch Themes”.

              You are assuming that all users upgrade whenever a new version is available.

              As a matter of principle, we do not facilitate users who choose not to keep their core, Theme, and or Plugin code current. Users are fully within their rights not to update, but that doesn’t mean we must accommodate that decision.

              Regardless, if a rule is being set, there should be clear cut distinctions in the review guidelines between what is a permissible shortcode vs. what isn’t…

              I’m not sure how much more explicit we can be with respect to shortcodes.

              If the Theme instructs or implies to users that bundled shortcodes are to be used in the post content, they are not allowed. If the shortcodes are intended to be used for other purposes (extending the Theme via hooks, or for user-configuration of template elements, etc., then they are allowed.

            • Sayontan Sinha 1:24 am on November 28, 2012 Permalink

              That still doesn’t make it a “fully conscious” choice, unless the user has been explicitly told “your post content will not display properly if you switch Themes”.

              I disagree. Regardless, I did make recommendations for this on this very thread:

              1. Make the users specify explicitly in their options page or in the readme.txt file that the shortcodes are not portable. You take your pick where you want them to specify this.
              2. Or make a modification to the core to show that a theme is defining shortcodes in the Appearance → Themes page. I am willing to write a patch if if this has takers, because that way it will not matter where a user has got a theme – the message will give the user fair warning even if the theme author hasn’t put it in.

              I’m not sure how much more explicit we can be with respect to shortcodes.

              Sorry, but this is not at explicit from any point of view:

              Themes must not bundle custom post-content shortcodes

              It makes no effort to define what a post-content shortcode is and to say that it leaves itself open to misinterpretation is an understatement. To me something like entry-title is a post-content shortcode, simply because it is defined in the context of a post. But you interpret this differently. I have multiple shortcodes of this sort, which if I went with my definition, I would have to pull from the theme, but based on your description they are fine because most of them don’t need to be executed in a post’s content.

              You could consider appending your own text from the above to the messaging:

              If the Theme instructs or implies to users that bundled shortcodes are to be used in the post content, they are not allowed. If the shortcodes are intended to be used for other purposes (extending the Theme via hooks, or for user-configuration of template elements, etc., then they are allowed.

            • Chip Bennett 2:31 am on November 28, 2012 Permalink

              You could consider appending your own text from the above to the messaging

              Oh, I certainly will.

              In case it hasn’t been apparent, I do try to go back to the OP and update the list based on the outcome of discussion in the comments. But, I try to wait until some consensus becomes clear, or until all questions have been answered regarding clarity/intent/etc. (For example, I think it would be more clear to refer to $post->post_content or the_content() rather than “post-content”, to indicate the shortcodes to which the guideline will apply.) I just want to make sure everything is clear before I edit the OP.

      • shawn 3:50 pm on November 28, 2012 Permalink | Log in to Reply

        Perhaps it would be helpful to shift your paradigm from functionality to content. Properly designed Themes will support most functionality out-of-the-box.

        Asked a different way: what functionality do you think Themes should be defining?

        I think we should all shift our paradigm not to content but its content usability and consumption, realizing that themes are more that just a presentation layer but the UI, disseminating and distributing content.

        The role of the theme while understated by its definition in the rule is very important to not only the success of the application but the site it powers. Themes should therefore be able define all “non out of the box” functionality or at least have a role in saying how it affects functionality of the theme.

        No. That is precisely the purpose of a Theme. WordPress is designed such that the Theme is the content presentation abstraction layer.

        That maybe so, but the design and implementation of the layer is functional and requires functionality. What abstraction does is hide that functionality from the end user, attempt to remove then the applications becomes static, useless.

        The problem I am having is that WordPress has now officially separated presentation from functionality, so the installation of a WP blog / site is becoming more and more windows-esque Drivers (plugins) Required, taking 100 year (computer years) step backwards.

        Look I get the problem mixing design and code is bad, but lets fix it the standard way by encouraging devs to separate design from data and code and not by penalizing theme dev/designers for their innovation!

        • Chip Bennett 4:21 pm on November 28, 2012 Permalink | Log in to Reply

          Shawn, that is a discussion, and a paradigm shift, that is far outside the scope of this periodic guidelines review process. Such a shift would fundamentally alter the underlying principles of the guidelines, and not something that we’re going to consider as part of this exercise.

          If you do feel passionately enough about it, though, I would recommend starting a discussion on the Theme-Reviewers mail-list, where the discussion can be given a more full and proper treatment.

          • shawn 5:20 pm on November 28, 2012 Permalink | Log in to Reply

            I not sure I understand why, if a guideline is fundamentally flawed it should be automatically reviewed or at least redefined.

            You simply cannot separate presentation from functionality, it would be like trying to create a graph without the data.

          • Chip Bennett 5:27 pm on November 28, 2012 Permalink | Log in to Reply

            I disagree that the presentation-vs-functionality guideline is “fundamentally flawed”. Again: if you do feel passionately about the matter, please start a discussion on the Theme-Reviewers mail-list, and we can discuss it at length, with all interested parties.

            • shawn 5:48 pm on November 28, 2012 Permalink

              I will seriously consider putting aside some time for it!

              Thanks for your time and patience Chip.

      • wpweaver 6:51 am on December 1, 2012 Permalink | Log in to Reply

        I missed the start of this discussion, but I do have a few thoughts on this. My theme, Weaver II, does indeed include a quite a few shortcodes, and certainly some of them could be unbundled and put into a plugin.

        But at least two of them, and they are both heavily used by my theme’s users, really would not work outside the context of the theme’s support framework. One is almost an integral part of how users can present content – a show post shortcode. The main reason it can’t go outside of the theme is that it relies on theme settings and display functions to format posts – picking up all the theme local layouts, how to display post information, etc. It truly is integrated with theme design. One could remove it to a plugin, but that plugin would only work when integrated to the theme.

        The other is a shortcode to conditionally display content depending on the if the view is mobile. While my theme is fully responsive, it also can dispay things differently depending on the user agent – so it is really more than responsive. How does one separate the plugin from the mobile display model of the theme? Even if using just the responsive parts, there are still theme settings to determine when various display items switch.

        And as been mentioned before, updating an existing theme that had been forced to eliminate included shortcodes, would mean that literally tens of thousands of sites would instantly be broken upon update.

        I do appreciate the goal of switching theme and having things still work. But my theme does things that no other themes can do, and part of the capability is to provide an integrated environment for the site developer.

        So – I think there needs to be some kind of grandfathering of existing themes. It just would not be reasonable for thousands of existing sites to break just to enforce a rule.

        One possible aid to solving the theme switch problem would be to require themes with built-in content side shortcodes to provide some kind of plugin that provided near-equivalent functionality upon theme switch. This might be difficult in some cases (e.g., my post shortcode or conditional display on mobile devices), but I suppose one could come close. I’ve even had this on my development list to help my own users who might want to switch.

        And not to shoot myself in the foot, but what about Page Templates? My experience is that switching themes that don’t have similar page templates is actually harder than some shortcodes.

        But at the heart of it, I still believe that there is room in the free repository for higher level themes that represent more of a complete environment that includes tightly integrated widgets, page templates, and shortcodes. Not every user is ready to develop their own child-theme, or spend hours hunting through plugins to find the functionality that fits just right with some theme – if they can add their own CSS rules to make the plugin’s styling consistent with the rest of the theme.

        • Chip Bennett 11:58 pm on December 1, 2012 Permalink | Log in to Reply

          Given that Weaver already has an associated Plugin, I don’t see any reason that the bundled shortcodes can’t easily be shunted off to that Plugin. In any case, there are other ways to implement a “show_posts” shortcode (which is really just a wrapper for a custom WP_Query() call) in a custom page template) than having users put the shortcode in $post->post_content.

    • Philip Arthur Moore 12:09 am on November 27, 2012 Permalink | Log in to Reply

      Change Theme Screenshot (screenshot.png) maximum dimensions from 300x225px to 600x480px.

      Should this read 600x450px?

    • Vicky Arulsingam 12:59 am on November 27, 2012 Permalink | Log in to Reply

      Shouldn’t custom post types fall under the “presentation-vs-functionality” rule?

      In terms of exceptions, if the theme author provides a plugin for shortcode/custom post type functionality, is that acceptable?

      • Chip Bennett 2:25 am on November 27, 2012 Permalink | Log in to Reply

        CPTs are a separate discussion, and are already handled by the “special use-case” Theme exception.

        If shortcodes can be placed in a Plugin, and the user directed to install the Plugin if/when he switches away from the Theme, then why not short-circuit the Theme altogether, and just release the shortcodes in Plugin form to begin with?

        Asked another way: what is the compelling reason for a Theme to bundle post-content shortcodes?

    • Sayontan Sinha 1:22 am on November 27, 2012 Permalink | Log in to Reply

      +1 for accepting themes that offer bundled shortcodes/CPTs as plugins.

      • Chip Bennett 2:23 am on November 27, 2012 Permalink | Log in to Reply

        CPTs are a separate discussion, and already handled by the “special use-case” Theme exception.

        I see no reason for any Theme ever to bundle post-content shortcodes.

    • Danielx64 4:02 am on January 24, 2013 Permalink | Log in to Reply

      Can we please add remove “wp_enqueue_script( ‘comment-reply’ )” to the list and make it recommended? One reason is that some people (like me) wants to add a quote button and therefore they don’t need to use the above function.

  • Chip Bennett 3:21 pm on May 8, 2012 Permalink | Log in to leave a Comment
    Tags: , Guidelines   

    Proposed WordPress 3.4 Guidelines Revisions 

    As we near the final release of WordPress 3.4, it is time to begin discussion and finalization of the related changes to the Theme Review Guidelines. Below are the proposed changes. Please discuss in the comments. We’ll do our best to keep this proposed list updated based on discussions in the comments.

    New WordPress 3.4 Functionality

    • Custom Headers/Backgrounds
      • New and deprecated functions are already covered by existing Guidelines. Themes may OPTIONALLY provide backward-compatibility with pre-3.4 handling of custom backgrounds and headers
    • Child Themes
      • Child Themes will formally be allowed to be submitted for inclusion in the Theme repository.
      • Child Themes are REQUIRED to use an approved Theme as a Template (i.e. as the Parent Theme)
      • Child Themes are REQUIRED to demonstrate sufficient difference from the Parent Theme to warrant inclusion
      • Stand-alone Themes are REQUIRED to provide basic Child-Theme support, including:
        • Proper use of get_template_directory()/get_template_directory_uri() vs. get_stylesheet_directory()/get_stylesheet_directory_uri()
        • Proper enqueueing of stylesheets, and proper cascading of styles, including no inline styles in the Theme template
    • Backward Compatibility
      • Backward compatibility is covered by existing Guidelines. Per existing Guidelines (2 major WP versions required/1 major WP version recommended):
        • Themes MUST NOT support backward-compatibility for more than two major WordPress versions (i.e. 3.2).
        • Themes are RECOMMENDED NOT to support backward-compatibility for more than one major WordPress version (i.e. 3.3).
    • Theme Settings and Data Security
      • Themes are RECOMMENDED to incorporate Theme options into the WordPress core Theme customizer.

    New Guidelines (REQUIRED)

    • Required Hooks and Navigation
    • Theme Features
      • If implementing a site logo, Themes are REQUIRED to provide user-configuration of the logo via the core custom header feature. (Exception: if incorporating both a site logo and custom header, the custom header is required to support the core custom header feature, and the custom logo is then required to be implemented via custom Theme option.)
    • Function Parameters, Filters, and Action Hooks
      • Themes are REQUIRED to use function parameters, filters, and action hooks where appropriate in order to modify content, rather than hard-coding:
        • wp_title: Themes are REQUIRED to modify output via wp_title filter. (Refer to Codex note.)
        • body_class()/post_class():
          • Themes are RECOMMENDED to modify output via filter
            (body_class/post_class)
          • Themes may OPTIONALLY modify output via function parameter
            (body_class( $class )/post_class( $class ))

    New Guidelines (RECOMMENDED)

    • Code Quality
    • Script Enqueueing
      • Themes are RECOMMENDED to enqueue the comment-reply script at the comment_form_before hook
        function theme_slug_enqueue_comment_reply_script() {
	if ( comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'comment_form_before', 'theme_slug_enqueue_comment_reply_script' );

    Clarifications

    Clarifications to existing guidelines being enforced:

    • Presentation vs Functionality
      • Themes are REQUIRED to function as stand-alone code. Themes may OPTIONALLY integrate support for third-party Plugins; however, Themes are REQUIRED to degrade gracefully and to function fully and properly without any such Plugins active.

    Feedback

    What else should be included? What should be revised? Let us know in the comments.

     

    • Andy Adams 4:36 pm on May 8, 2012 Permalink | Log in to Reply

      I’m not all too familiar with the .org theme repository requirements, so forgive me if I’m missing any background information. Thanks for all your work putting this together, Chip.

      The piece that I would revise would be the requirement to use the core custom header feature for logos. Many of the themes we develop use logos that don’t span the full width of the page, so it’s technically incorrect to call it a “header”. It comes down to semantics, I suppose. But I don’t like using the word “header” when it doesn’t apply.

      • Chip Bennett 4:52 pm on May 8, 2012 Permalink | Log in to Reply

        And thus, the discussion. :)

        The thought behind the requirement is two-fold: one, consistent UI is ideal for the end user, and two, with the advent of flexible headers, the core custom header feature becomes suitable for variable-sized logos.

        Personally, I think I’d rather see core implement a “site logo” option, because a site logo is Theme-independent (much like the site favicon, title, description, etc.), and then provide a way for Themes to incorporate/support that core feature.

      • Greg Priday 4:59 pm on May 8, 2012 Permalink | Log in to Reply

        3.4 gives you a lot more control over the header size. So it doesn’t need to span the full width of the page. The nice thing about using WordPress’ header functionality is that (I assume) it’ll integrate with 3.4′s theme customizer. Pretty neat.

        I agree though, I think using “headers” as logos might confuse a user. Say the user switches from one theme that uses the header as a header, to another theme that uses the header as a logo. That might not go down too well.

        Having a site logo in the core would be a great solution but for now, maybe this requirement is a bit strict – given it’s essentially a hack.

        • Chip Bennett 5:04 pm on May 8, 2012 Permalink | Log in to Reply

          Which would be easier to migrate in the future, if a “site logo” eventually becomes a core option: a core custom header theme_mod, or a custom Theme option? I don’t know; maybe either one would be equally easy, or equally difficult.

          Also, my thinking with using custom headers for the logo is that it might help differentiate the logo as a site option, rather than as a custom Theme option. But the question of end user confusion may very well be valid…

      • Devin Price 2:22 am on May 12, 2012 Permalink | Log in to Reply

        I agree. If core had a “logo” option, I would say go ahead and make it a requirement. But header implies something different.

        Also, I assume themes that already have a logo option in their theme options would be required to change it, and that could be very confusing for users who update.

    • Konstantin 4:38 pm on May 8, 2012 Permalink | Log in to Reply

      Can we drop the requirement for the following, when loading a textdomain?

      $locale = get_locale();
      $locale_file = get_template_directory() . “/languages/$locale.php”;
      if ( is_readable( $locale_file ) )
      require_once( $locale_file );

      See #20471

      In the comment-reply example, the comments_open() is not necessary (is it?), as it is called just prior to the 'comment_form_before' action.

    • ravi 4:45 pm on May 8, 2012 Permalink | Log in to Reply

      The section on “backward compatibility” is a bit confusing (to me): 2 major WP versions REQUIRED, 1 major WP version RECOMMENDED. That seems contradictory.

      • Chip Bennett 4:50 pm on May 8, 2012 Permalink | Log in to Reply

        Themes are required NOT to provide backward compatibility beyond two major WordPress versions, and they are recommended NOT to provide backward compatibility beyond one major WordPress version. The ideal is no backward compatibility at all, but that ideal simply isn’t practical.

    • Sayontan Sinha 9:37 pm on May 8, 2012 Permalink | Log in to Reply

      So, for the inline styles, consider this scenario:
      1. Let’s say I have some widgets where the users can put in a color that they want some text to show up with in the front end.
      2. There could be several instances of this widget, each with a different ID, which is dynamically assigned at the time of rendering. In such a case how can the user input be captured as an external style?

      I believe that inline styles should be allowed in such scenarios, because you are not taking away the flexibility from a user here: in fact you are offering the user the flexibility to provide such information through the UI.

      Note that the upfront absence of the widget ID makes it almost impossible to determine this information upfront. You could, theoretically parse the array of widgets to find the ID whenever the widgets are updated, then save the information to an external stylesheet, but this is not going to provide any added flexibility, since the method of information entry itself is from the user rather than the developer.

      • Chip Bennett 9:43 pm on May 8, 2012 Permalink | Log in to Reply

        First, remember: in (almost) all cases, exceptions can be requested.

        Second: you’re talking about a Widget, not a template file.

        Third: outputting a user-defined style inline is entirely different from hard-coding inline styles. The point isn’t that there’s anything inherently wrong with inline styles, but rather that hard-coded inline styles are almost impossible to override. User-defined styles output inline don’t fall into that situation.

        I think your scenario is essentially an example of an exception that proves the rule.

    • Bruce Wampler 5:11 pm on May 9, 2012 Permalink | Log in to Reply

      I should have posted a comment from the reviewers list here, sorry…

      But as Chip just said – the guide line applies to front end template files. After re-reading the guideline, it is clear that one of the main goals is to be sure child themes can essentially override anything the need to. Just keeping that goal in mind clarifies where inline styles really matter.

      Rather than widgets, my question was about inline style in the admin side where a child is not as likely to need to override a style. My admin interface code is full of inline styles because it is just kind of difficult to create a bunch of totally arbitrary styles for the admin style sheet anyway.

    • Bruce Wampler 5:19 pm on May 9, 2012 Permalink | Log in to Reply

      Yet another point – partly because recommended often becomes required, so about this one:
      Themes are RECOMMENDED to follow the official WordPress coding standards for all PHP code.

      I have a problem, sort of. Back when I started programming, and tab was based on 8 spaces. So I’ve always programmed with tabs or tabs+4 spaces for indentation. All my files use that – with the help of my IDE (Komodo). While not trivial, it certainly is possible to transform all that to 4 space based tabs which seems to be the PHP “standard”. Same with some of the other conventions, ( space in arg lists ) for example.

      But a problem with massive reformatting like that is that it will essentially make a diff review impossible. Perhaps a solution would be to allow a “reformatting” submission that would be mostly about making the code follow the WP standards?

      • Chip Bennett 6:39 pm on May 9, 2012 Permalink | Log in to Reply

        There are certainly some who want to move in the direction of requiring WP coding standards, but I think we need to have a very long conversation before ever considering that. There are certainly a plethora of best practices in the coding/CSS coding standards, but that doesn’t mean that they should be required.

        One of the primary reasons for core to publish coding standards is to help ensure consistency among disparate patches committed by a growing number of contributors and committers. It is fairly important for the core codebase to be consistent, in order to facilitate troubleshooting, bug-fixing, and future code enhancements and changes. None of these issues apply for non-core-bundled Themes.

        We want to make the coding/CSS coding standards recommended, in order to help raise awareness of those standards among the Theme developer community. I don’t view this recommended status as an intended escalation (unlike, say, the Settings API implementation, which I would prefer very much eventually to escalate to required); rather, I view it merely as awareness and promotion of best practices.

        I think it would be in the community’s best interest to consider each specific standard on a case-by-case basis, to determine appropriateness for inclusion in the Theme Review guidelines as required, rather than a wholesale adoption of those standards. By making the standards recommended, it opens the door to such further discussions within the community.

    • Andrew Nacin 5:07 am on May 10, 2012 Permalink | Log in to Reply

      A few points:

      Both Twenty Ten and Twenty Eleven would fail a number of these guidelines, including: not enqueueing styles, not filtering wp_title(), etc. I would be happy to see a Trac ticket to change these in 3.4 or 3.5. But until we do change them, I’m weary (but okay) with making these requirements.

      The CSS guidelines are still in draft mode, and may not be finalized before 3.4′s release. They were proposed originally by the Automattic theme team and not yet endorsed by the various frontend developers working on core.

      get_template_directory_uri() versus get_stylesheet_directory_uri() is not straightforward and may be tough to judge at times.

      • Chip Bennett 5:07 pm on May 10, 2012 Permalink | Log in to Reply

        I’ll be happy to submit any necessary patches for Twenty Ten and Twenty Eleven. If you see specific places where either would fail, just ping me and I’ll write them up.

        Thanks for the caveat regarding the CSS coding standards. That’s yet another reason that nothing more than recommended is appropriate at this time.

        In some cases, get_template_directory*() vs get_stylesheet_directory*() will be a matter of intended use; most of the time, though, the correct template tag to use is fairly clear. (Can/should be overridden by a Child Theme? Use stylesheet. Can’t/shouldn’t be overridden by a Child Theme? Use template.)

        • Justin Tadlock 6:04 pm on May 10, 2012 Permalink | Log in to Reply

          The use of get_stylesheet_directory*() should rarely be used in standalone/parent themes. It makes the assumption that either a child theme is not being used or that a particular file is housed within a child theme.

          Nearly always, if a regular theme is using *stylesheet*, it should be falling back to *template*.

      • Konstantin 8:29 pm on May 10, 2012 Permalink | Log in to Reply

        Oh, I’d love to contribute too (as a matter of fact, I have a patch prepared).

        @nacin: When you say “enqueueing styles” would that also include style.css?

    • Chip Bennett 5:02 pm on May 10, 2012 Permalink | Log in to Reply

      Please note the recent addition, under Clarifications, regarding stand-alone Theme functionality, and Plugin integration. This is something the WPTRT has been enforcing all along, but is not explicitly spelled out in the current Guidelines.

    • Justin Tadlock 6:01 pm on May 10, 2012 Permalink | Log in to Reply

      Themes are RECOMMENDED to incorporate Theme options into the WordPress core Theme customizer.

      Why recommend this at all? I’m already imagining disastrous scenarios of theme authors going too far. I definitely don’t want to see themes add 100s of options to this thing.

      • Chip Bennett 6:47 pm on May 10, 2012 Permalink | Log in to Reply

        I don’t understand the hesitation. Wouldn’t initial user configuration of custom Theme options via the customizer, upon Theme activation, provide the best-possible user experience?

        Sure, we’ll need to be sensible about how that integration takes place, but I think we can safely play that by ear as developers get their feet wet with the new feature. If we take the same philosophical approach with the customizer tab as we do with the Appearance sub-menu, I think we can reasonably keep things manageable, and avoid such disastrous scenarios as you’re envisioning.

        • Justin Tadlock 12:06 am on May 11, 2012 Permalink | Log in to Reply

          It’s just a question of whether we really need to recommend it, especially until we see how theme authors are utilizing it. I’m neither for or against recommending it. I’d just like to be more cautious with it for a while.

          As far as best user experience goes, I agree, to a degree. It can make for a great user experience as well as a horrible one.

          It’s just something I thought I’d throw out there for discussion.

        • Andrew Nacin 2:35 am on May 11, 2012 Permalink | Log in to Reply

          I agree with Justin. I would not “Recommend” it yet.

          • Chip Bennett 1:42 pm on May 11, 2012 Permalink | Log in to Reply

            I can see where both of you are coming from. Maybe OPTIONAL is a better approach initially? I want the customizer feature to be in the Guidelines (as with basically every other core feature that touches or interacts with Themes), as a basis for establishing future implementation guidelines.

    • Konstantin Kovshenin 6:56 am on May 11, 2012 Permalink | Log in to Reply

      I think it’s also time to make wp_nav_menu required.

      • Chip Bennett 1:44 pm on May 11, 2012 Permalink | Log in to Reply

        well, wp_nav_menu() is required: if the Theme design incorporates a navigation menu. The line we’ve not crossed thus far is dictating Theme design or aesthetic, and I’m not sure we want to cross that line. (Bear in mind that Widget support is required, and that Nav Menu Widgets can be added to dynamic sidebars – so technically speaking, all Themes do support navigation menus, at least in some form.)

    • Konstantin 7:12 am on May 11, 2012 Permalink | Log in to Reply

      I’d love to have a clearer Credit Link guideline with less leeway for both, Theme Authors and Reviewers!

      I’m not too happy about the entire “Credit Link” section of the Theme Review codex page. And when I say not too happy, I mean I hate this part of every review, because of the enormous propability that my findings won’t correlate with the opionion of more seasoned reviewers (as it happened on this one).

      What more is there to a Theme URL, other than it being a page specifically related to the Theme?
      What is relevant and appropriate in a public-facing credit link?
      What we understand under a project/development website?

      As I said before, I think a clarification, and writing up requirements that are currently enforced but not documented, would benefit both, Theme Authors and Reviewers.

      • Chip Bennett 2:01 pm on May 11, 2012 Permalink | Log in to Reply

        I completely understand your frustration. Trying to keep credit link guidelines completely objective, while at the same time avoiding CFR-level detail and breadth, can be a delicate balance.

        Regarding the ticket you linked (and if you want to discuss that one specifically, I’d be happy to do so in-ticket), when I look at the Theme URI, especially for a site that would otherwise not be valid as Author URI, the red flag for me is the ratio of Theme-related content to non-Theme-related content. Another criterion for me is, “how beneficial is this content to the end user?” But these criteria are difficult-to-impossible to quantify objectively. Call it experience-based intuition. (Maybe call it jadedness from dealing with too many Themes with crappy credit links?)

        My personal preference/ideal for an appropriate Theme URI would be Theme-specific landing page on a Theme developer (or Theme shop) site, not an essentially orphaned page, with some Theme-related content, on a site otherwise unrelated to WordPress/Themes. But that preference is not the consensus, so we try to strike a balance regarding appropriateness.

        Theme URI is one of the most subjective guidelines, and as such ends up causing most of the headaches regarding Theme-review observations.

        • Konstantin 3:13 pm on May 11, 2012 Permalink | Log in to Reply

          Please do share your thoughts in-ticket!

          I can see how it is difficult to to come up with objective guidelines, given the variations in Theme URL pages. This is probably why they haven’t been defined in more detail yet.

          But how about starting with someting like:

          Theme page is RECOMMENDED to be on a WordPress/Theme related site.

          I’d love to hear from other reviewers what they look for, when reviewing a Theme and it comes to the Crdit Links! Please share, so we can come to a better understanding on this.

        • Vicky Arulsingam 1:48 am on May 14, 2012 Permalink | Log in to Reply

          The key here is unrelated content.

          I’m okay with the Theme URI being an orphaned page but only if there isn’t unrelated content.

    • Clementine Hobbins 1:00 pm on May 17, 2012 Permalink | Log in to Reply

      Thx for information.

    • Satish Gandham 7:51 am on May 20, 2012 Permalink | Log in to Reply

      Can you please include guidelines for the featured themes, or at least ask the reviewer to say why he thought the theme should be featured.

    • Arie Putranto 8:31 pm on May 20, 2012 Permalink | Log in to Reply

      Well, what if comments.php does not exists but replace by a function which generated the comments list? Is it okay?

      • Justin Tadlock 11:17 pm on August 4, 2012 Permalink | Log in to Reply

        There’s technically not a need for the comments.php template. If your theme doesn’t need it but still handles comments correctly using the appropriate WordPress functions, you’ll be fine.

        • Chip Bennett 11:25 pm on August 4, 2012 Permalink | Log in to Reply

          I disagree. It is a general principle that Themes not rely on legacy template-part file support. And specifically for comments.php, according to source, backward compat for comments.php in comments_template() is intended to be removed, which IMHO is equivalent to it being considered as deprecated:


          else // Backward compat code will be removed in a future release
          919 require( ABSPATH . WPINC . '/theme-compat/comments.php');

          Thus, proper implementation of comments requires use of comments.php, included in the template via comments_template().

          If a Theme has a legitimate reason for an exception to this implementation, then that exception can be handled just like any other guideline exception.

    • @mercime 5:06 pm on May 22, 2012 Permalink | Log in to Reply

      We know now that there are theme authors who add another subpanel, Appearances > More Themes in themes that have been approved/accepted into the WP Theme Repository http://lists.wordpress.org/pipermail/theme-reviewers/2012-April/008791.html

      There should be guidelines surrounding the practice if this (More Themes subpanel) continues and grows, for example:
      1. Maximum number of themes which can be listed in that subpanel.
      2. Links from that subpanel should only go to webpages of approved Theme URL
      3. No affiliate links.
      4. In relation to that, no calling home scripts to find out how many clicked from subpanel links to theme webpage
      5. Best practices for adding subpanel.
      6. Etc.

      Thanks.

    • Emil Uzelac 5:36 am on June 22, 2012 Permalink | Log in to Reply

      Just a very quick note that this 3.4 guidelines will need to be discussed bit more before we actually decide on anything and push this over to http://codex.wordpress.org/Theme_Review

      For example get_template_directory()/get_template_directory_uri() should be recommended, not required.

      The reason is that many users already have Child Themes in place with non get_template_directory()/get_template_directory_uri(), requiring Themes to make a switch will break all of them. If requirements are needed, let’s set this for new submissions only, while only recommending to currently approved ones.

      Yes, this is definitely way to go, but not for currently approved Themes.

      Thanks,
      Emil

  • Chip Bennett 7:56 pm on March 14, 2012 Permalink | Log in to leave a Comment
    Tags: Frameworks, Guidelines, Namespacing   

    Theme Frameworks and Namespacing Guidelines 

    Due to confusion – mostly caused by inconsistent nomenclature – regarding namespacing requirements for Theme frameworks, we would like to clarify the guidelines, and open the floor to discussion.

    First, a word on nomenclature. For the purposes of this discussion, and the guidelines, a “Theme framework” is not a stand-alone Theme, but rather a “drop-in” code library used to facilitate Theme development. The following are examples of such Theme frameworks (note: this list is not an endorsement; rather, it constitutes a quick Google search for examples only):

    Note that none of the above examples constitutes a full, stand-alone Theme. Each is a library of code, used to develop a Theme. Such code libraries are different in both nature and purpose from stand-alone Themes that use the term “framework” to refer to an intended use as a Theme to be forked for further development. (Even the Codex conflates the uses of the “Theme framework” terminology in this manner.)

    So, to keep the terminology clear, when I refer to “framework”, I mean a drop-in code library, and not a stand-alone “starter” or “base” Theme. In other words, using this definition of “framework”: Hybrid Core is a Theme framework; the Genesis Theme (even though it is called “Genesis Theme Framework”) is not a Theme framework, but rather a stand-alone, base/starter Theme.

    Now, on to the Guidelines, which include the following requirement:

    Themes are required to use a unique slug as a prefix for anything in the public namespace, including all custom function names, classes, hooks, public/global variables, database entries (Theme options, post custom metadata, etc.)

    This guideline applies to forked/derivative Themes. For example, several Twenty Ten and Twenty Eleven derivative Themes get submitted to the repository. We require these Themes to re-namespace their custom functions, hooks, global variables, textdomain, etc.

    However, some confusion arises when a Theme uses a framework – i.e. a drop-in code library – to develop the Theme. Should the Theme be required to re-namespace the framework code? Our current thinking is that such a requirement would effectively defeat the purpose of using a Theme framework, and would deter, rather than facilitate, Themes using such frameworks – and, more importantly, keeping the framework updated.

    Requiring Themes to re-namespace such framework library code would be analogous to requiring Themes to re-namespace bundled jQuery Plugin libraries. Also, requiring such re-namespacing serves no practical purpose, and would be counter-productive toward one of the Theme Review Team’s long-term desires to have the means/process/infrastructure for vetting/approving such Theme frameworks, in order to facilitate their broader use. If we started requiring Themes to re-namespace the framework library code today, we’d have a mess on our hands in the future, if we one day are able to have vetted/approved versions of those same frameworks.

    So, bottom line, TL:DR: forked/derivative stand-alone Themes ARE required to re-namespace; Themes that use framework libraries are NOT required to re-namespace the framework library code.

    What are your thoughts?

     

    • ZaMoose 1:08 pm on March 15, 2012 Permalink | Log in to Reply

      Agree 100%. Kind of wish we would just call so-called “Frameworks” “libraries” instead.

      I mean, is the STL a “framework”?

      • Edward Caissie 2:06 pm on March 15, 2012 Permalink | Log in to Reply

        +1; that was the recommendation I was going for in the discussions prior to this post. We just have to get used to not using the “framework” buzzword everywhere it is currently being applied.

      • Justin Tadlock 3:23 pm on March 15, 2012 Permalink | Log in to Reply

        We should start calling those other “so-called frameworks” what they really are: themes. Everyone who builds a theme with a few hooks in it is calling it a framework now. Those of us who have had true development frameworks for years now (e.g., Hybrid Core, Carrington Core, WP Framework) shouldn’t need to start calling them something else because a few companies have decided it’s a good word to use for marketing purposes.

        • ZaMoose 3:33 pm on March 16, 2012 Permalink | Log in to Reply

          Justin:
          No offense intended. Hybrid Core, etc. do indeed hew fairly closely to the compsci definition of “framework” with one small exception:

          Inversion of control

          In a true framework, the program flow is generally dictated by the framework and not the calling program. Perhaps it’s a minor point, but that’s where my objection was coming from.

          • scribu 2:00 am on April 8, 2012 Permalink | Log in to Reply

            Well, it’s not that clear cut. For example, you can’t really call Carrington Core a “library”. You load it, but then it creates the advanced template hierarchy by itself and you can hook into it via some filters, if you need to.

    • Otto 4:31 pm on March 15, 2012 Permalink | Log in to Reply

      Are you speaking of namespacing in terms of function naming or in terms of internationalization calls?

      Function names = don’t care if they re-namespace or not. Doesn’t matter much, since only the active theme is loaded, and having the same functions in multiple themes is fine.

      Internationalization function calls *must* have their domains be replaced with the new domain if there is any such code in the framework that would require it. Note that domains need to be plain text strings as well, using defines or global variables does not work properly, and never really will for various reasons. However, this should be as simple as a global search/replace if the framework is up to par. If the framework is smart about it, all the strings for this could be defined in a single file.

    • Sayontan Sinha 6:34 pm on March 15, 2012 Permalink | Log in to Reply

      What about namespacing of JS libraries? The wp_enqueue_script call provides a handful of JS libraries, but if a theme is using a common JS library like Fancybox or JQuery Cycle, what is the requirement? Does the $handle argument of wp_enqueue_script need to have the theme name prefixed? This can lead to repeated loading of the same file on a site.

    • Michael Fields 6:49 pm on March 19, 2012 Permalink | Log in to Reply

      Hello,

      The above requirements appear to have been altered before this post was made to include “hooks” in the requirements:

      Themes are required to use a unique slug as a prefix for anything in the public namespace, including all custom function names, classes, hooks, public/global variables, database entries (Theme options, post custom metadata, etc.)

      Read the Codex changeset.

      I was just wondering if there was any discussion regarding these changes to the requirements? I would love to have taken part in such a dialog. Hooks are bit different when compared to the other items in the list. IMHO it is perfectly valid for a theme to include un-prefixed hooks. One of the most convincing use-cases is plugin integration. I’ve been using this practice for many months mainly inspired by Rethinking Template Tags in Plugins. I really love this solution and think it’s great for automatic plugin/theme integration. I use it myself here.

      I believe that introducing such a requirement may limit communication between plugins and themes. I do my best to follow the guidelines laid out by the WPTRT. Can we discuss this topic more?

      • Chip Bennett 6:53 pm on March 19, 2012 Permalink | Log in to Reply

        Indeed; I changed that guideline to clarify the existing intent, which is that everything belonging to the Theme that resides in the public namespace, must be uniquely prefixed.

        I’m all in favor of using a consistent, standard nomenclature for hooks; unfortunately, no such standard exists. If/when it does, it will certainly be a benefit to developers and users alike, for exactly the reasons you stated.

  • Chip Bennett 1:48 am on December 15, 2011 Permalink | Log in to leave a Comment
    Tags: Guidelines,   

    Getting the Review Queue Back on Track 

    As I write this post, Theme-Trac indicates the following:

    Welcome to WordPress Themes Trac

    There are 161 new tickets waiting for review. 24 themes were reviewed in the last 7 days.

    Although right now is the holiday season here in the US, and most of us have been busy getting ready for the just-released WordPress 3.3, that review queue number is extraordinarily high. That number represents a lot of developers awaiting feedback on their Themes, and a lot of end users not benefiting from new and/or updated Themes. Let’s see what we can do to address it!

    Revising the Trainee Reviewer Experiment

    First things first: the Theme Review Team has been experimenting with a training program for new reviewers. After a few months, it appears that this experiment isn’t working out as intended. New reviewers aren’t getting assigned tickets as quickly as possible, and full reviewers don’t seem to have enough time to follow up on those reviews, provide feedback, and resolve/close the tickets. While we want to provide training for new reviewers, so that we equip our volunteers with the tools and skills necessary to complete Theme reviews, we can’t let that training get in the way of completing Theme reviews.

    So, effective immediately, we’re going to try something else: anyone who requests a ticket to review, and then completes their assigned review, will be given full “reviewer” status in Theme-Trac. That means that, once a new reviewer has requested and completed their first ticket, they will then be able to assign themselves tickets, and will be able to resolve/close tickets on their own. An admin reviewer will double-check tickets resolved as “approved”, but otherwise, once you’ve done one review, you’ll be free to review without the burden of any additional oversight.

    Where previously we have been slow to “promote” to full reviewer status, and exceedingly slow to remove reviewer privileges, now we will look to be very quick in granting reviewer privileges, and perhaps somewhat quicker than we were previously with removing reviewer privileges, either due to inactivity or poor reviews (mainly, approving Themes that should not be approved).

    Revising the Queue Priorities

    Second: for a considerably longer period, the Theme Review Team has used a three-tiered priority approach to the review queue:

    1. Priority #1: Currently Approved Themes
    2. Priority #2: Previously Reviewed, Not-Approved Themes
    3. Priority #3: Never-Reviewed Themes

    This three-tiered approach has worked fairly well, especially for Themes that have successfully passed the review process, and are currently approved. However, the Theme Review Team has been unable to keep the Priority #2 queue cleared, meaning that new Themes end up waiting weeks (or longer) to get even an initial review.

    So, effective immediately, we’re adding a fourth tier to the prioritization, which will become the new #2 priority: tickets that have been in the review queue for longer than two weeks, regardless of previous review/approval status. The new prioritization will be as follows:

    1. Priority #1: Currently Approved Themes
    2. Priority #2: Tickets Older Than 2 Weeks
    3. Priority #3: Previously Reviewed, Not-Approved Themes
    4. Priority #4: Never-Reviewed Themes

    Hopefully with this change, the oldest tickets will be reviewed in a more timely manner. Our long-term goal will be that this new Priority #2 queue will be – and stay – empty; but for now, it will help ensure that tickets don’t stay in the queue for weeks on end.

    Revising Handling of Review-Based Theme Revisions

    Currently, once a Theme is reviewed, if the developer revises the Theme to address issues from the review, and then re-submits the Theme, the re-submitted Theme goes to the end of the Previously-Reviewed Themes queue. This process does not encourage or facilitate such review-based Theme revisions. Understandably – especially with the state of the review queue – Theme developers may be discouraged by the process, and may choose never to submit a revision. This outcome helps no one: end users don’t benefit from an approved Theme becoming available, Theme developers don’t benefit from having their Theme hosted in the repository, and the Theme Review Team expends time and effort reviewing a Theme that never ultimately gets approved.

    For some time, the Theme Review Team has had an informal policy, subject to the discretion of each reviewer, of allowing a review to be continued on a subsequent ticket, if a revision is submitted in a timely manner. This informal policy has facilitated prompt Theme revision submissions, and has led to more Themes eventually passing Theme review, and being approved.

    So, effective immediately, we’re formalizing this policy: any review-based Theme revision that is submitted within two days of the previous review will be assigned to the previous-ticket reviewer, and the review continued on the new ticket. Bear in mind: exercise of this policy will still be at the discretion of each reviewer, and should be considered to be a privilege, based on a good-faith effort on the part of the Theme developer. While most Theme developers will exercise such good-faith effort, I want to make clear that this policy is not a license to use the review process as quality control.

    Revising Review Emphasis

    The Theme Review Guidelines currently include a requirement for W3C HTML/CSS validation. It has become clear that this requirement is largely a distraction, both to developers and to reviewers. From the beginning, the W3C Validation requirement was intended to be a holistic tool used in the review process, rather than a rigid requirement; however, all too often, reviews have emphasized W3C Validation results – even at the expense of far more important guideline requirements.

    So, effective immediately, W3C Validation criticality is being reduced from REQUIRED to RECOMMENDED, and Theme reviewers will no longer make review comments regarding W3C Validation. Theme developers can/should use W3C Validation as a development tool, but it will no longer be part of the review process.

    Also, the Theme Review Team has made an effort to ensure that every review is thorough and complete, in order to reduce the number of times any given Theme must go through the submission/review process prior to approval. However, it is clear that this emphasis on thorough reviews has acted to the detriment of performing reviews expeditiously. What was intended to be a service to Theme developers has actually led to more developer frustration, as the review queue continues to grow.

    So, effective immediately, the Theme Review Team will no longer emphasize complete and thorough reviews, and will instead close tickets upon observation of any non-trivial issues. Theme developers have always been responsible for knowing and following the Theme Review guidelines. The key take-away on this point: if you have a question, ASK. As much as we would like to walk every developer through the review/approval process, we simply don’t have enough volunteers to spare the time. If you are unsure about a review guideline, or need clarification on a review comment, ASK. Ask on the theme-reviewers mail-list before you submit your Theme. Ask in the review ticket after you submit. We are here to help developers, but will need to rely more on developers to communicate your questions and concerns, so that we can focus more on reviewing/closing tickets.

    Summarizing The Changes

    Again, here’s what we’re going to be doing differently, effective immediately, to help facilitate Theme reviews:

    • Anyone who requests a ticket to review, and then completes their assigned review, will be given full “reviewer” status in Theme-Trac
    • We’re adding a fourth tier to the prioritization, which will become the new #2 priority: tickets that have been in the review queue for longer than two weeks, regardless of previous review/approval status
    • Any review-based Theme revision that is submitted within two days of the previous review will be assigned to the previous-ticket reviewer, and the review continued on the new ticket
    • W3C Validation criticality is being reduced from REQUIRED to RECOMMENDED, and Theme reviewers will no longer make review comments regarding W3C Validation
    • The Theme Review Team will no longer emphasize complete and thorough reviews, and will instead close tickets upon observation of any non-trivial issues

    I would also like to add a gentle reminder that the Theme Review Team is a 100% volunteer effort. None of the Theme reviewers are paid for our efforts. For almost all of us, Theme reviews take time away from other development work (whether paid or free) – time that we are happy to contribute. That said: while we understand your frustration in waiting for your Theme review to be completed, I would like to make a request: before you email the theme-reviewers mail-list asking when your Theme will be reviewed, post a comment to the current Trac Ticket Review Request Queue, and ask to be assigned a ticket of your own to review. This request is not a pay-for-play scheme, and no tickets or developers are given special treatment for participating in Theme reviews; rather, the more people we have reviewing Themes, the faster the review queue will get processed. (And as a bonus: you’ll learn more than you might otherwise imagine about what is required to pass the review process successfully.)

    Remember: in the end, our entire effort is all about ensuring that WordPress end users have the best-possible Themes available for use.

    If you have any other suggestions for how we can improve the process, please let us know – either in the comments, or via the theme-reviewers mail list.

     

← Older posts

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