WordPress.org

Theme Review Team

Recent Updates Page 2 Toggle Comment Threads | Keyboard Shortcuts

  • Justin Tadlock 6:38 pm on May 7, 2015 Permalink |
    Tags:   

    Customizer tutorials and documentation 

    One of the things that TRT has been doing over the past several months is striving to make education a top priority. We’ve got some awesome things in the pipeline (look out for design and accessibility resources soon).

    Today’s topic is about utilizing the Customization API (i.e., the theme customizer). Over the past week I’ve been gathering links to various tutorials to share with theme authors. There’s actually quite a bit that’s been written on the customizer. I thought it’d be helpful to consolidate some of these into one place.

    This list is just a sampling of what’s out there. It also gives us an idea of what hasn’t been written about so that we can strive to provide more examples.

    Official Documentation

    Of course, the best place to start is the developer handbook right here on WordPress.org. So, dive into the Customizer API docs before anything.

    General and Basic Tutorials

    The following tutorials are mostly overviews and general tutorials on the basics of working with the customizer. A few dive into some more advanced topics, but for the most part, they’re good for getting acquainted with the customizer.

    Advanced and Specific Topics

     
    • mattmedeiros 7:40 pm on May 7, 2015 Permalink | Log in to Reply

      Wanted to include our 3 part series on working with the customizer and the previewer. This tutorial explores adding “helper” buttons to the previewer which communicate with the customizer. Opening panels/sections, passing data, and more.

      https://conductorplugin.com/developing-wordpress-customizer-part1/
      https://conductorplugin.com/developing-wordpress-customizer-part2/
      https://conductorplugin.com/developing-wordpress-customizer-part3/

      • usability.idealist 10:37 pm on May 15, 2015 Permalink | Log in to Reply

        +1

        Hell, that’s been one of the most helpful (series of) tutorial(s) for the Customizer for ages!

        Where is the like-button if you need it? Ah well .. Guess the old “+1″ has to do it! 😉

        I’d wish folks would go more into detail how to actually work with the JS and not focus on how to create pansy, easy-peasy stuff. That’s been my major cause of headache – or maybe call it “grief” – since I started intensely wrestling with the Customizer last year (ie. April 2014).

        cu, w0lf.

        • Justin Tadlock 1:49 am on May 16, 2015 Permalink | Log in to Reply

          I’ve just started working with JS on the customize controls side of things (nothing too advanced yet), but maybe there’s a tutorial or two I can get out of it.

          Of course, there’s JS on the preview side as well. I’ve worked with that a bit. You kind of have to for live previews.

          Anyway, I’m no JS guru, but I’d love to hear about anything in particular you’d like to learn about. Maybe it’ll get my creative juices flowing.

    • Emil Uzelac 6:27 am on May 8, 2015 Permalink | Log in to Reply

      You nailed it!

    • Matt Hill 7:01 am on May 8, 2015 Permalink | Log in to Reply

      Fantastic resources, thank you for compiling these Justin.

    • Jami Gibbs 11:40 am on May 8, 2015 Permalink | Log in to Reply

      Stellar. Thanks Justin!

    • Samuel Wood (Otto) 12:43 pm on May 8, 2015 Permalink | Log in to Reply

    • Maria Antonietta Perna 2:36 pm on May 9, 2015 Permalink | Log in to Reply

      At last some great educational buzz on the Customizer! Thanks :)

    • wpweaver 3:52 pm on May 14, 2015 Permalink | Log in to Reply

      At some point, if I remember right, you or someone else generously offered to take comments on limitations in the Customizer interface, and perhaps work on implementing new features.

      Is there an ongoing thread for such a specific discussion? I have a few significant suggestions, but they obviously belong elsewhere.

      • Justin Tadlock 4:55 pm on May 14, 2015 Permalink | Log in to Reply

        The idea is to put together control classes (possibly setting classes) to extend the customizer that theme authors don’t know how to build. I’m personally doing tutorials on each that I build to explain things. Anyway, this is as good of a place as any to ask.

        • wpweaver 3:31 pm on May 16, 2015 Permalink | Log in to Reply

          OK –
          1. The Customizer apparently uses the WP color picker. The color picker has, in my opinion, a serious lack that would totally frustrate any serious site designer – no way to handle transparency. It seems you can just specify a solid hex color. It really needs to be able to support named colors, including ‘transparent’, as well as rgba or other transparency standard. It is time to move beyond IE8 color support, I think. I really can’t believe that every single place there is a color option (any where on standard WP options) that only solid colors are allowed.

          2. All the Customizer examples I’ve seen only have menus one level deep (only the right arrow at the top most level). This may just be restricted thinking, but can one go deeper?

          3. One of the most serious flaws with Customizer when it comes to designing user friendly, helpful interfaces (as opposed to simply consistent ones) is the limited width. This makes it EXTREMELY difficult to provide appropriate context help within each panel/tab – a good explanation of a feature simply takes up too much space. What would really help this situation would be a universal, standard pop-up help symbol (like a ? or “i” icon) that the theme developer could easily specify, and the end user could click to get a tool-tip-like pop-up help field.

          4. Text entry fields seem really small – again, the limited width. For example, one option that seems to be somewhat common in themes using Customizer with more advanced options is a custom CSS field. It would be very helpful to the end user if there were a mechanism to auto-expand these fields, or at least have some resizing capability. Believe it or not, some site designers actually would like to be able to see their custom CSS rules more like they can in a real editor, and not crunched up in a tiny little box. Makes life so much simpler.
          (Just a dream, but a really nice CSS editor window with syntax highlighting and CSS rule generation help would be fantastic, but is obviously not high priority.)

          5. BG colors? Having shaded or colored backgrounds on different panels can greatly enhance the user experience. Is this supported?

          6. Hidden/Advanced options. It can be a very helpful practice to hide or shrink more advanced options to help avoid clutter. So it would be nice to have a built-in option to have some options easily expand/contract. Just adding another panel does not solve this interfact design issue as these advanced options are usually associated with a more basic option and should be in the same place.

          • Ulrich 4:07 pm on May 16, 2015 Permalink | Log in to Reply

            Responses:
            1. What do you use in your settings page?
            2. I am not sure. I have never tested it.
            3. I think you should not need to much contex help as the user will be able to see the changes happening live on their site. Here is an interesting talk related to this from LoopConf: https://www.youtube.com/watch?v=7usuZRBsyk8
            4. I opedned a trac ticket for this https://core.trac.wordpress.org/ticket/32296
            5. You should be able to load CSS styles on the customizer page and style the customizer like you want like you have done in the settings pages.
            6. It should be possible to extend the customizer to include this.

          • Justin Tadlock 4:12 pm on May 16, 2015 Permalink | Log in to Reply

            1) I believe Kirki has a color control that allows transparency. I’d definitely check that out. Another option is to use a basic range input to allow transparency control. It’d mean a separate setting, but I’ve seen this done on a couple of themes before.

            2) Panels allow you to go two levels deep.

            3) Otto shows how to change change the width in his most recent tutorial. I also plan to write a tutorial on customizing the customizer that goes into a bit more depth. As for a univeral help symbol, that’s an idea you’ll need to get in touch with the customizer team about.

            4) Have you looked into how large widgets slide out to the side of the customizer? That’s one option that I think would work here. I’ll be honest and say that I don’t know how that’s done. I’d love to see a non-core theme/plugin that does it.

            5) Do you mean colored customizer panel/section backgrounds? Yep, that’s doable. Follow the custom CSS example in Otto’s tutorial I linked above. I can also cover this in my tutorial.

            6) This is actually possible now. I’ll need to write out the code and probably a tutorial on it.

    • Tomas Mackevicius 1:53 am on May 19, 2015 Permalink | Log in to Reply

      Is it possible to get validator like there is one for plugin readme:

      https://wordpress.org/plugins/about/validator/

  • Samuel Sidler 3:01 am on May 7, 2015 Permalink |  

    Genericons and Theme Updates 

    Earlier today, the core security team shipped new versions of a number of themes that were vulnerable to a cross-site scripting issue due to shipping a Genericons example file. This was in conjunction with WordPress 4.2.2 but happened hours prior to it shipping. This is the first time we’ve updated themes without notifying the theme authors ahead of time, so I wanted to make sure that we let you know that it happened and answer any question you have.

    Note: Among the themes updated was Twenty Fifteen due to the same vulnerability.

    If you have any questions, feel free to ask and I’ll do my best to respond to them.

     
    • Jeff Chandler 3:57 am on May 7, 2015 Permalink | Log in to Reply

      Is it possible to see a list of affected themes?

    • Jose Castaneda 5:06 am on May 7, 2015 Permalink | Log in to Reply

      Thanks for letting us know Sam!

    • Stephen Cronin 7:49 am on May 7, 2015 Permalink | Log in to Reply

      Just wondering – when you say “the core security team shipped new versions”, do you mean that they just updated the themes on wordpress.org, or do you mean they force updated users’ sites?

      If they force updated users’ sites, I’d be really curious as to whether the number of users losing customizations (ie having edited files) was a significant issue or not. I’m not sure the average user knows how to use child themes, which is a pity.

      • Samuel Wood (Otto) 9:34 am on May 7, 2015 Permalink | Log in to Reply

        We updated the themes on WordPress.org with new version numbers. These versions were identical to the previous versions, with only the single problem file removed.

    • Deborah 3:28 pm on May 7, 2015 Permalink | Log in to Reply

      Thanks for the update. Appreciate all the work from the security team. Like Jeff, I’d be interested in the list of updated themes.

  • Tammie 9:03 pm on May 6, 2015 Permalink |  

    Theme review team weekly meeting notes

    The logs are here:
    https://wordpress.slack.com/archives/themereview/p1430848645010243

    Points from meeting:

    • @jcastenada updated on the readme.txt. This will be a new recommended item for all reviews.
    • @jami0821 and @melchoyce updated us on the design handbook. They are going to try and get Custom CSS thanks to @samuelsidler who will look into this for the handbook. This will help with examples.
    • @davidakennedy and @joedolson have been hard at work with the doing_it_accessibily_wrong theme. Videos are coming really soon. This is all really exciting as means we can train sooner.
    • The queue push was a great success, so much we’re going to have another one every month. The last Saturday of every month will be the push day. That makes the next one 30th May.
     
  • Tammie 11:28 am on May 5, 2015 Permalink |  

    This week’s meeting agenda

    We have a meeting today at 18:00 utc. Lets get updates on the following:

     
  • Jose Castaneda 10:36 pm on April 29, 2015 Permalink |  

    A revised readme 

    In our meeting we talked about the addition of a changelog. The consensus was including it in the readme.txt file like plugins do. To quote Otto:

    If we had it in the readme.txt, we’d expose the data to core via the API, same as we already do with plugins

    In order to make this happen we need to determine what – from the plugin’s readme – we can use, create a sample file and have all theme authors adopt it. @greenshady provided a sample one and @grapplerulrich even added in about a dedicated license section – which I think we can do.

    Below is a revised version of Justin’s and includes Ulrich’s idea of the bundled resources section.

    === Theme Name ===
    Contributors: (this should be a list of wordpress.org userid's)
    Tags: left-sidebar, fixed-width, custom-background
    Requires at least: 4.0
    Tested up to: 4.3-alpha
    Stable tag: 1.0.3
    License: GPLv2 or later
    License URI: http://www.gnu.org/licenses/gpl-2.0.html
    
    Short description. No more than 150 chars.
    
    == Description ==
    Theme desc.
    
    == Frequently Asked Questions ==
    
    = A question that someone might have =
    
    An answer to that question.
    
    == Changelog ==
    
    = 1.0 =
    * Added new option
    
    = 0.5 =
    * Security bug addressed
    * Changed thumbnail size
    
    == Upgrade Notice ==
    
    = 1.0 =
    * Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.
    
    = 0.5 =
    
    * This version fixes a security related bug.  Upgrade immediately.
    
    == Resources ==
    * magnify.jpg © 2014 Jane Doe, CC0
    * supermenu.js © 2013-2015 James Today, MIT 
    

    Chime in and discuss!

     
    • NateWr 10:40 pm on April 29, 2015 Permalink | Log in to Reply

      It would be terrific if the specification encouraged (required?) dates for each release in the Changelog. A lot of plugins don’t include them, but it’s a great way to get a sense of a product’s maintenance record over time.

    • Justin Tadlock 11:03 pm on April 29, 2015 Permalink | Log in to Reply

      The only issue I see with a “License/Resources” section is if a theme author normally puts those licenses in a LICENSE file. I’d even argue that the license file should be the preferred method of adding license + copyright declarations. Nevertheless, I think it’s a good idea to account for it in the readme.txt standard format.

      It’s something to consider anyway.

      • Samuel Wood (Otto) 1:27 am on May 7, 2015 Permalink | Log in to Reply

        I agree, a separate license file is better. It can be an optional “other”section if you like though. Dunno. Licenses matter, but not enough to expose this to end users like that.

        • Chip Bennett 3:18 pm on May 7, 2015 Permalink | Log in to Reply

          I don’t agree that a separate license file is *better*. I don’t think either approach is better or worse than the other. If there are infrastructure/implementation reasons to favor one over the other, then I understand. Otherwise, I see it as a bikeshed question, and have no reason to argue strongly for one or the other.

          • usability.idealist 9:37 pm on May 15, 2015 Permalink | Log in to Reply

            A separate LICENSE file is BETTER, because it’s lessening the overall structocalypse. The user doesnt give a lot about what’s underneath, and in most cases, no developer will care much about the LICENSE of the resources, as long as they work.

            So, putting up to 30 different license items into the README file would clutter it up tremendiously.

            TL;DR: +1 for licenses listed in the file of the same name, to enforce structure and reduce clutter.

            cu, w0lf.

    • Justin Tadlock 11:10 pm on April 29, 2015 Permalink | Log in to Reply

      Some more ideas to ponder. Some things to consider dropping from the header:

      • Contributors – Is this useful with only one theme author allowed?
      • Tags – Already defined in style.css
      • Stable tag – Theme repo always uses latest version
      • License – Defined in style.css
      • License URI – Defined in style.css

      I also dislike the “Tested up to” header because it can give users a bad impression if you’re not updating your theme once every couple of months (most themes don’t need this much updating).

      • Ulrich 11:19 pm on April 29, 2015 Permalink | Log in to Reply

        Contributors may be possible sometime in the future. Otto said he has some similar code which he could use. https://meta.trac.wordpress.org/ticket/27

      • Tammie 9:38 am on April 30, 2015 Permalink | Log in to Reply

        I actually think contributors is important. I have in the past worked on a multiple authored theme that ended up with an account having to be made we all accessed – not awesome. We then still couldn’t credit everyone. It was a bit sad as a community project for BuddyPress.

      • Tammie 9:39 am on April 30, 2015 Permalink | Log in to Reply

        Tested up to is important from a ‘what does it work with’. I actually think you could say supported versions and be less dramatic.

        • Chip Bennett 3:26 pm on May 2, 2015 Permalink | Log in to Reply

          “Tested up to” and “Requires” are important in combination, and could be used very powerfully by the WP Admin, by hiding (or requiring a confirmation before installing) Themes that do not support the user’s current WordPress version.

          For example, I provide no intentional backward compatibility in my Theme. So, my “Requires” is almost always the same as, or perhaps one version prior to, the current WordPress version. So, if someone running an older version tries to install my Theme, the Admin could compare the user’s version (e.g. 3.9) to my Theme’s “Requires” and “Tested up to” (e.g. 4.0), and either not show my Theme, or display an “are you sure?” dialogue or something.

          • usability.idealist 9:50 pm on May 15, 2015 Permalink | Log in to Reply

            Maybe just a big fat notice.

            Hiding things is nasty (it’s basically censorship, but that’s another topic).
            Just take a look at Firefox Extension directory. LOTS of the stuff in there hasn’t been “updated” to work with current versions .. but about 70% of them do so.

            Now, Mozilla is hiding them from view, and you have to explicitely UN-select the automatically claimed FF version. Of corpse, you have to know that in the first place. So for un-experienced users, who just want to get their site roling quickly (and I’d say they’re making up the majority of the WP users), even such an option would be .. well, I’d guess most of them wouldn’t even recognize it.

            And: Although I’d consider myself a professional with the web and its UI shenannigans in general, but sometimes it still happens that I oversee this option, coursing and cruising WTF the extensions I wanted are not being displayed .. starting to fume again when finaily remembering that option.

            TL;DR: Annoying your users in the first place is not the best.

            So +1 for a big fat notice.

            -1 for a “click something” prompt. Thanks to Windows, the current “we use cookies, did you know” thingy and the recent data security apocalypse, most users are potty-trained to automatically click on the “okay” button.

            cu, w0lf.

      • Jose Castaneda 8:28 pm on April 30, 2015 Permalink | Log in to Reply

        • tags/license/license uri – I agree, a little redundant.
        • stable tag – I only consider this because there are some that link to a github repo
      • Chip Bennett 3:23 pm on May 2, 2015 Permalink | Log in to Reply

        I like “Tested up to”, but perhaps for Themes, we could keep it at major versions only. There is almost no reason for a Theme to break due to a point release.

        Plugins are potentially different, but for a Theme that properly differentiates between presentation and functionality, keeping “Tested up to” current for major releases should suffice.

    • Tomas Mackevicius 11:15 pm on April 29, 2015 Permalink | Log in to Reply

      Is it required to use format:

      == Resources ==

      or I could use:

      Resources
      =========

      ?

    • Tomas Mackevicius 11:18 pm on April 29, 2015 Permalink | Log in to Reply

      Also I used to think that Stable Tag was about WP version, but in this example it doesn’t look like.

    • Emil Uzelac 12:58 am on April 30, 2015 Permalink | Log in to Reply

      Contributors! Will that work?

    • Edward Caissie 1:10 am on April 30, 2015 Permalink | Log in to Reply

      As offered in Slack … I go with this currently (from my Opus Primus them):

      === Opus Primus readme.txt ===

      • Last revised April 28, 2015

      == Contents ==

      • Copyright
      • Licenses
      • Screenshots
      • Basic FAQ
      • Notes
      • Changelog
      • Review Tickets

      == Copyright ==
      Copyright (c) 2012-2015, Opus Primus

      This file is part of Opus Primus.

      Opus Primus is free software; you can redistribute it and/or modify it under the
      terms of the GNU General Public License version 2, as published by the Free
      Software Foundation.

      You may NOT assume that you can use any other version of the GPL.

      This program is distributed in the hope that it will be useful, but WITHOUT ANY
      WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
      PARTICULAR PURPOSE. See the GNU General Public License for more details.

      You should have received a copy of the GNU General Public License along with
      this program; if not, write to:

      Free Software Foundation, Inc.
      51 Franklin St, Fifth Floor
      Boston, MA 02110-1301 USA

      The license for this software can also likely be found here:
      http://www.gnu.org/licenses/gpl-2.0.html

      Note: All Opus Primus file Copyright years start with the first year of use and
      are amended with subsequent years based on theme publication regardless of any
      change or modification to the actual file.

      == Licenses ==
      All items are licensed under the GNU General Public License v2; or, as the case
      may be, individually noted below.

      • Normalize.css is a project by Nicolas Gallagher and Jonathan Neal. A minimized

      version is used. Licensed as Public Domain

      • Font: Merienda One

      Copyright (c) 2011, Eduardo Tunni (http://www.tipo.net.ar), with Reserved Font Name “Merienda”
      This Font Software is licensed under the SIL Open Font License, Version 1.1.
      This license is available with a FAQ at: http://scripts.sil.org/OFL

      • Font: Underwood Champion

      Copyright (c) 2009, Vic Fieger (http://www.vicfieger.com/)
      The Vic Fieger fonts are freeware, to be downloaded and used by anyone who wants them for free.
      This license can also be found at this permalink: http://www.fontsquirrel.com/license/Underwood-Champion

      • Theme Hook Alliance

      Licensed as GNU General Public License, v2 (or newer)
      The details of the copyright and license of this work may be found internal to
      the relevant files found under ..\stanzas\tha\ or at this website: https://github.com/zamoose/themehookalliance

      • SlickNav – Responsive Mobile Menu jQuery Plugin – Version 1.0.1

      Copyright (c) 2014, Josh Cope (http://slicknav.com)
      Opus Primus uses an adaptation of the plugin which is under a MIT License
      The details of the license can be found under ../js/SlickNav/MIT-LICENSE.txt
      Only the relevant files have been included, a complete download can be found at https://github.com/ComputerWolf/SlickNav

      • FitVids – built by Chris Coyier and Paravel – Version 1.1

      Copyright (c) 2013, Chris Coyier – http://css-tricks.com + Dave Rupert – http://daverupert.com
      Released under the WTFPL license – http://sam.zoy.org/wtfpl/
      Only the plugin file has been included, the complete project can be found at https://github.com/davatron5000/FitVids.js

      This above may not be construed as overriding any item with a previously written
      and applied license, stated or not, which will take precedence over anything
      written here.

      == Screenshots ==

      == Basic FAQ ==
      Q: I just updated to version 1.3, what could be causing these child-theme errors?
      With version 1.3 of Opus Primus the calls to the classes were changed from using
      `require_once` to `locate_template`. This then followed files being updated from
      calling the class global variable to creating a “new” class instance as needed.
      This is expected to provide better child-theme compatibility going forward and
      only be a one-time correction for existing child-themes.

      Q: What are Stanzas?
      Stanzas are meant to add additional functionality specifically to Opus Primus by
      either using specific Opus Primus assets, such as a particular font face; or, by
      hooking into specific action and/or filter hooks only found in Opus Primus.

      Q: What is the difference between how the “Featured Image” is used on a post and
      how it is used on a page?
      The “Featured Image” on a page is set to ideally be used as a “banner” on pages;
      and, to add emphasis for posts when they are viewed as part of a list, such as
      the index view or in archives.

      Q: How do the breadcrumb trails work?
      There are two different breadcrumb trails used in Opus Primus. One type is used
      on pages and shows the page hierarchy from the highest level to the lowest. The
      second trail is used on single views of posts and shows the first category and
      Post-Format of the post, both linked to their respective archive.

      Q: Where are the menu locations, and how are they used?
      There are three menu locations defined in Opus Primus.

      • The Primary Menu, located at the top of the page above the main content area.
      • The Secondary Menu, no location is set by default; the menu has been pre-

      defined for uses as the case may be, for example, page templates or Child-Themes

      • The Search Results Menu, located at the bottom of the content area when there

      are no search results returned, especially in the case of a “404” error be sent.

      Q: Is Opus Primus designed to be responsive to multiple screen sizes?
      In a word, no. Although the theme does include some minimal CSS specifically
      geared towards being responsive to multiple screen sizes the ideal method we
      recommend at this time is to take advantage of one of the many quality plugins
      available from the WordPress Extend Plugins repository to handle these requests.
      Please note, we intend to continue in our efforts to provide an inclusive method
      of managing these requests in future versions.

      Q: How do I modify an existing function from one of the classes?
      Most WordPress functions included with the theme will have their own filter,
      otherwise it would be recommended to extend the class and overload the theme
      function you are trying to modify.

      Q: How does Opus Primus automatically handle multiple column layouts?
      Through some CSS trickery and code logic Opus Primus will display by default
      one, two, or three columns depending on which sidebar widget areas are active.
      There are four(4) widget areas built into two sidebar areas.

      The following will show how, if active, they affect the layout:

      • Full Page (one-column): no active sidebar widget areas
      • Two-Column: widget areas active in only one sidebar area
      • Three-Column: at least one widget area active in each sidebar area

      Q: What happened to the LESS components of the theme?
      The LESS components of the theme were effectively removed at version 1.2 as a
      means to improve load time. The styles that were generated by the LESS script
      and related file were compiled and merged into the main theme stylesheet.

      == Notes ==
      1. $content_width is set based on how many columns being used and the common
      display size of 1024px * 768px.

      This being the case, the following widths will be used:

      • one-column: 990px
      • two-column: 700px
      • three-column: 450px

      2. Default Menu depth levels may be of concern in some cases. As it stands, the
      default menus are not restricted to any specific depth except the Search Results
      Menu which is restricted to a single level only when a custom menu is not used.

      3. Future revisions of the ‘theme-version-guidelines.txt’ file may not
      necessarily be recorded in the changelog. The “Theme Version Guidelines” page
      found at http://opusprimus.com/under-the-page/theme-version-guidelines/ will
      be considered the most current at all times. The version of the guidelines
      included with the theme will simply be a copy of the noted page.

      == Changelog ==
      === Opus Primus changelog.txt ===
      Last revised April 18, 2015
      Please note, the Opus Primus copyright can be found at the end of this file.

      = Version 1.4 =

      • Released …

      = Code =

      • Added `widgets` to the HTML5 theme supported items
      • Added `number_format_i18n` to better accommodate locale based values
      • Added two classes for use in rendering the comments link text displayed … or not
      • Added `Share the Author Wealth` method, not implemented as a display element, yet
      • Change all classes to a singleton style
      • Ensure `$pagination` has been initialized in `OpusPrimusNavigation::pagination` method
      • Moved the `support_comment` method back into the `OpusPrimusStructures` class
      • Moved the `before_comment_form` and `comments_form_closed` methods back into the `OpusPrimusComments` class
      • Refactored `OpusPrimusComments::comments_link` to use the WordPress core more effectively
      • Removed `$screen` parameter as not necessary in Taglines Stanza
      • Renamed file `class.OpusPrimusHeaders.php` to `class.OpusPrimusHeader.php` for consistency

      = CSS =

      • Added class definition to hide comment link text when comments are closed and there are no comments
      • Adjusted CSS to not reference `li` elements in default widget styles

      = Miscellaneous =

      • i18n: Added base `.po` file as well as English (Canadian) `.pomo` files
      • i18n: `null` does not need to be translated
      • i18n: Symbolic characters do not need to be translated
      • Added `opus_authors_list` filter hook
      • Continue removal of extraneous end of structure comments …

      /** ————————————————————————- */
      = Version 1.3.4 =

      • Released March 2015

      = Code =

      • Used a more specific element identifier for the SlickNav `prependTo` parameter

      = Miscellaneous =

      • Continue removal of extraneous end of structure comments …

      /** ————————————————————————- */
      = Version 1.3.3 =

      • Released March 2015
      • Added sanity checks to ensure there is actually an image in use when returning the featured image view.

      /** ————————————————————————- */
      = Version 1.3.2 =

      • Released March 2015
      • Added support for the `title` tag via `add_theme_support` function

      /** ————————————————————————- */
      = Version 1.3.1 =

      • Released March 2015

      = Code =

      • Added `get_the_posts_pagination` for navigation between pages of posts
      • Added `hide_category_widget_list_items` method and related hook
      • Added some escaping sanitization and linked Featured Image to post via the post ID
      • Changed method to return the Featured Thumbnail versus outputting it
      • Changed from using `get_the_time` to `date_i18n` for `OpusPrimusImages::exif_timestamp` method
      • Extracted code from `featured_thumbnail` method to create `featured_thumbnail_single_view` method
      • Improved look of navigation links in `OpusPrimusNavigation::multiple_pages_link` method

      = CSS =

      • Added `=== Screen Reader Text ===` section
      • Added `h5.comments-link` definition to provide a better aesthetic location
      • Added styling to navigation for moving within a single post’s pages
      • Incorporated WordPress recommended styles for `.screen-reader-text` class

      = Miscellaneous =

      • Added `opus_featured_thumbnail_single_view_portrait` filter hook and updated `hooks-filters.txt`
      • Begin removal of extraneous end of structure comments …
      • Inline documentation clean-up and re-organization
      • Updated `hooks-filters.txt` file

      /** ————————————————————————- */
      == Version 1.3 ==

      • Released November 2014

      = Code =

      • Added `post-title-link` wrapper class to better manage Post Title output
      • Added WordPress HTML5 markup support for search form, comment form, comment list, and caption
      • Added sanity checks to ensure constants are not already defined
      • Added `OpusPrimusRouter` class to replace path and URL CONSTANTS
      • Added Child-Theme “slug” for easier customizations
      • Added empty hooks before and after showing the breadcrumbs
      • Added OpusPrimusComments class methods to `functions.php` to work-around duplicate output issue
      • Added checks for Child-Theme and relevant references to `opus_primus_support_comment`
      • Better code organization to only load classes when needed
      • Changed post breadcrumb link to the WordPress shortlink
      • Create `/lib/` folder to store bundled libraries and ancillary files
      • Enqueue JavaScripts and CSS for SlickNav JavaScript plugin integration to handle mobile menus
      • Extracted the Opus Primus PullQuotes Stanza (see https://github.com/Cais/opus-primus-pullquotes)
      • Moved `support_comment` method to `functions.php` to eliminate duplicate output
      • Replaced the majority of `require_once` calls with `locate_template` calls
      • Replaced `global` variable calls with `new` class instances
      • Update to use `preg_match_all` in OpusPrimusGallery featured and secondary id methods

      = CSS =

      • Added new typography styles for better reading
      • Added styles for the “BNS Login” plugin
      • Added `clear: both` to `footer`
      • Added `width: auto;` for `th` and `td` elements
      • Added `#header-widgets` to the “Clearance” section of `opus-primus.css`
      • Added minor `attachment` related styles
      • Added better search form aesthetics in the sidebar
      • Change default `ul` list-style property to `none inside`
      • Hide the post/page breadcrumbs in mobile displays
      • Hide “Search” button for search form
      • Removed duplicate definitions from media queries stylesheet
      • Removed unused `div#top-navigation-menu` definition
      • Removed unused `nav div.nav ul li` definition
      • Updated `editor-style.css` to match new typography of theme
      • Updated galleries styles to use HTML5 markup
      • Updated font-size of excerpt more link symbol to 35px from 200%

      = JavaScript =

      = Miscellaneous

      • Added Contact Form 7 compatibility
      • Added BNS Login compatibility to use `dashicons` display
      • Added Gravity Forms compatibility (for reCaptcha form)
      • Added to `readme.txt` FAQ “I just updated to version 1.3, what could be causing these child-theme errors?”
      • Removed `works-in-progress` folder from theme
      • Updated `readme.txt` to note the use and license of SlickNav by Josh Cope
      • Updated `readme.txt` to note the use and license of FitVids by Chris Coyier and Paravel
      • Updated `readme.txt` to remove FAQ item related to blank menu items; resolved in WordPress core trac ticket #23254
      • Updated `style.css` description to emphasize the addition of the SlickNav and FitVids libraries
      • Updated `screenshot.png` to better reflect latest release
      • Updated `hooks-actions.txt` with new additions

      /** ————————————————————————- */
      == Version 1.2.5 ==

      • Released July 2014

      = Code =

      • Added new method `OpusPrimusNavigation::pagination` for moving between pages of posts
      • Added new method `OpusPrimusNavigation::pagination_wrapped` to provide actions hooks before and after the `pagination` method
      • Added `antispambot` email protection to author biography email addresses
      • Added sanity checks to ensure widgets are active before rendering sidebars
      • Added `opus_primus_defaults.php` to replace `$opus_defaults` class
      • Added `opus-primus-ignite.php` to reduce clutter in `functions.php`
      • Added `opus_image_link_navigation_output` filter hook to provide access to navigation output
      • Added `opus_tagline` to default hidden screen options array
      • Adjusted the `OpusPrimusStructures::the_loop` and `OpusPrimusStructures::the_loop_archives` to use the `pagination_wrapped` method
      • Changed navigation method from `posts_link` to `pagination`
      • Changed single view first year of copyright to published year of post/page in `OpusPrimusStructures::copyright` method
      • Deprecated `OpusPrimusDefaults` class (file may be removed in a future release)
      • Enqueue custom stylesheet in an update safe location `/wp-content/opus-primus-customs/`
      • Enqueue custom JavaScript in an update safe location `/wp-content/opus-primus-customs/`
      • Refactored all defaults using true/false to use filtered define statements
      • Refactored `OpusPrimusTaglines::tagline_create_boxes` to clarify the parameter usage
      • Remove conditional customization enqueue using internal theme folder
      • Renamed `opus-ignite.php` to `opus-primus-ignite.php` and moved to theme root
      • Renamed `OpusPrimusNavigation::image_nav` to `OpusPrimusNavigation::image_link_navigation`
      • Replaced `OpusPrimusStructures::replace_spaces` with `sanitize_html_class`
      • Set Customization path and URL CONSTANTS

      = CSS =

      • Added `Navigation` section and `Pagination Method` sub-section
      • Complete refactoring of the `@media` query styles for better responsiveness
      • Corrected `select` element to use “max-width” rather than “width”
      • Fixed white space on right side of iPhone displays
      • Minor adjustments to `img` tag related items
      • Monster be gone!? – addressed special case many level menu in sidebar

      = Miscellaneous =

      • Updated `hooks-filter.txt` documentation to note eight (8) new filters
      • Updated `hooks-actions.txt` documentation to note two (2) new actions
      • Updated `screenshot.png` to show a bit more of the theme display

      /** ————————————————————————- */
      == Version 1.2.4 ==

      • Released May 2014

      = Code =

      • Added sanity check to only display comments_link when not in single view or in an archive view
      • Added Featured Image Thumbnails to post-format single and archive view templates (except Post-Formats: Image and Gallery)
      • Added `opus_primus_theme_version()` call as an accessible text string
      • Added new default `number_of_secondary_images` method under Gallery parameters
      • Bring the Featured Image Thumbnail back into the index view … can you say “waffle”?
      • Change `$output = null` to `$output = ”` in `OpusPrimusPosts::sticky_flag` method
      • Corrected typo in `’opus_links_pages_after’` hook
      • Corrected modified date/time output to account for scheduled posts being modified earlier than they are posted
      • Refactored conditional comments and featured thumbnail checks into the `comments_link` and `show_featured_thumbnail` methods
      • Removed `extract` function, escaped attributes, and refactored conditional checks in PullQuotes Stanza
      • Use `opus_primus_theme_version` in place of `wp_get_theme` calls
      • Use transients to improve performance impact of the `OpusPrimusStructures::copyright` method

      = CSS =

      • Added Format-Aside Dashicons to Post-Format: Aside posts
      • Added Flag Dashicons to Sticky Posts
      • Changed Password Protected Dashicons to use the Lock
      • Separated the Tagline output class into two different classes
      • Updated normalize.css to 3.0.1 (copy and pasted from git.io/normalize)

      = Miscellaneous =

      • Added filter `opus_primus_theme_version_text`
      • Change text domain to match theme slug
      • Updated `hooks-actions.txt`
      • Updated `hooks-filters.txt` (corrected reference to `opus_first_author_details_text`)
      • Updated Opus Primus PullQuotes `readme.txt`

      /** ————————————————————————- */
      == Version 1.2.3 ==

      • Released February 2014

      = Code =

      • Added more tests
      • Added Featured Image thumbnail to standard post-format archive views
      • Moved `featured_image` wrapper into OpusPrimusGallery::featured_image method
      • Moved `secondary_images` wrapper into OpusPrimusGallery::secondary_images method
      • Moved the ellipsis out of the read more link
      • Refactored `$output` to use `button` class versus the button element in meta byline flags
      • Removed unused parameter `$more` from `OpusPrimusPosts::excerpt_more_link` method
      • Removed `$sep_location` parameter as it was not used in `browser_title` method
      • Removed Featured Image thumbnail from index view
      • Renamed `OpusPrimusDefaults` methods from `show_*` to `display_*`
      • Set `display_page_byline` to true as theme author aesthetic choice

      = CSS =

      • Added post coda post format classes
      • Added `dashicons` dependency to main `Opus-Primus` stylesheet
      • Added `button` class to replace the button element styles
      • Change to only append to the `cite` tag when it is inside the `blockquote` tag
      • Center align Calendar Day table header cells
      • Fixed really long Post Titles and Words not wrapping as expected
      • General clean-up and removal of excess/over-writing properties
      • Prepended Post Byline with matching Post-Format dashicons
      • Re-Adjust `ul.nav-menu` and `.nav-menu` to `z-index: 3` for main menu
      • Reduced the citation font-size for better aesthetics

      = JavaScript =

      • Re-format code structures
      • Removed `table-stripe` class from specific Calendar elements

      = Miscellaneous =

      • Updated tags used in `style.css` header block to include responsive-layout and fluid-layout
      • Updated `readme.txt` to note existence and location of `changelog.txt`
      • Updated `readme.txt` copyright notice to clarify copyright years used by individual files.
      • Updated Required WordPress version to 3.8 for `dashicons` dependency

      /** ————————————————————————- */
      == Version 1.2.2 ==

      • Released October 2013

      = Code =

      • Added conditional test rather than print both breadcrumbs (one empty)
      • Additional i18n code corrections and enhancements
      • Corrected i18n code for EXIF data
      • Extracted $post_title management from `post_breadcrumb` method into the `breadcrumb_post_title` method
      • Fixed issue with Gallery Post-Format being used when the `gallery` shortcode is not used.
      • Fixed undefined offset when there is no image found in post
      • Reformatted to be closer to (modified) WordPress Coding Standards – see https://gist.github.com/Cais/8023722

      = CSS =

      • Reduced all menu related elements with `z-index` property to a value of 1
      • Removed `z-index` property from breadcrumb related elements
      • Set the breadcrumbs background color to `#ffffff` (white)

      = Miscellaneous

      • Add documentation to the `first_linked_image` function
      • Removed `table-stripe` class from Post-Format: Image tables
      • Tested up to WordPress version 3.7

      /** ————————————————————————- */
      == Version 1.2.1 ==

      • Released August 2013
      • Removed `translation-ready` tag

      /** ————————————————————————- */
      == Version 1.2 ==

      • Released August 2013

      = Code =

      • Added display of featured image centered at full size in single standard post format view
      • Added full `featured_image` method call to single view of post formats audio, chat, quote, and status
      • Added `get_author_description` method in Authors class
      • Added filtered `comment_form_required_field_glyph` method in Comments class
      • Added many new filters – see http://opusprimus.com/under-the-page/hooks-filters/ or `hooks-filters.txt` for a current list
      • Added sanity conditional check to eliminate potential duplicate body classes
      • Added `is_single` conditional test before enqueue of Comment Tabs script
      • Added post to post navigation in single view
      • Added conditional check if not post password required when displaying comments
      • Added conditional for showing the page byline details
      • Added `display_page_byline` default and set as false
      • Changed `the_post_thumbnail` to use parameters which are set in the call to `OpusPrimusImage::featured_image`
      • Changed post thumbnail on pages to full size image and align to the center
      • Changed comment fields into an unordered list
      • Changed `meta-tags` container from `p` to `div` (adjusted CSS as needed)
      • Changed `opus_post_byline_details` filter to `opus_post_byline_phrase`
      • Check for long post titles in breadcrumbs and trim as needed
      • Display comment count in meta details if comments exist and comments are closed
      • Fixed call to wrong post navigation function in single view
      • Merge `opus-ignite.php` into `functions.php`
      • Moved `featured_image` method call into `is_single` conditional in post-format loops
      • Removed `featured_image` method call from post-formats link and video loops
      • Removed global `$opus_image_meta`; replaced with call to `exif_data` method
      • Removed `style.less` related function and action calls
      • Removed `restore_image_title`

      = CSS =

      • Added styles for comment form fields
      • Added more specific selector used with `.post.format-link`
      • Added more BNS Plugin Integration (BPI) adjustments
      • Added styles from compiled `style.less` file (file removed)
      • Added `img` elements for captioned images and `wp-smiley` images
      • Address both class and id usage for the sidebar search form
      • Adjusted widths of comment form elements
      • Adjusted CSS to better handle large images with captions in large full-width displays
      • Adjusted `table` elements from `max-width: 100%` to `width: 100%` and other minor changes
      • Minor tweaks and adjustments
      • Sorted out the adaptive layout for screens less than 480px wide

      = JavaScript =

      • Added more specific selector used with `.post.format-link` when adding `.link-symbol` class
      • Added script to create class to display tables with striped rows
      • Removed LESS JavaScript library

      = Stanzas =

      • PullQuotes – Added `pullquotes-readme.txt` file
      • PullQuotes – Added left-side placement with new `to` parameter
      • Taglines – Added `taglines-readme.txt` file
      • THA – Added `tha-readme.txt` file

      = Miscellaneous =

      • Documentation Updates
      • Minor changes to text tense used in `changelog.txt`
      • Removed `style.less` file (compiled and merged into `opus-primus.css` file)
      • Removed license references related to LESS as all components were removed
      • Updated `hooks-actions.txt`
      • Updated `hooks-filters.txt`
      • Updated `readme.txt` FAQ – What is the difference between how the “Featured Image” is used on a post and how it is used on a page?
      • Updated `readme.txt` FAQ – What are Stanzas?
      • Updated `readme.txt` FAQ – What happened to the LESS components of the theme?

      /** ————————————————————————- */
      == Version 1.1.1 ==

      • Released March 2013

      = Code =

      • Added `all_comments_count` and `show_all_comments_count` methods to Comments class to be used in the ‘comments.php’ template when displaying total comments
      • General minor code refactorings and improvements
      • Moved `comments only tab`, `pingbacks only tab` and `trackbacks only tab` functionality into Comments class methods
      • Moved `comments only panel`, `pingbacks only panel` and `trackbacks only panel` functionality into Comments class methods

      = CSS =

      • Added rounded corners for the comment type tabs and the comments panel
      • Added `#d3d3d3` color as default tab background color; active is transparent
      • Removed unused element for non-existent ‘comments-toggle’ script

      = Miscellaneous =

      • Remove $content_width set values from Structures class method `layout_open` and set in ‘functions.php’
      • Updated ‘hooks-actions.txt’

      /** ————————————————————————- */
      == Version 1.1 ==

      • Released March 2013

      = Code =

      • Added `excerpt_more_link` and attached to `excerpt_more` filter
      • Added `anchor_title_text` for use with `excerpt_more_link` and permalink in the post meta details
      • Added additional list wrapper around each comment type
      • Added Breadcrumbs trails to pages and posts
      • Added Comment Tabs for each type (Comment, Pingback, and Trackback)
      • Created and enqueued ‘opus-primus-comment-tabs.js’
      • Created Header class
      • Dropped `restore_image_title` filter hook into `media_send_to_editor` as potentially blocking insertion of media
      • Fixed comments (only) count output
      • Limit width generated by “Full Size Video” JavaScript to a maximum of 1000px
      • Refactored Structures class to put `site_title`, `site_description`, and `custom_header_image` into Header class
      • Refactored `opus-primus-header` to reflect class/method changes of Structures and Header

      = CSS =

      • Added classes to `h2`, `ul`, and `li` elements in `OpusPrimusAuthors::author_details`
      • Add minor comments styles
      • Centered content of Post Format: Video posts.

      = Miscellaneous =

      • Removed unused style sheet ‘opus-primus-responsive-layout.css’

      /** ————————————————————————- */
      == Version 1.0.4 ==

      • Released March 2013

      = Code =

      • Added ‘Breadcrumbs’ class
      • Fixed problem with wrong loop method call in ‘archive.php’
      • Moved `breadcrumbs` method from ‘Structures’ class to ‘Breadcrumbs’ class
      • Removed `hgroup` container from ‘opus-primus-header’

      = CSS =

      • Added Breadcrumbs section
      • Code formatting

      /** ————————————————————————- */
      == Version 1.0.3 ==

      • Released February 2013

      = Code =

      • Changed the MetaBoxes class to TagLines
      • Moved TagLines into its own Stanza as another example of the theme extensibility
      • Added `breadcrumbs` method to Structures as a precursor to new features in version 1.1

      /** ————————————————————————- */
      == Version 1.0.2 ==

      • Released February 2013

      = Code =

      • Fixed ‘search’ template bug when a page is returned in the results

      = CSS =

      • Started “BNS Plugin Integrations” (aka BPI) – BNS Inline Asides

      /** ————————————————————————- */
      == Version 1.0.1 ==

      • Released February 2013

      = Code =

      • Added ‘opus_footer_after’ action hook
      • Change classes in ‘404.php’ from using underscores to using hyphens
      • Created new methods `the_loop_wrapped` and `the_loop_archives_wrapped`
      • Modified action hooks to more semantic naming convention: `opus_
        _`
      • Moved ‘opus_body_bottom’ action hook to immediately before closing body tag
      • Replaced `the_loop` method and surrounding code with `the_loop_wrapped`
      • Replaced `the_loop_archives` method and surrounding code with `the_loop_archives_wrapped`
      • Wrapped ‘opus_modified_post_after’ action hook in conditional making it consistent with ‘opus_modified_post_before’

      = CSS =

      • Centered top level menu items only – better aesthetics with short page titles
      • Added `clear: both;` to ‘img.aligncenter, img.center’ to address Firefox issue when when a Featured Image and a large in post image are too close together.
      • Added post coda post format classes
      • Fixed really long Post Titles and Words not wrapping as expected

      = Miscellaneous =

      /** ————————————————————————- */
      == Version 1.0 ==

      • Initial release – February 2013

      == Review Tickets ==

      —-

      I based the overall layout on the premises put forward in plugin readme files with a couple of optional items such as the expanded licenses section and a list of all past trac tickets for the theme.

      I’d be agreeable to adding a header section of sorts (along the lines of the OP example), obviously inserted before my “Copyright” section as noted in the readme contents area.

      Excuse the excessive length but linking to the file really doesn’t give the same impact of what a readme.txt file could look like after several versions if/when the changelog is added into it.

      • Daedalon 5:21 pm on May 6, 2015 Permalink | Log in to Reply

        I’d be all for showcasing only a few items of each type in similar future comments, just as many as is enough to illustrate the approach, with the optional link to the full file for those who want to dive deeper.

    • Tammie 9:42 am on April 30, 2015 Permalink | Log in to Reply

      This is what we do at Automattic and to me feels the right format: https://themes.trac.wordpress.org/browser/resonar/1.0.3/readme.txt.

      A few points:

      • Tags are great to have in one place here too. It means you end up with one doc that has all the essential information. Easier to parse and easier for users.
      • The change I’d probably make is tested up to. I’d probably say supported.
      • Credits could be resources, I don’t mind what you call it.
    • Dion Hulse 12:55 am on May 4, 2015 Permalink | Log in to Reply

      I’d suggest dropping the ‘Tested Up to’ or ‘Supported’ fields, but retaining the ‘Requires’.

      My reasoning is:

      • Themes often keep working (and don’t become obsolete like plugins), there’s no good reason for a theme to break with a WP upgrade
      • Updating that metadata will require a new theme release, plugins can just make a quick unreviewed commit, themes are not that simple
      • The fields haven’t really been great in the plugin directory IMHO, Lots of things continue working, but people avoid them as the theme isn’t specifically marked as supported (or you get support requests every month asking “Does this work with 4.2? I don’t think it does because it’s not listed as such”
      • If a theme isn’t compatible with a new version of WordPress, or fatals/etc, it should be pulled from the listing, so “tested up to” should really be inferred as being the latest version

      I understand that many theme authors who release a new update every month and constantly update the theme to be up to date with WordPress’s features, would love a Tested field to make them stand out from the crowd, but it feels like it’ll just be at a detriment to other not-as-frequently-updated themes which are not necessarily of lesser quality and ultimately provide little benefit to an end-user.

      As for other comments about keeping the fields to major releases only, +1, but that kind of happens for plugins already, we have an internal list in the APIs that says “4.1 compatible means 4.1.1 & 4.1.2 too”, there’s never been a requirement nor need to update it to “Tested up to 4.1.2″ if you had it listed as 4.1.

      • Chip Bennett 7:32 pm on May 4, 2015 Permalink | Log in to Reply

        If a theme isn’t compatible with a new version of WordPress, or fatals/etc, it should be pulled from the listing, so “tested up to” should really be inferred as being the latest version

        How would Themes be “pulled from the listing” without some way of knowing that it isn’t compatible with the current version of core? The best we can hope to do, currently, is hide from the listing any Theme that hasn’t been updated in the past X period of time (currently two years, IIRC).

        The biggest roadblock, as you mentioned, is the need for a simple compat-verification documentation (e.g. “Tested up to” in the readme) to go through the entire review process – though updates for approved Themes happen almost immediately.

        Perhaps we need some mechanism for Theme developers to update readme.txt in the Theme repo directly?

        • Justin Tadlock 11:11 pm on May 4, 2015 Permalink | Log in to Reply

          One thing I’ve always wanted to see was a simple select box on the WordPress.org site itself for theme/plugin authors to say that something is compatible. The readme file is a poor way of handling this to me.

        • Dion Hulse 11:37 pm on May 4, 2015 Permalink | Log in to Reply

          How would Themes be “pulled from the listing” without some way of knowing that it isn’t compatible with the current version of core?

          Having a readme line, checkbox, widget, or whatever that says “Hey, my theme is still compatible with WordPress” is silly, that was my whole point.
          Themes remain compatible with WordPress (although not always with the TRT guidelines) for long enough that having to proactively update something seems a waste of time for all involved.

          How often do you see a theme that is no longer compatible with WordPress? When that number becomes more than a handful a year, maybe we could consider a compatibility widget for themes (like we have for plugins)..

          Otherwise, I’d just prefer to see proactive removals when someone knows somethings wrong with it – “Hey this theme no longer works, can someone suspend it for me?” or “Hey, this theme isn’t compatible with 4.5, can someone suspend it until I’ve got time to fix it next month?”

          For reference – I already suspend themes from the directory when I see them start to cause fatals on wp-themes.com, the WordPress.org devs get notified about them – It’s rare, but there’s been a few recently that were from 2008. I always shoot the author a friendly email to let them know though.

          Perhaps we need some mechanism for Theme developers to update readme.txt in the Theme repo directly?

          I’d also say that’s not needed, if the tested-up-to version is the only thing that would require it.. it oughta just be dropped.

          • Chip Bennett 12:26 pm on May 5, 2015 Permalink | Log in to Reply

            Having a readme line, checkbox, widget, or whatever that says “Hey, my theme is still compatible with WordPress” is silly, that was my whole point.

            You’re right. This is a pretty big “win” for the Themes directory, and we should recognize it as such. Sometimes I forget just how far we’ve come in just a few short years.

            The biggest potential issue is functions being newly deprecated in a new version of core – but even that will almost never cause breakage.

            I do think that Theme developers will complain (and rightly so, given the user perception that “recently updated” == “better”) if they are unable to highlight that they have tested/verified their Theme against the latest version of core. It is also seen as a sign of a Theme being actively updated/supported by the developer. So, I do think there’s some value in that information.

            I like Justin’s idea, though – provide some way for the developer to indicate core support in the Admin area of the Theme’s listing on the directory. A simple checkbox or dropdown select would probably suffice.

    • Emil Uzelac 8:24 pm on May 10, 2015 Permalink | Log in to Reply

      @jcastaneda just noticed == Resources == in your original post, while it should be == Credits == instead :)

    • Tomas Mackevicius 4:44 pm on May 19, 2015 Permalink | Log in to Reply

      Is it possible to get validator like there is one for plugin readme:

      https://wordpress.org/plugins/about/validator/

  • Tammie 7:25 pm on April 28, 2015 Permalink |  

    Meeting notes

    We had a meeting today, archive here:
    https://wordpress.slack.com/archives/themereview/p1430243960008321

    Accessibility reviews

    We talked about these and getting a training plan. @joedolson and @davidakennedy are going to be working on a doing_it_accessible_wrong theme and some screencasts. People will work through these and we can have a baseline then for them to pass before move onto trac. This should be done within 2 weeks. We plan to get the first batch of people trained up inside a month. They are going to report back in 2 weeks.

    Changelogs

    Having in readme.txt seems to make sense and is the consensus from the thread. @jcastaneda will be looking into how we start doing that and then report back next week on make.blog.

     
    • gsayed786 7:29 pm on April 29, 2015 Permalink | Log in to Reply

      Hi,
      Need some help from you !
      I had submitted my theme on wordpress for review ..however because of the natural disaster in nepal the reviewer cannot continue with the review and has asked me to contact admin to assign my theme to another person for review ..Can you help me how to contact admin regarding this .
      Thanks
      Ghafir

    • Ulrich 12:50 pm on May 1, 2015 Permalink | Log in to Reply

      Can we discuss in the next meeting how we can reduce the number of tickets that need a new reviewer?

      Here are some ideas to get use started.

      • Add popup to confirm to review a theme. Related https://meta.trac.wordpress.org/ticket/960
      • Improve the initial email when assigned a ticket with further information. Like what the requirements are and what the workflow is.
      • Automatic reminders after 4 days. I believe some people forget that they have requested a theme to review.
  • Tammie 7:29 pm on April 27, 2015 Permalink |  

    This week’s meeting agenda

    This week we will be talking about Accessibility reviews. How can we come up with a training method for people to become fully fledged accessibility reviewers? We have a few things to consider:

    • A hangout that is recorded to use for training foundation.
    • Scaling, mentoring doesn’t scale that well and we only have handful trained so far. How do we deal with early training?
    • List of people wanting to be trained. Who is interested? I’d advise as many admins and key reviewers as we can should be trained at least in basics.
    • A plan, a process.

    We will also have space to deal with the changelog discussion.

     
    • Justin Tadlock 7:53 pm on April 27, 2015 Permalink | Log in to Reply

      I could probably do accessibility reviews myself. It’s just been one of those things I’ve avoided jumping into because of time constraints. I know our only two reviewers for this would welcome some help though.

    • Joe Dolson 7:56 pm on April 27, 2015 Permalink | Log in to Reply

      Any help would be fabulous – but I certainly know well that we’ve all got time constraints.

    • Sami Keijonen 8:29 pm on April 27, 2015 Permalink | Log in to Reply

      I’m very interested to get trained for this. I’m not even a theme reviewer yet but if I quit my day job in couple of months I have more time starting reviews. At least I have confidence I can do it:)

      I’ll understand if this is only for admins and key reviewers.

      • Tammie 8:33 pm on April 27, 2015 Permalink | Log in to Reply

        This isn’t just for admins and key reviewers. I would like to think all of those could be trained and also any reviewers that want.

        I think ideally we’d have you reviewing normally first. But there is nothing to say that can’t happen whilst we work out the training. Come along and I’m sure we can work something out.

      • Jose Castaneda 9:16 pm on April 27, 2015 Permalink | Log in to Reply

        Always open to those that want to learn! :)

    • irenem 2:51 am on April 28, 2015 Permalink | Log in to Reply

      I want to learn. Sign me up ☺

    • Sharon Austin 11:44 am on April 28, 2015 Permalink | Log in to Reply

      Hi Tammie you may want to consider some insights from a conversation at Accessibility Innovators. It’s specific to ARIA concerns, but I think it speaks to the wider problem of teaching accessibility.

      This is the article:

      For educators: How to create a curriculum for teaching ARIA; differentiating between content authors and developers

      Link to article For Educators by Bryan G.

  • Jose Castaneda 9:03 pm on April 26, 2015 Permalink |  

    Changelog proposal 

    Recently I mentioned that we need to have a standard changelog format. Not only does this benefit us as reviewers but it also benefits the users because it lets them know what has changed. This is important if a theme update has a security fix or it makes drastic changes. Users can then decide if the update is worth it for them or not. Plugins provide them and I feel themes should as well. We have tried to recommend this in the past but it hasn’t stuck.

    There are currently two tickets that should be watched. The first one is the meta ticket. It is a little outdated because the tabbed theme browser no longer exists but can be easily amended to include a link to the changelog file.

    Meta ticket:
    https://meta.trac.wordpress.org/ticket/45

    The second ticket being the core one. This is what the user will see when they are on the update screen on the Appearance screen.

    Core ticket:
    https://core.trac.wordpress.org/ticket/22810

    If we want to make this happen, ideally we should be following the core development release cycle. As you can see 4.3 is scheduled release around August and 4.4 in December.

    Core Development Roadmap:
    4.3 – August
    4.4 – December

    What does this mean? It means in order for this to happen we have to require a changelog or a section in the readme file with a changelog and we have to set a timeframe. We would also need to have a standardized format that theme authors can easily and quickly adhere to. What I’d like to propose is requiring a dedicated changelog file that follows the format of:

    changelog.txt
    == changelog ==
    = 0.3.1 =
    * Added Dutch, French translations
    * Fixed nav menu not displaying in mobile devices
    
    = 0.3.0 =
    * Fixed PHP error in some hosting environments
    

    Let’s discuss!

     
    • Scott Smith 9:06 pm on April 26, 2015 Permalink | Log in to Reply

      I would prefer that Changelog.md files become the standard. They provide nice formatting option to make change logs more readable and render well on sites like GitHub.

    • usability.idealist 9:10 pm on April 26, 2015 Permalink | Log in to Reply

      So, basic Markdown format, right?

      Would be nice to mention that in the post, thou 😉

      cu, w0lf.

    • Emil Uzelac 9:10 pm on April 26, 2015 Permalink | Log in to Reply

      While I practice this in every project and believe that we should include one, I don’t think that this would be beneficial for reviewers simply because we use diff.

      • Ulrich 9:13 pm on April 26, 2015 Permalink | Log in to Reply

        @emiluzelac I find the changelog helpful to understand what changes the theme author has done when looking at the diff. It gives just a bit more information.

        • Emil Uzelac 9:17 pm on April 26, 2015 Permalink | Log in to Reply

          If this would be used like what plugins have yes, people can see the changes before they update, other than that reviewer must be able to read the difference and understand them.

      • Jose Castaneda 9:14 pm on April 26, 2015 Permalink | Log in to Reply

        It gives just a bit more information.

        I feel the same way. :)

      • Chip Bennett 12:15 am on April 27, 2015 Permalink | Log in to Reply

        Personally, I find change logs to be incredibly helpful, even when using a .diff. The changelog is the human-readable summary of changes, that can really help grok the diff changes.

    • Ulrich 9:11 pm on April 26, 2015 Permalink | Log in to Reply

      This is a great Idea. We can also take some inspiration from. http://keepachangelog.com/

      One thing that is missing that I find important is the date when the update is released.

    • Gary Jones 9:19 pm on April 26, 2015 Permalink | Log in to Reply

      Historically, change log files are named with capitals: CHANGELOG, so that it moves to the top of the file list in case-sensitive systems and at least stands out amongst other files, so CHANGELOG.md would be my suggestion.

      Like Ulrich, I’m also +1 for keepachangelog.com. I personally think the subsections within a release (changes split into Added, Deprecated etc.) are over the top as most themes probably only have a few changes per release, but the overall approach of versions, with dates (ISO 8601 format) and the other things it mentions is a good approach for all theme (and plugin) projects.

    • Justin Tadlock 9:49 pm on April 26, 2015 Permalink | Log in to Reply

      Honestly, I don’t see change logs as all that important from a user standpoint. While I don’t have any official stats, I’d wager that the vast majority of users don’t read change logs and, of those who do happen upon one, don’t understand most of what’s actually in the file.

      Change logs are, by and large, a developer tool. It’s a nice-to-have feature. I don’t care one way or another. I never read them. I doubt we’ll get great change logs from the majority of theme authors. We can’t even manage to get some semantic versioning down or basic inline PHP docs. We’ll probably see a lot of Git commit logs copied/pasted or my personal favorite, “Changed a bunch of stuff. Too busy building awesome s*** to care about tracking changes”. :) Meh.

      If we did go with a standard, I’d love to see it handled as changelog.md (I hate all caps). At least follow http://keepachangelog.com/

    • Andrew Nacin 9:54 pm on April 26, 2015 Permalink | Log in to Reply

      Plugin readmes already have this — is there any reason not to follow the existing pattern in the community?

    • Chip Bennett 12:18 am on April 27, 2015 Permalink | Log in to Reply

      I would only be in favor of *requiring* a standard-format change log if it were integrated into core, such that the change log information could be exposed to the end user via the admin. Otherwise, the change log is really only useful to reviewers/developers – and I am not generally in favor of making requirements that serve no purpose to the end user.

    • Edward Caissie 1:22 am on April 27, 2015 Permalink | Log in to Reply

      I’ve been using a changlelog.txt file based on the plugin readme.txt file from almost day one of my theming endeavors. I even used the plugin readme validator as a quick check for my markdown in the theme’s changelog as well. I really don’t see any reason to re-invent the wheel more than adopting the plugin’s current readme framework for a changelog as is …

      My general layout follows along these lines (taken directly from my oldest theme):

      ----
      
      === Desk Mess Mirrored ===
      Changelog: April 15, 2015
      == Version 2.4 ==
      = Code =
      
      • i18n updates to better enable translations
      • Minor code clean-up
      = Miscellaneous =
      • Update copyright year and tested up to version
      /** ------------------------------------------------------------------------- */ == Version 2.3 == = Code =
      • Added BNS Login "Compatibility Code" to use dashicons instead of text
      • Dropped backward compatibility for `wp_title` with Desk Mess Mirrored Child-Themes based on version 2.1 and earlier
      • Removed `wp_list_bookmarks` section from `sidebar.php` template
      • Wrap `register_sidebar` calls in a function that is used as a callback for the `widgets_init` hook
      • Take into account what happens on the 404 page when returning no posts
      = CSS =
      • Aligned previous month text in default calendar widget to left
      • Stop Gravity Forms reCaptcha iframe from creating a blank area in the footer
      • Fixed mixed list bullets
      • Minor layout adjustments for widget items
      = Miscellaneous =
      • Code reformatting to better meet current WordPress Coding Standards
      • Adjusted screenshot size to be 880x660 pixels
      /** ------------------------------------------------------------------------- */ == Version 2.2.4/2.2.4.1 == = Code =
      • Added `dmm_post_meta_link_edit()` function with filter hooks for DRY purposes
      • Removed call to `function_exists( 'dynamic_sidebar' )` as required WordPress version precludes its necessity
      = CSS = ...

      (Don't mind the make site's interpreting of my markdown, I just copied and pasted it right out of my theme's changelog.txt file.)

      • Emil Uzelac 2:31 am on April 27, 2015 Permalink | Log in to Reply

        Nice! Check out one of the earliest releases of Responsive: https://themes.svn.wordpress.org/responsive/1.3.0/changelog.txt

        Changelog Legend:
        
        [+] = Added
        [-] = Removed
        [^] = Moved
        [=] = No Changes
        [x] = Deleted
        [!] = Bugs
        
        (03/15/2012) - Version 1.3.0
        [!] Prefix inconstancy for comment reply function
        [+] wp_enqueue_scripts instead of wp_print_scripts
        [+] wp_enqueue_style for Google Fonts replaced with a static link
        [+] translation function in:
            - comments.php
        	- functions.php
        	- home.php
        	- sidebar-home.php
        	- sidebar-gallery.php
        	- single.php
        	- search.php
        [+] wp_filter_post_kses changed to esc_url_raw in theme-options.php
        [+] CTA references changed to Call to Action followed 
            by option renaming for the same in theme-option.php
        	and home.php
        [+] class for home #widgets
        [^] titles just after #widgets
        [^] widget-title-home h3 in .widget-title
        [x] widget-title-home h3 a
        [*] read more
        [-] gallery-meta
        [+] CSS source formatting
        [+] social-icons center align for responsive layout
        [-] post thumbnail CSS
        [+] See more to Read more in all files
        [+] global $more; $more = 0; for pages with _excerpt
        
        (03/12/2012)
        Initial Release
        

    • Samuel Wood (Otto) 2:41 am on April 27, 2015 Permalink | Log in to Reply

      Forget separate changelog files. If we move in any direction, it will be along the same lines as plugins, with the readme.txt route. That’s the way forward. Stick to that.

      If you want to be future proof: Use the same format as readme.txt files that plugins have. That will be the first implementation that we use. Nothing else.

      • Emil Uzelac 3:02 am on April 27, 2015 Permalink | Log in to Reply

      • Emil Uzelac 3:37 am on April 27, 2015 Permalink | Log in to Reply

        So Otto, what do you propose we do?

      • Gary Jones 8:52 am on April 27, 2015 Permalink | Log in to Reply

        > Forget separate changelog files.

        Why? The change log file would be changing on every release, while the readme may not. A readme that gives some information to users about how to install, doesn’t need to be 5 times the length with a bulk load of historical changes that they may not care about. Keeping it in a separate file means those who do care, can more easily find it and the readme history isn’t unnecessarily adorned with a list of changes.

      • Chip Bennett 2:06 pm on April 27, 2015 Permalink | Log in to Reply

        This is one time I’m definitely happy to have clear direction handed down from “above our pay grade”.

      • Tammie 3:47 pm on April 27, 2015 Permalink | Log in to Reply

        I actually think seperate logs is better from a user view and from a reading. But, I do think we need one way for both plugins and themes. If there is a plugin way set then we should be following that. Just requiring that a log is there would be a good starting point.

        • Samuel Wood (Otto) 1:49 am on April 28, 2015 Permalink | Log in to Reply

          I’m not opposed to improving the system, but first i think we need to unify the thing. We already have code to parse and use the plugin readme files, somewhat. We just need to figure out how to use that for themes.

          So even if we’re not using those files right now, let’s get theme authors on the same page and get them to make those readme.txt files. This gives us a base to work with and to write code for. Helps.

    • Justin Tadlock 5:07 pm on April 27, 2015 Permalink | Log in to Reply

      Just to be clear, and in case anyone took what I wrote out of context, I’d love to see change logs done by all developers. I just don’t think they’re beneficial to users without support in the core code.

      I’m mostly indifferent to the idea until core implements something that allows users to view the change log before updating. This would most likely be handled via a readme.txt just like plugins.

      • Jose Castaneda 9:39 pm on April 27, 2015 Permalink | Log in to Reply

        I’d love to see change logs done by all developers.

        As would I. :)

        This would most likely be handled via a readme.txt just like plugins.

        Which I think this discussion really appears to be headed. I’m down for that direction. Honestly, I like the plugin way of handling it and have for a long time too.

        • Justin Tadlock 9:53 pm on April 27, 2015 Permalink | Log in to Reply

          I’d be down the the plugin method. If that’s the case, this conversation needs to turn into a broader conversation about readme.txt. I say let’s implement a standard for that (including change logs), which we’ve all been wanting to do for a few years now, right?

          • Jose Castaneda 9:54 pm on April 27, 2015 Permalink | Log in to Reply

            Yes! Let’s

          • Justin Tadlock 10:17 pm on April 27, 2015 Permalink | Log in to Reply

            Rough pass at a readme standard. I copied from plugin standard. I removed the “installation” (think it’s a bit outdated given advancements in installation) and “screenshots” (probably not needed b/c live previews) sections.

            === Theme Name ===
            Contributors: (this should be a list of wordpress.org userid's)
            Donate link: http://example.com/
            Tags: left-sidebar, fixed-width
            Requires at least: 4.0
            Tested up to: 4.2
            Stable tag: 1.5
            License: GPLv2 or later
            License URI: http://www.gnu.org/licenses/gpl-2.0.html
            
            Here is a short description of the theme.  This should be no more than 150 characters.  No markup here.
            
            == Description ==
            
            Theme desc.
            
            == Frequently Asked Questions ==
            
            = A question that someone might have =
            
            An answer to that question.
            
            = What about foo bar? =
            
            Answer to foo bar dilemma.
            
            == Changelog ==
            
            = 1.0 =
            
            * A change since the previous version.
            * Another change.
            
            = 0.5 =
            
            * List versions from most recent at top to oldest at bottom.
            
            == Upgrade Notice ==
            
            = 1.0 =
            
            * Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.
            
            = 0.5 =
            
            * This version fixes a security related bug.  Upgrade immediately.
            * something else
            * third thing
            • Ulrich 6:27 pm on April 28, 2015 Permalink

              We should have a section for the licenses.

    • Emil Uzelac 8:31 pm on April 27, 2015 Permalink | Log in to Reply

      Which translates to this: we all want them and our difference was just a matter of the opinion who needs it more.

    • Samuel Wood (Otto) 3:32 am on April 28, 2015 Permalink | Log in to Reply

      It comes down to this. If you adopt the existing system we already have for plugins, and figure out how we can use that information, then it’s probably going to be simpler to get working in the short term, and then we can iterate on both in the long term.

      In what way is the current plugin’s readme method deficient? Other than stupid naming concerns? We’re not looking for perfection on the first iteration, I think balance would work just fine.

      Also, remember that the core WP code does not read the readme.txt at all, nor will it. That is .org specific data, just for display here (and in the API returned data). That actually makes the most sense and gives a solid separation of info vs. code.

  • Tammie 10:53 am on April 26, 2015 Permalink |  

    Amazing results from the queue push day.

    We had a queue push day yesterday. It was really great to see so many reviewers dropping in and really making a difference. The big news is we got the admin review queue down to zero! It was really great to see as people pinged in channel the tickets they were dealing with and the day rapidly saw the queues get down.

    To give perspective this is what things looked like before the event:

    • 161 new tickets are waiting for review.
    • 0 tickets are older than 4 weeks
    • 0 tickets are older than 2 weeks
    • 35 tickets are older than 1 week
    • 95 tickets are older than 3 days
    • 248 tickets are assigned.
    • 166 tickets are older than 4 weeks
    • 227 tickets are older than 2 weeks
    • 242 tickets are older than 1 week
    • 248 tickets are older than 3 days
    • 77 are approved but are waiting to be made live.

    This is what it looked like after the event:

    • 80 new tickets are waiting for review.
    • 0 tickets are older than 4 weeks
    • 0 tickets are older than 2 weeks
    • 28 tickets are older than 1 week
    • 52 tickets are older than 3 days
    • 288 tickets are assigned
    • 185 tickets are older than 4 weeks
    • 255 tickets are older than 2 weeks
    • 276 tickets are older than 1 week
    • 284 tickets are older than 3 days
    • 0 are approved but are waiting to be made live.

    It’s really incredible what we can do as a team when we focus like this – how strong we are united. The next hurdle is making sure this keeps up. To do that, we need diligence. Admins or key reviewers, if you re-opened a ticket make sure you check it doesn’t get lost without an owner. Also, those that took reviews, make sure they get done in 7 days.

    This event was so good, lets try to do one a month. Not everyone will turn up to each and certainly we shouldn’t be getting the queues as bad if we try and keep up. It’s worth having a day a month though where we try and clean up things. I’ll post here again the week before a next one starts.

    Thanks again all that turned up, you made a real impact.

     
  • Justin Tadlock 8:29 pm on April 25, 2015 Permalink |  

    Theme Authors: Update TGM Plugin Activation 

    This is a quick notice for all theme authors using the TGM Plugin Activation (TGMPA) class in their themes. Please update to version 2.4.1 as soon as possible. There is currently a XSS vulnerability. However, this issue is limited in scope.

     
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