Tips for New Plugin Developers to Help Connect the Dots

  • WatchCount.com

    (@watchcountcom)


    14 years, 3 months ago

    As a new plugin developer, like many I learned a lot about WordPress plugin development by reviewing the Codex, diving in, and reading numerous 3rd party tutorials and blog posts online, written by generous WP veterans. From one place or another, I pieced together the big picture and got most everything answered for myself. However, a number of questions about plugin development and the directory submission process lingered in my mind (and some still do), undocumented as far as I could tell, and took a little while to figure out.

    So I thought I’d “fill in the blanks” here about several of those loose ends that I figured out for myself, in case other newbie plugin developers are having the same question marks appear in their heads. If you’re currently in the plugin learning or launching process, you may want to look over this tips list alongside all the other helpful information out there about WP plugins.

    Uploading Your Plugin
    The plugin uploading system for the WP Plugin Directory doesn’t work via FTP. Instead, server-side software called Subversion (“SVN”) houses both WordPress and all plugins in the WP Plugin Directory. You’d obtain a Subversion client, such as TortoiseSVN, and use it to access the repository. You then “Checkout” your files (even your empty repository area the first time), add your updates to your local folder, then “Checkin/Commit” your updates to the repository. Within ~15 minutes, your updates will be live.

    First though, you’ll need to gain access to the repository by being granted so by WP.

    WP Plugin Directory Submission
    After you’ve finished creating and testing your new plugin, you’ll probably want to submit it to the central WP Plugin Directory (if appropriate). The process is this: You’ll submit your request, which creates a placeholder repository download page (not publicly searchable). Within a few days someone at WP will (hopefully) approve your request, granting you permission to upload your plugin into the Subversion repository using your current WordPress.org username and password. The ball’s now in your court, and your directory page is live, capturing (and updating every ~15 minutes) your plugin files, as uploaded into SVN.

    Tip: Before applying for a SVN repository account, be sure to create a “homebase” for your plugin on your own website. Evident on such a page would be the reason the plugin exists, what it does, a general overview, and perhaps detailed documentation. Make the plugin downloadable already from your own website. You want the plugin to be able to stand on its own 2 feet before it can be hosted in the WP Plugin Directory.

    On the application form, the “Plugin URL” field, while optional, is where you’d put a link to your plugin’s information/home page on your site. Also, give some thought to how you name your plugin on that form (more info on that down below).

    (…Part 2 continued below…)

