WordPress.org

Make WordPress Plugins

Tagged: svn Toggle Comment Threads | Keyboard Shortcuts

  • Samuel Sidler 1:35 pm on August 30, 2016 Permalink
    Tags: maintenance, svn   

    COMPLETED! Upcoming Maintenance Window for Plugins SVN 

    Hello plugin authors!

    We will have a maintenance window for the plugins SVN repository from August 31, 20:30 UTC through September 01, 00:30 UTC (four hours total). During this time, plugin authors will not be able to commit to the SVN repository.

    This post on the WordPress.org status page will be updated when the maintenance window is complete.

    Edit: Maintenance has been completed, and the plugins SVN is available for commit once again.

     
  • Samuel Wood (Otto) 6:12 pm on June 9, 2012 Permalink |
    Tags: , , 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 https://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 https://wordpress.org/plugins/admin-bar-button/

      • duck__boy 3:31 pm on April 22, 2014 Permalink | Log in to Reply

        Just in case anyone ever runs in to this, my issue was that my `readme.txt` file was not encoded as ANSI for some reason. I simply recreated the file using the correct encoding and all is now good with the world (well, my plugin anyway…).

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

      @Otto42 is there any chance that the readme parser could be changed so that it reads “Tested up to” and “Requires” from the trunk copy of readme.txt? It would sure make it a lot easier for Plugin developers to update this information in the Plugin directory. As it is right now, we either have to update the readme.txt in the stable tag readme.txt, or else bump the version number just to indicate that the Plugin has been tested and works with the latest WordPress version.

      • Samuel Wood (Otto) 5:03 pm on April 22, 2014 Permalink | Log in to Reply

        You can edit the readme.txt file in a tagged version. SVN isn’t like Git, it doesn’t have a restriction preventing you from editing tagged versions.

        I’ll think about using the trunk readme for other things though, some of this seems like it might be a candidate for a refactoring.

    • Raghunath Gurjar 1:37 pm on June 17, 2014 Permalink | Log in to Reply

      Hi,
      I have released my plugin two version but still on plugin download page its show first release version 1.0 while when you will download my plugin , you will get all latest code.

      https://wordpress.org/plugins/simple-testimonial-rutator/
      You can also find developer log from here https://wordpress.org/plugins/simple-testimonial-rutator/developers/

      Can you someone help me please?
      I don’t know why this happening , i have updated the Stable tag in readme.txt file to 1.2

      • Samuel Wood (Otto) 5:25 pm on June 17, 2014 Permalink | Log in to Reply

        All information in the system is gathered directly from your plugin. If the displayed information is wrong, then your plugin is wrong.

        In this case, notice that the version number in the plugin itself is 1.0:
        https://plugins.svn.wordpress.org/simple-testimonial-rutator/tags/1.2/simple-testimonial-rotator.php

        Fix the plugin to have the correct information.

        • Natallya 7:21 pm on August 22, 2014 Permalink | Log in to Reply

          Hi, does anyone know how to get feedback for a plugin published?
          It’s more then month we sent it for review but no information at all. How can I know if it was declined ?

          Thank you!

          • Samuel Wood (Otto) 7:24 pm on August 22, 2014 Permalink | Log in to Reply

            We don’t have any plugins in the queue that have been there for more than a month. You would have received an email about it, and if we got no answer for 7 days, then it would be automatically rejected and you would receive an email about that too.

            Make sure that your email system is set up to never spam any emails coming from WordPress.org. We send emails for lots of things, but we cannot control what your end does with them.

          • Samuel Wood (Otto) 7:26 pm on August 22, 2014 Permalink | Log in to Reply

            Looking closer, it appears that your plugin was approved and you never continued on and did anything with it. Again, check your emails, your plugin was approved on the 11th of last month.

    • Natallya 5:46 pm on September 4, 2014 Permalink | Log in to Reply

      Thanks a lot, email had gone to junk… Setting up all further things. Thank you again for a good news! πŸ™‚

    • JayDeep Nimavat 12:34 pm on October 4, 2014 Permalink | Log in to Reply

      Hello wordpress friend,

      I have created new version of “JDs Portfolio” plugin,

      I have done change,

      • deleted all folder and files from Repository trunk directory and uploaded new files and folder of new plugin version.
      • Created new directory 1.1 in Tags directory where 1.0 is already available and I uploaded all new files and folder of new plugin version in 1.1.

      The duration of uploaded new version plugin is more than one day.

      The problem is that it still give old version of plugin when anyone download it, and shows in Developer option as other version, as current version it display me old version 1.0.1 of JDs Portfolio plugin.

      Please help me to solve :
      How can I apply new version of plugin as current version?

      your good suggestion most appreciate,
      Thanks a Lot’s,
      JD.

    • salescart 4:45 pm on October 8, 2015 Permalink | Log in to Reply

      Ok, I’m sorry but I’ve read this and I’m still confused. We tried to make our first revision at https://plugins.svn.wordpress.org/e-commerce-by-salescart/tags/1.1.0/

      1.) So are you saying it still looks at the readme.txt file in the /trunk folder to find the stable tag, and based on that that, it then goes to that /tags folder for the plugin content and will ignore the rest of the content in the /trunk folder?

      2.) Or, are you saying the only released version is ALWAYS the version at the trunk? (This would be despite the readme.txt file’s stable tag saying 1.1.0 instead of trunk and that the tags folders is just for historical reference). Therefore, the /trunk version must be the most up-to-date version… ?

    • webbistro 9:29 am on January 10, 2016 Permalink | Log in to Reply

      Hello,

      I’ve read this carefully, and I uploaded new versions many times, but I am afraid I need help now. I am sure that all data is correct in my tag and trunk readme-s and in the main php, but I still see the old description, changelog, everything below readme’s header. The significant differences from the previous updates is that I am not receiving email notifications any more.
      Please help https://wordpress.org/plugins/enhanced-media-library/ (I know, too many actions… but I hoped I just did something wrong).

      Thanks!
      -Nadia

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
Skip to toolbar