WordPress.org

Ready to get started?Download WordPress

Make WordPress Plugins

Updates from Samuel Wood (Otto) Toggle Comment Threads | Keyboard Shortcuts

  • Samuel Wood (Otto) 6:57 am on April 7, 2014 Permalink | Log in to leave a Comment
    Tags: mysql, mysqli, php, wpdb   

    MySQL in WordPress 3.9 – Implications for Plugin Authors 

    If you’re a plugin developer and you have a plugin using any of the php mysql functions directly, then you might start to see breakage in WordPress 3.9.

    See, the php mysql extension is very old. As of PHP 5.5, it’s also deprecated and will very likely not be receiving further updates.

    So starting in WordPress 3.9, if PHP 5.5 is being used, the built in WPDB class will switch to using the mysqli extension instead.

    What this means for your plugin is that if you’re using any mysql_* functions directly, and somebody tries to use your plugin on a WordPress 3.9 + PHP 5.5 system, then all your database code will no longer work properly. Since the mysql functions are no longer being used in such a case by WordPress, then there is no longer an implicit database connection available to these function calls.

    Instead of using a direct database connection, you can switch to using the global $wpdb instance of the WPDB class to access the database. @pento gives a great rundown on what functions to use as drop-in replacements on this make/core post: http://make.wordpress.org/core/2014/04/07/mysql-in-wordpress-3-9/

    Now, as this is currently limited to PHP 5.5 and up only, the amount of breakage will likely be very minor. Our stats currently show that PHP 5.5 is being used on less than 1% of installations. Nevertheless, hosts are starting to upgrade PHP versions more and more frequently. This number is thus expected to grow over the next year or two. So before your users start having broken sites, please, take the time to switch your plugins over to the WPDB based methods. This will ensure future compatibility and minimal breakage.

    WordPress will always maintain backward compatibility in its own functions, so using them ensures that you’ll be good for the forseeable future, no matter what database methods are being used internally.

     
    • rahul286 7:27 am on April 7, 2014 Permalink | Log in to Reply

      Glad to hear this. mysqli is much better.

      We use PHP 5.5 and mysqli on all sites. I hope WordPress site’s running PHP 5.5 and mysqli will run faster soon. :-)

  • Samuel Wood (Otto) 4:14 pm on April 16, 2013 Permalink | Log in to leave a Comment
    Tags: author, google, markup, schema   

    Be the Author… 

    So, I’ve had this working for a while, but not a lot of people noticed, so I figured I’d spell it out explicitly.

    WordPress.org plugin pages have special magic Google markup. This is what allows many of the Google tricks we do for plugin pages to work. If you’ve ever searched for one of our plugins on Google, you may have noticed that it says it’s “free” as well as showed the rating as stars and such. This is all using Google’s Rich Snippets functionality with markup from the schema.org specifications.

    One of the magic tricks we do is to point to your WordPress.org Profiles page as the “author” of the plugin. It’s your plugin, after all, and you deserve the credit. But promoting the authorship is only half the picture, it helps if Google also knows who you are as an author. Then they can do something clever too:

    googleauthor

    This is a sample entry for one of my plugins from the Rich Snippets Testing tool. The photo and authorship info may not show up on every search result that gets my plugin up on Google’s search results, but it certainly doesn’t hurt. But to get this information to be capable of showing, Google needs to connect your profile and user information on WordPress.org with a profile and user information from Google+. To do this, there’s two steps:

    Step 1: Edit your WordPress.org profile to include a link to your Google+ account. You can do this yourself, and you can see how I did it on my Profiles page. I included this link in my “About Me” section: https://plus.google.com/100201852715113506716?rel=author

    Note that the ?rel=author bit is important, that’s what tells Google that you are the author here and links your G+ account to this page.

    Step 2: Tell Google that you contribute to WordPress.org. To do this, go to your Google+ Profile. In the “Links” section you will find a “Contributor To” area. You need to add two links to this area:

    • The first link will be a link to your own profile page, on http://profiles.wordpress.org. This completes the connection and tells Google that you and the profile are the same person. Because your plugin page automatically links to your profile with the author information, making this connection creates an indirect authorship connection to all your plugins.
    • The second link you need to make is a link to http://wordpress.org itself. This is because Google wants there to be an explicit connection on the same domain name (not a subdomain), and so this link is required. And hey, you’re contributing to WordPress.org every time you update your plugin or theme, so well done there! :)

    After doing both these steps, you can try your plugin’s URL in the Rich Snippets tool yourself, and voila, you’ll see the magic. Note that you may not see it in the actual Google search results for weeks, and it may never appear. Google shows snippets like these on terms of their own choosing. All you’re doing here is to give them the data that lets their engine do the magic, if it can.

     
    • Gabriel Reguly 4:24 pm on April 16, 2013 Permalink | Log in to Reply

      Wonderful Otto! Thanks for sharing this.

    • Charleston Software Associates 4:28 pm on April 16, 2013 Permalink | Log in to Reply

      Coolness! Thanks for the step-by-step guide, Otto. Works great!

    • myatu 5:39 pm on April 16, 2013 Permalink | Log in to Reply

      I didn’t even know you could use HTML in the “About Me” section. Learn something new everyday! :)

    • Peter 6:14 pm on April 16, 2013 Permalink | Log in to Reply

      +1 for Otto!

    • Chuck Reynolds 6:26 pm on April 16, 2013 Permalink | Log in to Reply

      never had my about section filled out. html ftw. thx – good setup.

    • realloc 7:50 pm on April 16, 2013 Permalink | Log in to Reply

      +1 Excellent!!

    • Syed Balkhi 8:43 pm on April 16, 2013 Permalink | Log in to Reply

      Sweet. I just added authorship on my profile :)

    • Crunchify 8:52 pm on April 16, 2013 Permalink | Log in to Reply

      Great Tips. I’ve just updated my profiles..

    • Andrey "Rarst" Savchenko 9:13 pm on April 16, 2013 Permalink | Log in to Reply

      Had you considered implementing `link rel=”author” url=”[g+ profile]“` in plugin pages header? It will simplify setup and won’t need that “indirect” connection through profile page.

      • Samuel Wood (Otto) 9:17 pm on April 16, 2013 Permalink | Log in to Reply

        That would require us to set up a special field somewhere for a G+ account, and if that social-network, then why not add others too, and yadda-yadda..

        This was a freebie, basically. I didn’t have to make any code changes to do it. We’ve had rel=author in there pointing to profiles forever, and the schema.org markup has been there for at least a year or more.

        I just noticed that I seemed to have been the only one to have done this already when I was looking through some search results today, so I felt like a post to show people how was in order. I did fiddle with the markup a bit today for other reasons, but not for this post.

    • Marcel Brinkkemper 9:14 pm on April 16, 2013 Permalink | Log in to Reply

      This is great stuff. +1 for @rarst suggestion

    • Jon Brown 1:32 am on April 17, 2013 Permalink | Log in to Reply

      This is fantastic Otto, Thanks for the detailed write up. Would have taken way longer than I have patience to figure it all out on my own.

    • takien 2:45 am on April 17, 2013 Permalink | Log in to Reply

      Done, thank you :)

    • toddhalfpenny 9:35 am on April 17, 2013 Permalink | Log in to Reply

      Absolutely brilliant… lovely work… thanks.

    • Eric Amundson 2:26 pm on April 17, 2013 Permalink | Log in to Reply

      Thanks for the write-up, Otto.

      Looks like the WP.org plugin repo alphabetizes plugin contributors, correct?

      In trying to connect my profile, I found that the Rich Snippet Testing Tool, I get an error saying:

      “Note: The testing tool currently only checks the first rel=author link listed on a webpage for a link to a Google+ profile”

      Issue is that a former contributor has a name that starts earlier in the alphabet, so it’s always finding his author link first, but since he’s not linking to Google +, his avatar isn’t showing in results.

      Any ideas on how to force Google to see the profile of the correct user?

      • Samuel Wood (Otto) 2:36 pm on April 17, 2013 Permalink | Log in to Reply

        I don’t think it is sorted, actually. I think it shows up in the order in the Contributors line in the readme.txt file. But if you have an example I can see, I can track the code down.

        • Aaron D. Campbell 8:10 pm on April 17, 2013 Permalink | Log in to Reply

          Google “WordPress Twitter Widget” and you’ll see Sara’s pretty face, and she’s the last contrib in the list. However, check the Rich Snippet Tool and it shows me. I’m the first contrib in the list. I’d prefer it to show Range, but that one’s in the middle.

          I’m not certain this is the pattern, but that seems to be what’s happening now. I’ll try to tweak the contrib list on a few plugins and see what happens.

          • Samuel Wood (Otto) 8:17 pm on April 17, 2013 Permalink | Log in to Reply

            The readme.txt for that plugin has the people in the same order as the author listing on the sidebar does:

            http://plugins.svn.wordpress.org/twitter-widget-pro/tags/2.5.3/readme.txt

            I have no idea how/why Google shows faces or chooses between them. The rich snippets tool says first one wins, but this is neither the first nor the last time that Google has given me false or contradictory information.

            • Aaron D. Campbell 8:22 pm on April 17, 2013 Permalink

              Yeah, the rich snippets tool says the first wins (and displays the first person), but actual Google searches seem to be showing the last. Since you’re right about the order of contribs matching the readme, I’m going to try reording some to see what happens.

            • Aaron D. Campbell 6:33 pm on April 18, 2013 Permalink

              I gave it a little over 24 hours after the change, and as best as I can tell, Google just likes Sara better. She seems to be listed no matter the order. It may still be cached, but either way it’s still really cool.

              https://www.google.com/search?q=WordPress+Youtube+Upload+Widget
              https://www.google.com/search?q=WordPress+WP+Google+Analytics
              https://www.google.com/search?q=WordPress+Twitter+Widget

            • Samuel Wood (Otto) 6:37 pm on April 18, 2013 Permalink

              24 hours isn’t enough time. Those things likely won’t alter for weeks or more. I know WordPress.org is well-indexed by Google, but seriously, their snippets logic is confounding sometimes. Best to just set it the way you want and let it do its own thing. You can’t force it.

              Mine didn’t start showing up until I changed my G+ pic to be a “recognizable headshot”. Guess they don’t like my scuba avatar. It’s a shame too, I like the blue one.

            • Samuel Wood (Otto) 6:20 pm on April 20, 2013 Permalink

              After screwing around with this for a while, and reading up on the topic, Google seems to get very, very confused with multiple rel=authors. So I just now changed it to only have one rel=author on the plugin page, and that will be the first person listed.

              Hopefully, this should eliminate the ambiguity and cause more predictable results.

    • Brad Dalton 8:56 pm on April 17, 2013 Permalink | Log in to Reply

      Been using this link on my profile for a while already but didn’t add the ?rel=author to the end of the Google url which does make a difference.

    • Mert Yazicioglu 9:31 am on April 20, 2013 Permalink | Log in to Reply

      Before doing this, my plugin WordPress Move was the second result in Google when you searched for “wordpress move”. Now, however, it’s on the third page.

      Not sure if it’s a coincidence.

  • Samuel Wood (Otto) 4:43 pm on September 13, 2012 Permalink | Log in to leave a Comment
    Tags: assets, screenshots   

    Last December, we added header images to the top of plugin screens. Since then, we’ve made more changes to the plugin directory and started supporting HiDPI images for those plugin headers as well.

    As part of that original header update, one thing that was added which I always meant to do more with was the addition of a new “assets” directory at the top level of the plugin SVNs. This is an optional directory that sits alongside the /tags and /trunk directories, and was just used to hold the banner images. Creating a place to put plugin assets which didn’t need to be included in the plugin itself simply made sense to me.

    It also never made sense to me that the plugin screenshots, which are rarely used by the plugin, needed to be included in the plugin’s ZIP file. Some plugins can use these themselves, certainly, but the majority don’t and it’s just really inflating the size of the plugin to include them.

    So, starting today, you can put your screenshot files in the assets directory instead of in the main plugin directory.

    A few notes, for the technically minded:

    • Screenshot naming conventions have not changed, nor have the readme.txt requirements for their captioning. The naming and behavior is exactly the same, the file can just go into a new place.
    • The old way still works too. If you have your screenshots in the plugin’s “stable” directory, then it will find them there just fine.
    • Screenshots in the assets directory take precedence over screenshots in the plugin’s directory. If you have both, then the assets directory wins. Of course, there’s really no reason to have both, this is just for backwards compatibility.
    • Like everything else in the assets directory, we are serving them through a separate static caching system, and so it may take a few minutes to update when you change them. What this means is that when you put the screenshots in there for the very first time, they may not show up on your page for a few minutes and you’ll just see the captions with no images above them. Please give the proxy some time to retrieve your screenshots and cache them before telling me it’s buggy. It should only take a few minutes. :)

    The ultimate goal, of course, is to reduce the size of the plugin ZIP files being served. By not including the screenshots in the plugin, files are smaller and upgrades are thus speedier for everybody.

    In the future, if we have a need for more “directory only” files, I expect them all to be in the assets directory as well, for just this sort of reason.

     
    • Pippin Williamson 4:48 pm on September 13, 2012 Permalink | Log in to Reply

      Excellent!

    • logikal16 5:00 pm on September 13, 2012 Permalink | Log in to Reply

      That’s great news, thanks!

    • Brad Touesnard 5:03 pm on September 13, 2012 Permalink | Log in to Reply

      Nice!

    • Chuck Reynolds 5:04 pm on September 13, 2012 Permalink | Log in to Reply

      This is great. Shouldn’t we also do the same for readme files? With the recent security talks concerning the version number being in the readme’s in each plugin dir.

      • Otto 5:15 pm on September 13, 2012 Permalink | Log in to Reply

        I don’t know what talks you speak of in particular, but a) no and b) knowing the version of code being used is not an inherent security risk.

        A security risk is caused by running insecure code. The solution is not to attempt to hide the version, but to update the code to eliminate the security risk. This sort of thinking is along the same lines of hiding the WordPress version number from public view. Hiding your version number doesn’t improve security in the slightest. Fixing security related issues does.

        • Chuck Reynolds 10:46 pm on September 13, 2012 Permalink | Log in to Reply

          true, i can’t find the specific thing I read the other day but… whatever. just thinking out loud.

          Moved all my plugins’ screenshots to /assets/ from trunk and latest tag.

        • Ian Dunn 7:54 pm on September 14, 2012 Permalink | Log in to Reply

          I think that’s only half true. Obviously, fixing security bugs is the most important thing, but security-through-obscurity isn’t inherently bad, if you understand it correctly.

          Security shouldn’t be thought of as a binary thing — you’re either “secure” of “insecure” — and there are no silver bullets. Instead, it should be thought of in layers. Security-through-obscurity is a good first layer. It keeps the script kiddies away, so that you can focus your time on defending against real attackers.

          It’d be stupid to rely on obscurity as your only layer, but it’s a good practice to employ it as the first layer among many.

    • Ben Lobaugh (blobaugh) 5:12 pm on September 13, 2012 Permalink | Log in to Reply

      Thanks Otto

      @Chuck – good point, you would lose the tagged readme files though. Maybe the readme.txt file should just be blocked from serving?

    • scribu 5:53 pm on September 13, 2012 Permalink | Log in to Reply

      This makes sense. I just moved the screenshots over for all of my plugins.

      I noticed that the readme.txt example doesn’t point to the new /assets/ dir yet.

    • Thomas_Michaela 6:40 pm on September 13, 2012 Permalink | Log in to Reply

      Is there any discussion / ideas how to redesign the “popular plugins” section, so authors don’t need to fake their download numbers anymore?

      http://wordpress.org/support/topic/plugin-all-in-one-seo-pack-another-update-with-no-changes-this-plugin-is-just-scam?replies=8

      • Otto 7:18 pm on September 13, 2012 Permalink | Log in to Reply

        That doesn’t appear to be faked to me, just a bad development practice.

        Edit: Note that if you have hard evidence other than a one-time-thing, then that’s different. I’ll burn and salt the earth with the ashes if you can find a real case of somebody gaming our systems, but this does not appear to be such a case.

    • Jon Brown 7:36 pm on September 13, 2012 Permalink | Log in to Reply

      This all sounds great, nice work!

      Since I’m still a little slow when it comes to SVN though… Am I correct that /Assets is outside of version control? If that’s that case, I think that alone is reason to keep the readme files inside trunk, but even if that is not the case I’d still prefer seeing readme files in the zips.

      • Otto 7:45 pm on September 13, 2012 Permalink | Log in to Reply

        No, you’re not correct, and I’m not sure I understand the question.

        SVN is a version control system. Everything in it is “in version control”. So… yeah, you’ve left me confused.

        And there’s no plan (nor reason) to put readme.txt files anywhere that isn’t part of the plugin and isn’t in the ZIP file. That’s not under discussion nor up for debate, really. Readme’s should be sent with the plugin files.

    • Edward Caissie 8:03 pm on September 13, 2012 Permalink | Log in to Reply

      I must be slow or its not enough coffee today … to implement this new ‘assets’ directory the plugin author needs to send a commit with it included, correct? In other words, the assets directory is not being (has not been?) populated into the existing repository plugins (nor is it part of new plugin repositories).

      • Otto 8:13 pm on September 13, 2012 Permalink | Log in to Reply

        Correct, the /assets directory is not created for you. You can create it at the root of your plugin directory, alongside the trunk and tags and branches directories, and use “svn add” to add it and any files inside it to your next commit.

        • Edward Caissie 8:29 pm on September 13, 2012 Permalink | Log in to Reply

          Thanks. I had tested that with an existing plugin as well as checking out a newly created plugin repository as well. Just been having SVN client issues recently and wanted to make sure I was not _doing_it_wrong().

        • Matt Mullenweg 6:46 pm on September 14, 2012 Permalink | Log in to Reply

          Can we add it to the script that sets up directories for new plugins?

          • Otto 6:50 pm on September 14, 2012 Permalink | Log in to Reply

            We could, just haven’t seen the need to do so. Not everybody needs it, in the same way that uber-simple plugins don’t really need a readme.txt file.

            I’ll go ahead and add it though.

        • RobertPHeller 6:31 pm on June 15, 2013 Permalink | Log in to Reply

          ‘svn mkdir assets’ will both make the directory AND add it to the svn version control all in one step. Then doing a ‘svn mv trunk/screeshot*.png assets/’ moves the screenshots over.

          • Samuel Wood (Otto) 6:47 pm on June 15, 2013 Permalink | Log in to Reply

            The assets directory is automatically created for all new plugins now. You only need to do this if you got your plugin approved before last September.

    • elfin 8:58 pm on September 13, 2012 Permalink | Log in to Reply

      excellent – one reason why I never included any to begin with was because of the file size issue. Nice work again Otto.

    • shazdeh 10:38 pm on September 13, 2012 Permalink | Log in to Reply

      Totally makes sense!

    • Greenweb 1:30 pm on September 14, 2012 Permalink | Log in to Reply

      Great update to the system !

    • XYZScripts 6:08 am on September 15, 2012 Permalink | Log in to Reply

      Good move. Really saves on zip size.
      Next we should separate out readme.txt from folder as Chuck said.
      I think right now readme.txt is parsed from trunk until stable tag is found and then it starts parsing stable tag readme.
      So we have put this file in both trunk and tag which is simply duplicate.
      I dont think readme.txt is needed in s wordpress installation as it reads info from plugin main file (Correct me if an wrong)
      So why not move it to assets?

      • Otto 2:13 pm on September 15, 2012 Permalink | Log in to Reply

        No, the readme.txt file belongs with the plugin file itself and should be in the ZIP file. Moving it to assets makes no sense.

        The readme.txt will remain where it is.

    • Lance Cleveland 1:28 pm on September 17, 2012 Permalink | Log in to Reply

      Great decision. It is smart thinking like this that keeps WordPress ahead of all others and why I continue to recommend it as the best-of-breed for web publishing for my clients.

    • Aaron D. Campbell 2:08 pm on September 17, 2012 Permalink | Log in to Reply

      This was a great change. One of my plugins went from a 168k download to 52k. Thanks Otto.

    • wiredimpact 9:26 pm on September 28, 2012 Permalink | Log in to Reply

      This is a welcome change. It will greatly decrease the size of plugins. Thanks.

    • Aman 8:43 am on October 4, 2012 Permalink | Log in to Reply

      A very great decision :)
      Less size more downloads

    • Ben 7:50 pm on October 14, 2012 Permalink | Log in to Reply

      Awesome news!
      I was wondering if you guys where thinking about doing something for the languages files as well?
      I know that means also adapting the way a plugin is installed as well, but the more translations the heavier your plugins gets. Just leaving the .mo files it can be about 100k per language depending on the plugin’s size. Translate your plugin in 10 languages and Bam you get 1Mo extra.
      Thanks!

      • Otto 5:42 pm on October 16, 2012 Permalink | Log in to Reply

        No particular plans for languages, but that would be pretty cool. I was thinking more along the lines of having core support for language packs. Like, we could have a big GlotPress install somewhere to allow community translations of plugins and themes, then have an API to serve up-to-date .mo files, then serve them directly to users that request them, and let the core put them in the right place, etc.

        Would be neat, but obviously that’s a big job there, with a lot of moving parts.

        • Ben 8:59 am on October 17, 2012 Permalink | Log in to Reply

          Sounds good, if we’re aiming to this kind of solution, that’s just perfect. But as you said it feels like a lot of changes and work involved.

      • Milan Dinić 6:34 pm on October 23, 2012 Permalink | Log in to Reply

        Still in works.

      • Milan Dinić 6:36 pm on October 23, 2012 Permalink | Log in to Reply

        How about displaying “Screenshots” tab only when there are screenshots, not always when “Screenshots” section of readme.txt has any content?

    • Joe Dolson 7:29 pm on October 22, 2012 Permalink | Log in to Reply

      The recent changes to the plug-in directory have been great — I noticed something today that I’m hoping would be a pretty quick fix: you can’t do a search on the words ‘accessibility’ or ‘accessible’. You can visit the tags, of course, but I don’t think it’s really the right response to send searches for these two terms to the results for ‘access’ — those are definitely two very distinct searches, and really should be giving different results.

      • Otto 7:40 pm on October 22, 2012 Permalink | Log in to Reply

        There’s no limitation on what you can search for. But the search engine considers similar words to be similar for the purposes of searching.

        • Joe Dolson 8:42 pm on October 22, 2012 Permalink | Log in to Reply

          Well, it’s definitely a problem — is there any way to tweak what the search engine considers to be similar? “access” and “accessibility” may be similar from a programming standpoint, but in terms of the search intent, they’re radically different – and I think it’s a serious limitation to the repository that you can’t easily find plug-ins that are intended to support accessibility.

    • RobertPHeller 6:20 pm on June 15, 2013 Permalink | Log in to Reply

      My plugin has a PDF user manual. This adds to the ‘bloat’ of the plugin. The plugin is complex enough to need this level of documentation. I am wondering: if I were to put the PDF manual in the assets directory, how would I link to it from the plugin’s contexual help screens? Right now, with the PDF file embedded in the plugin’s ZIP file, it is just a relative link.

      • Samuel Wood (Otto) 6:35 pm on June 15, 2013 Permalink | Log in to Reply

        You don’t. Files in the assets directory do not go into the plugin itself. You need to have the file in the plugin to be able to use it on people’s sites.

    • TC.K 4:51 pm on June 27, 2013 Permalink | Log in to Reply

      Hi, I added a header image into the assests/ directory, but some how the image does not show up in my plugin page. I checked on my plugin svn assests/ directory, I can see the files is in there, but it is not showed up. what is the problem?

      I don’t know whether here is the right place to ask, if there is another way to report this problem, please let me know.

      Thanks

    • TC.K 5:48 pm on June 27, 2013 Permalink | Log in to Reply

      Sorry, I spell it wrong here. But in the directiory is corret. Here is the link:
      http://plugins.svn.wordpress.org/ajax-wp-query-search-filter/assets/

      • Samuel Wood (Otto) 5:58 pm on June 27, 2013 Permalink | Log in to Reply

        You named the file wrong, probably from copy and pasting the name. The letter between the 772 and the 250 needs to be an “x”, not that multiplication symbol you have there.

    • TC.K 11:54 am on June 30, 2013 Permalink | Log in to Reply

      Yes, you are right!! Thank you very much!

    • Lars Schenk 11:35 pm on November 27, 2013 Permalink | Log in to Reply

      Looks like the /assets makes a problem for git-svn. Question asked here:
      http://stackoverflow.com/questions/12742842/how-to-add-a-header-image-to-my-wordpress-plugin-using-git-svn
      Not answered since 1y.

      Also found in other words: ” Does anyone have any insight on using this (updated) commit workflow along with the SVN assets folder? I have my git and SVN repositories synced up, but now I need to update the screenshots. I assume that if I do a pure SVN commit to update these then everything will get out of sync. I don’t see a way to update the assets folder via git-svn either. Any help would be appreciated!”

  • Samuel Wood (Otto) 6:12 pm on June 9, 2012 Permalink | Log in to leave a Comment
    Tags: , plugin, readme, repository, svn   

    The Plugins directory and readme.txt files 

    Every once in a while, somebody pings me to say that their plugin isn’t showing up properly in the directory. Almost always it’s a problem with the plugin itself having incorrect information somehow. So I thought I’d do a quick post to explain some aspects of the plugin directory, and explain some of the more obvious stuff which a lot of people miss.

    Layout

    First, let’s briefly go over the layout of your plugin in the SVN repository. There’s three directories created by default, and an optional fourth one that you can create yourself.

    Trunk: The /trunk directory is where your plugin code should live. The trunk can be considered to be the latest and greatest code. It’s the development version. Hopefully, the code in trunk should always be working code, but it may be buggy from time to time because it’s not necessarily the “stable” version. For simple plugins, the trunk may be the only version of the code that exists, and that’s fine as well.

    Tags: The /tags directory is where you can put versions of the plugin at some specific point in time. Usually, you’ll use version numbers for the subdirectories here. So version 1.0 of the plugin would be in /tags/1.0, version 1.1 would be in /tags/1.1, and so forth. Again, not every plugin uses tags for versioning.

    Branches: The /branches directory is a place that you can use to store branches of the plugin. Perhaps versions that are in development, or test code, etc. The WordPress.org system does not use the branches directory for anything at all, it’s considered to be strictly for developers to use as they need it.

    Assets: The last optional directory doesn’t exist by default (Edit: It does now, older plugins may be missing it, but all newly added plugins will get it by default.) You can create it yourself though. Just make a directory called “assets” next to those other three directories. Assets currently only has one use, which is to store the banner image to be displayed on your plugin page. We may use it for more things in the future. For now, you can just make an image, name it banner-772x250.png or banner-772x250.jpg, and put it in there. Easy.

    Additional Info: Since creating this post, some new files have been added to the assets folder. You can create a banner-1544x500.png or banner-1544x500.jpg now too. This high-resolution banner will be shown to users with high-resolution displays, such as phones or tablets or certain newer laptops. Additionally, screenshots which once lived in the plugin’s own directory can now be moved from there into the assets directory. This allows the screenshots to be shown on the plugin page, but not included in the download of the plugin, reducing file size. It’s recommended to put screenshot files in /assets.

    Parsing the plugin information

    All plugins contain a main PHP file, and almost all plugins have a readme.txt file as well. The readme.txt file is intended to be written using a subset of markdown.  The example readme.txt explains most everything pretty well, but there’s a few little tidbits that are worth pointing out.

    First is the concept of the “Stable Tag”. When WordPress.org parses the readme.txt, the very first thing it does is to look at the readme.txt in the /trunk directory, and then read that “Stable Tag” line. If the Stable Tag is missing, or is set to “trunk”, then the version of the plugin in /trunk is considered to be the stable version. If the Stable Tag is set to anything else, then it will go and look in /tags/ for the referenced version. So a Stable Tag of “1.2.3″ will make it look for /tags/1.2.3/.

    Important bit: Everything else is read from this new location. If the Stable Tag is 1.2.3 and /tags/1.2.3/ exists, then nothing in trunk will be read any further for parsing by any part of the system. If you try to change the description of the plugin in /trunk/readme.txt, and Stable Tag isn’t trunk, then your changes won’t do anything on your plugin page. Everything comes from the readme.txt in the file being pointed to by the Stable Tag.

    Now let’s get to the plugin information itself. The WordPress.org directory reads the main plugin PHP file to get things like the Name of the plugin, the Plugin URI, and most importantly, the version number. On the plugin page, you’ll see the download button which reads “Download Version 1.2.3″ or similar. That version number comes from the plugin’s main PHP file.

    Some people get this versoning confused due to the tags system. The Stable Tag points to a subdirectory in the /tags directory. But the version of the plugin is not actually that, it’s the version that is listed in the plugin’s PHP file itself. If you have changed Stable Tag to 1.4 and the plugin still says 1.3 in the PHP file, then the version listed will be 1.3.

    Readme.txt pieces that everybody gets wrong

    Back to the readme.txt. There’s a line called “Contributors”. This line has always been expected to be WordPress.org usernames only. WordPress reads those, gets information about that user, gets their gravatar, name, etc, and makes the authors listing. If you put anything here that’s not a WordPress.org username, then it doesn’t look nearly as good. No picture, no link, just text.

    Other information in the readme.txt is read and used at various points on the Plugin listing. The Donate link makes a “Donate to this plugin” link in the sidebar. The “Requires at least” and “Tested up to” fields are used for compatibility checking, even on the WordPress installation itself. Few people get these wrong.

    One thing a lot of people get wrong is this line:
    “Here is a short description of the plugin.  This should be no more than 150 characters.  No markup here.”

    That bit is serious, and you should read it again. That one line people get wrong more often than anything else. That line of text is the single line description of the plugin which shows up in big letters right under the plugin name, and if it’s longer than 150 characters, it gets cutoff and makes your plugin page look silly.

    Markdown allows for easy linking in your readme.txt as well. Just write like this to link a word to a URL:

    [WordPress](http://wordpress.org)

    Videos can be put into your readme.txt too. A YouTube or Vimeo link on a line by itself will be auto-embedded. It’s also possible to embed videos hosted on VideoPress using the wpvideo shortcode. More on that topic here: http://wpdevel.wordpress.com/2010/02/20/plugins-can-now-include-videos-in-their-readme-txt-files/

    Summary

    I don’t think I covered everything, but hopefully that will explain some of the more obscure features of the directory and how it works. If it reduces the number of times people send me the question “why didn’t my version change show up in the directory”, then I think this post was time well spent. :)

     
    • Marcus 7:32 am on June 10, 2012 Permalink | Log in to Reply

      I must admit, I’ve made one or two of these mistakes starting off :)

      Useful article, it would go great linked somewhere in the developer center, as I’m sure that’s where people starting would look first.

    • Lance Cleveland 2:37 pm on July 12, 2012 Permalink | Log in to Reply

      Don’t forget about the new “high definition” banners for the header image. If memory serves this is twice the resolution of the standard banner in the assets directory at 1444×500.

    • Mike Schinkel 7:16 pm on August 3, 2012 Permalink | Log in to Reply

      Just replying so I can get subscribed to this blog (might be another way, but can’t figure out how.)

    • Brad Touesnard 3:53 pm on August 17, 2012 Permalink | Log in to Reply

      @Otto Would it be possible to start supporting the filename README.md in addition to readme.txt? A lot of developers host their plugins on GitHub as well but the filename readme.txt isn’t run through the markdown parser at GitHub. It would be nice if .org supported the README.md filename as well.

    • Gwyneth Llewelyn 10:12 pm on November 18, 2012 Permalink | Log in to Reply

      Ok, I’m a bit confused now.

      “If the Stable Tag is 1.2.3 and /tags/1.2.3/ exists, then nothing in trunk will be read any further for parsing by any part of the system. If you try to change the description of the plugin in /trunk/readme.txt, and Stable Tag isn’t trunk, then your changes won’t do anything on your plugin page. Everything comes from the readme.txt in the file being pointed to by the Stable Tag.”

      So if I understand this correctly, the best way to deal with this scheme is simply to have a single file under /trunk/, which is readme.txt, and that needs only to hold 9-10 lines or so with the headers — and just point to the “Stable Tag”? Then the *rest* of the readme.txt *which is under the tag, not trunk* will be read & parsed instead? I don’t need to have a full copy of readme.txt both under /trunk/ *and* /tags/X.Y.Z/ ?

      You see, I hate unnecessary file duplication :) I love the idea of having a super-small, 9-line only, readme.txt file under /trunk/ which just points to the correct place. Also, it makes this far easier to revert to earlier versions in case something goes seriously wrong!

      Sorry if all of this sounds incredible obvious to you seasoned plugin developers :)

      • Gwyneth Llewelyn 10:44 pm on November 18, 2012 Permalink | Log in to Reply

        Maybe all that’s needed on trunk/readme.txt is 2 lines after all:

        === Plugin Name ===
        Stable tag: X.Y.Z

        Is that right? The remaining readme.txt will come from tags/X.Y.Z instead? If so, this is just awesome!

      • Samuel Wood (Otto) 4:38 am on November 19, 2012 Permalink | Log in to Reply

        Yes, that works.

        No, you absolutely should not do it that way.

        There is a *convention* in place here. People expect trunk to contain the latest development code of your plugin. In other words, the latest and greatest code, unstable changes and all, belongs in trunk. The latest stable, versioned, tagged code, will be in a tags directory.

        The directory is based around this concept. There are beta-tester plugins which assume this to be true. Forget about “duplicated files”, do it the way everybody else does it so that you don’t mess up the friggin’ system. :)

        Put your development code in trunk. Tag the ready-for-release versions of the code in the tags directory. This is the best way to manage things. Even repository systems such as git and github have the concept of a main trunk for development and tags for versioning. The goal isn’t to make things easier for you to manage, the goal is to make the code accessible to everybody else in a sane way.

        • Gwyneth Llewelyn 4:42 pm on November 19, 2012 Permalink | Log in to Reply

          Thanks for the clarification and I do apologise if I have understood you wrongly. Maybe you should clarify that duplication of everything continues to be mandatory, and not optional, to stick to conventions. Your article, read in a certain light, seemed to convey the idea that the convention was changed exactly for the benefit of keeping things simple.

          I’m not here to discuss what is better and what is not — I’ve just asked the question on how to do things from now on because the article lead to believe me that the convention had changed, or, if it hadn’t, that “beginners were always making mistakes and can do things in much simpler ways if they understand the directory structure better”. And I appreciate your answer: no, nothing has changed.

          “The goal isn’t to make things easier for you to manage”. Why not? KISS is always a good philosophy, IMHO.

          • Samuel Wood (Otto) 4:59 pm on November 19, 2012 Permalink | Log in to Reply

            It’s not really duplication though. SVN doesn’t store files that way, it really just stores changesets. The trunk/tags/branches convention is SVN’s, not ours. You can tag things using an svn copy operation, and that’s not making new files in svn, just marking copies of the files at a specific point in time.

            The Stable Tag and readme.txt stuff is indeed ours, simply for the purpose of keeping things in the directory sane.

    • brasofilo 2:08 pm on December 18, 2012 Permalink | Log in to Reply

      Finally I got the /tags/ concept and am correcting a wrongful use of the “Stable Tag” (I had it declared, but the version was not present in the tags folder), although the system was kind enough to make it work.

      Now, I’m looking for articles on how to use the /trunk/ when developing a new version of the plugin.
      I mean, is it possible to install and update from there?

      • Samuel Wood (Otto) 5:56 pm on December 18, 2012 Permalink | Log in to Reply

        Trunk should be the “beta” version, and have its version numbers indicating such. So if my Stable Tag was like 1.0, and I had a /tags/1.0 directory, then I could make trunk’s version into 1.1-beta or something like that, and make all the changes I liked, then when it was ready for release, change it to 1.1 and tag it and update the Stable Tag field in the readme.txt to point to the new one.

        If you use this sort of structure, with trunk containing the latest beta code, then you can easily use a plugin like http://wordpress.org/extend/plugins/plugin-beta-tester/ to update to that beta version on a site.

        • brasofilo 7:29 pm on December 18, 2012 Permalink | Log in to Reply

          Perfecto, Otto, gracias!

        • Hinjiriyo 1:56 pm on January 31, 2014 Permalink | Log in to Reply

          Now I got the concept of the trunk dir! Thank you very much for your explanation.

          There are other informations about the way the readme file and tag files are processed by the WP plugin repo. I wish someone would extend the Plugin Developer FAQ with that article and the role of the trunk.

    • amineoujda 10:09 am on July 16, 2013 Permalink | Log in to Reply

      Hi,
      I want to change the line description that appears below the plugin name

    • bendoh 4:44 pm on January 22, 2014 Permalink | Log in to Reply

      Hey,

      Is there any sort of documentation as to the exact subset of Markdown that’s being used on these readme.txt files, or could you perhaps point me to the code that’s actually producing the rendered markup?

      I just submitted a plugin with standard Markdown list formatting, (e.g., * Item 1\n*Item 1) in the readme.txt, and it was not rendered correctly on the plugin page: it just appeared all together in one paragraph without any markup.

    • duck__boy 9:32 am on April 14, 2014 Permalink | Log in to Reply

      A very will written post, but I must admit, I’m still struggling with the `readme.txt` file. I suspect I’m just missing something, but I’m hoping you are able to help.

      I have both a version of my plugin with the `readme.txt` file, in the `/trunk` and `/tag/1.2.4` folders, but none of the details from `readme.txt` seem to be read, including the Stable Tag. This also means that the `Installation`, `FAQ` and `Changelog` sections are not available on the plugins `Details` page).

      So taking the above in to account, if I change the version number of the main PHP file in `/trunk` to say `1.3-beta`, that version number is shown when you search for my plugin, and my `/tag/1.2.4` file is ignored.

      The plugin in question is http://wordpress.org/plugins/admin-bar-button/

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