Viewing 7 replies - 1 through 7 (of 7 total)
  • Thread Starter WatchCount.com

    (@watchcountcom)

    14 years, 3 months ago

    “Trunk Method”
    The common method of publishing your plugin is to “tag” (define) a formal release version of the plugin, amongst all the other historical versions of that plugin that you’ve uploaded to SVN for development, testing, or release. From your WP Plugin Directory page, people can see and download earlier versions of your plugin that you’ve tagged.

    However, another strategy exists: You can opt to make only the latest version of your plugin available by abstaining from tagging your releases, keeping the latest/current live version in your SVN ‘trunk’ folder (don’t put your dev/test version there!), and noting your readme.txt file with “Stable tag: trunk” instead of “Stable tag: 1.2.3”. You might like the simplicity of this method in keeping only 1 version of your plugin available for download.

    Plugin Download
    A few things about the big red “Download” button on your repository/directory page: SVN will automatically wrap your files into a .zip file for download, so you never need to deal with zipping yourself. Also consider linking your “Download now” link on your own website to this WP-hosted .zip file instead of maintaining your own separate .zip file. It looks like the download counter for your plugin will still increment when downloads of the SVN-hosted .zip occur from your own website.

    Also know that if you tag your releases, the download zip filename will include the version number, which can obviously change if you release upgrades. Example:
    http://downloads.wordpress.org/plugin/stats.1.6.zip

    If you use the “trunk method” above, your download zip filename will continue maintaining the same name, such as:
    http://downloads.wordpress.org/plugin/stats.zip

    More SVN Tips
    When you use your SVN client (like TortoiseSVN) to connect to Subversion, it’s recommended to connect via HTTPS instead of HTTP for improved security.

    While you may have subdirectories for your plugin’s .js/.css/etc. files, place your main plugin’s .php file directly into the root ‘trunk’ folder.

    Know that (as I understand it) the entire plugins repository is completely public for read-only access; you’re only asked for your password when you “Checkin” or “Commit” your plugin files for updating. You, and anyone, can download other people’s plugin files from the repository, including previous versions that may not be officially tagged as public relases and appear on the directory page. Consider everything that you upload to SVN to remain available to the entire world, until the end of the world.

    When you first get granted access to SVN, your plugin will also be assigned a certain string, like “wp-my-plugin-name” that defines your plugin in a number of places in the WordPress plugin universe. It’ll appear as part of your SVN URL, your WP Plugin Directory page URL, the download .zip filename itself, your forum tag, and perhaps a few other places. As far as I can tell, it’s a streamlined version of the plugin name you first mention in your original WP plugin submission request. For example, if you initially call your plugin “NewStuff.com Super Cool Fun Widget”, then the string derivation assigned to you will probably be “newstuffcom-super-cool-fun-widget”. Just something to keep in mind as you name your plugin.

    (…Part 3 continued below…)

    Thread Starter WatchCount.com

    (@watchcountcom)

    14 years, 3 months ago

    Readme.txt Tips
    Your readme.txt file is what defines just about everything that appears on your WP Plugin Directory page – the Description, Installation, Screenshots, FAQ, etc. It also defines plugin compatibility with different WP versions. It’s mostly just a plain text document, but you can add some basic formatting features (bold, italics, links, lists, etc.) by using a streamlined markup language cleverly named ‘Markdown’.

    The Description part of readme.txt is what’s displayed on the main/first page of your WP Plugin Directory pages. Naturally, you’ll want to put some good thought into exactly what you have to share there as you inform visitors what your plugin does. But, also know that many bloggers discover plugins right from the Install Plugins admin pages which allow them to search the WP Plugin Directory right from within their very blog. In that case, they first see a summary of your plugin — which is roughly the first 1-2 paragraphs of your readme.txt Description section. So, keep that in mind as your formulate what to say in your Description, as you may only have the first 60-or-so words to capture their attention.

    While there’s a documented syntax used within readme.txt to display screenshots inside your WP Plugin Directory page, there aren’t many (any?) formatting options. You may wish to consider instead just linking from that area to your website where you can go hog wild with screenshots and other demos.

    Plugin Installation
    If your plugin is finally listed in the WP Plugin Directory, bloggers can install the plugin right from within their blog’s Install Plugins admin pages. They’d find your plugin via an inline Directory search, then click “Install” once or twice and their blog handles the download + installation internally. There’s no need to bother folks with FTPing plugins and such, unless they have an earlier version of WP.

    As an alternative (such as if you’re not listed in the WP Plugin Directory), you can offer the option to download the plugin .zip file, and upload it into the Install Plugins page in their blog. They’ll need a newer version of WP to avail themselves of this feature (probably 2.7+).

    Plugin Upgrade
    Assuming your plugin is listed in the WP Plugin Directory, upgrading is best done right from within the Manage Plugins admin page, with but a simple click (or two). That’s all. While I’m not completely sure of what happens behind the scenes, I would image that simple file replacement is all that is done, with your new plugin files overwriting the old ones. (Naturally you’ll need to make sure your plugin is written to interact with the blogger’s WP DB properly after it’s been upgraded.)

    For plugins not listed in the WP Plugin Directory, I’m not sure the best way to guide users into a clean plugin upgrade, aside from file replacement via FTP. The “upload a .zip file from within WP method” seems to fail on trying to replace the plugin files, citing that the plugin “already exists” (…yes, it does, and we want to replace it with a newer version…).

    Forum Tag
    In the WordPress Plugins and Hacks forum, you get a special tag reserved for you — the “SVN string” mentioned earlier. AFAIK, if anyone posts a new thread/topic in that forum with the first tag being that string, then the Topic Title gets prepended with “[Plugin: Your Formal Plugin Name Here]” for easy review. This all happens automatically when clicking the “Got something to say?” link in the sidebar of your WP Plugin Directory page and is meant to give quick access to support threads about your plugin within the larger Plugins and Hacks WP forum — as if you had your own subforum there. (Example: our WP forum tag.)

    (…Part 4 continued below…)

    Thread Starter WatchCount.com

    (@watchcountcom)

    14 years, 3 months ago

    Other Tips
    When plugins are installed in a blog, the Manage Plugins admin page lists each plugin with a description. That description is pulled from the header of the main plugin php file. Cool tip: you can include some basic HTML there, such as <a> link tags, <strong> for bold, and some others, to spruce up the description and hold your bloggers’ hands as you guide them to learn the ropes of your new plugin. Your plugin’s entry on that screen will likely stand out amongst the other plugins the blogger has installed since most plugins just use plain text in that description area.

    Version numbering: WordPress recommends (maybe even requires) that you number your plugin versions with numbers and periods instead of letters and spaces. I recommend you play it safe and use the same numbering format that WordPress itself uses: 1.2.3 — there are many good reasons for this.

    While there’s a new plugin compatibility system being rolled out at this time (late 2009 / early 2010) to allow people to vote on the compatibility between plugin versions and WP versions, you may wish to declare compatibility of your plugin with earlier versions of WP. To edit those pages, you’ll first to need to establish a (free) WP Codex login – this is different from your WordPress.org/SVN login+password.

    When you’re logged in to WordPress.org and are viewing your WP Plugin Directory page, you’ll see an ‘Admin’ tab with some handy SVN links, POT file / i18n info, and the ability to add more admin users (“Committers”) for your plugin.

    WP-Plugins.net – This seems to be an old site no longer maintained, and at some point replaced by the new, current shiny WP Plugin Directory. Probably not worth your time submitting there, but who knows.

    Still developing your plugin? Check out these common plugin coding mistakes.

    Wrap-Up
    Ironically I don’t have an appropriate blog to post this tips list on, so I’m dropping it here on the forums. You are more than welcome to copy all or part of it to your own blog for better visibility, provided that you credit WatchCount.com as the author, and link back to either this thread, or to our plugin. (Feel free to make minor edits to correct or clarify any of the above.) Likewise, if any WP admins are reading this and feel this could even stand alone somewhere else within the WP.org site, please gimme a holler or follow up below.

    Thanks, everyone! 🙂

    -WCC

    lorensiuswlt

    (@lorensiuswlt)

    14 years, 2 months ago

    Nice article, really helps for new developer like me..

    Thread Starter WatchCount.com

    (@watchcountcom)

    14 years, 2 months ago

    Thanks, lorensiuswlt! Glad you’re getting some good mileage from it.

    -WCC

    Meini

    (@meini)

    14 years, 1 month ago

    Thanks for the article, it was extremely helpful.

    I published my first plugin today and struggled with getting my head around this subversion thing. I am totally new to it and the more I read the Tortoise help file the more I got confused. So I thought as long as it is still fresh in my mind, I write about what I, as a total beginner struggled with and how I solved it, in the hope that it helps others in a similar situation.

    If you are the only one who works with your plugin, wich propably most of us are, then things can be really simple. So here is the recipe of what worked best for me:

    1. Read WatchCount.com’s blog (top on this page)
    2. Read a lot of the other stuff that I could find

      3. At this point I had a bit of an idea what subversioning is all about.

    3. Downloaded and installed Tortoise
    4. Created a new folder on my local machine using (Windows) Explorer. This folder acts as a launch pad for uploading files to the repository.
    5. Right clicked on that folder and clicked SVN Checkout (this command should be available after you installed Tortoise). I think at this point I was asked for my online SVN repository URL which I received in my approval e-mail. Tortoise then created a bunch of visible and hidden files and folders of which I currently use only one, the trunk folder.
    6. Put all my files that I want to publish into the trunk folder, obvioulsy that is the entire plugin. Don’t zip it, just use the loose files.
    7. Right clicked on that folder or its parent and clicked SVN commit
    8. Entered my WP login details when asked and off they went. My plugin was online and after I came back from a nice cup of coffee, there it was, amongst all the other ones!
    9. Of course the readme.txt file did not render exactly the way I thought it would and I had to make some quick changes. So, in order to update things I just edit or replace a file (in this case readme.txt) and go SVN commit again.

      10. Turtoise gives you bold symbols on your folders or files according to their status, wheathere they are in sync or need uploading.

    Obviously there is a lot more to subversioning, but this is how things work in their simplest form and if you only want to provide the latest version of your plugin this is all you need to know to get started.

    Oh and one more thing. If you get a 403 (forbidden) error, then it is probably because you forgot to capitalize the first letter of your user name or something similar. WordPress login does not seem to care about upper and lower case in the user name but the SVN does. Took me over an hour to figure out.

    Hope this is of some use to someone.
    Cheers
    Meini

    cornishsurfer

    (@cornishsurfer)

    14 years ago

    This is great, I will use this as about to upload my first plugin…

Viewing 7 replies - 1 through 7 (of 7 total)
  • The topic ‘Tips for New Plugin Developers to Help Connect the Dots’ is closed to new replies.