Dr Nic

[Trick] Live Version Numbers on your blog

There isn’t much connecting your open source projects – written in one language and possibly stored on a SourceForge/RubyForge server – to your blog – written in some other language and stored on a different server. Pity.

Sure, you can list your available projects/gems/plugins/libraries on your sidebar, and that’s great for new visitors but what about the old warhorses? What about the people who actually use your code? It would would be snazzy to inform them if a new version of your projects was available.

Sure you can spam your entire subscription list about every minor update. And during the lean weeks, you might just do that so people know you’re alive. But you’re a professional, and you want something cool. Something automatic and, dare I say it, magical.

Today, we’ll just do automatic. Tomorrow, soon maybe, we’ll all share a newer, improved magical version! Kazzam!

Screenshot of site - 16th August 2006If you look on the sidebar of my site – http://drnicwilliams.com – you’ll see the dubiously short list of my projects – Composite Primary Keys and Dr Nic’s Magic Models. Your keen eyesite will notice version numbers next to them. On the assumption I’ll change the site one day, here is a screen shot…

The version numbers are not stored at http://drnicwilliams.com – they are both stored at their respective websites: http://compositekeys.rubyforge.org and http://magicmodels.rubyforge.org. This is the super best part – once I start a new project and add it to the list on the sidebar, I never need to touch the blog templates again. Automatic. Almost magical.

Tourists and weary travellers can check if a new version of any project is available whenever they visit the site. If they don’t visit the site because they use feed readers, then now they have a reason to visit the site. Weird logic. Look, the next release of this idea will be so super cool that all your readers will just HAVE to come to your site. I promise. Perhaps you can flog some advertising. Anyway, your mother will be impressed.

How do I get sweet Live Version Numbering love for my projects?

What follows below will work for your 100k line mega-framework down to your 10 line Rails plugin. As long as you can create and modify one file on your project’s website.

Let’s call that file version.js, and give it the following innards:

var myproject_version = "0.7.1";
document.write(" - " + myproject_version);

This is a small Javascript program that you will run within your blog to generate the version number. Its separated on to two lines so that it will be super easy for you to change the version number whenever you need to in the future.

Let’s say you’ve saved this file at the web address: http://www.myproject.org/version.js

Now, modify your blog to include your homebrew wizardry. Go to the templates, and edit the sidebar, or wherever you already have your projects listed. NOTE: if you currently have the projects generated for you from a blog list (like in WordPress) then you’ll need to stop using the list generator, and hand craft the html yourself. Be a man, its only one time.

For me, my original html for the two projects was:

<li><h2>Open Source Projects</h2>
	<ul>
	  <li><a href="http://compositekeys.rubyforge.org">Composite Primary Keys</a></li>
	  <li><a href="http://magicmodels.rubyforge.org">Dr Nic&#039;s Magic Models</a></li>
	</ul>
</li>

To get the Live Version Numbers working make the following changes:

<li><h2>Open Source Projects</h2>
	<ul>
	  <li><a href="http://compositekeys.rubyforge.org">Composite Primary Keys</a><script src="http://compositekeys.rubyforge.org/version.js" type="text/javascript"></script></li>
	  <li><a href="http://magicmodels.rubyforge.org">Dr Nic&#039;s Magic Models</a><script src="http://magicmodels.rubyforge.org/version.js" type="text/javascript"></script></li>
	</ul>
</li>

Let’s call this Cross-Site Scripting; other people do. If the javascript wasn’t coming from a known site – your project site – it’d be considered a security problem.

So now you have Live Version Numbers working, what do you do if you release a new version of one of your projects? You change the version number in the version.js file. You score extra points if your release mechanism can automatically update this value for you.

The future of Live Version Numbers – the Magic Edition

What your readers really want is an “in your face” notification or dropdown box if they need to know about a new version. Yes you could do a dedicated RSS feed instead/as well, but we’re trying to impress people here. RSS isn’t impressing anyone: if they understand it, they’re not impressed; if they don’t understand it, they’re not impressed.

So, the future version will include cookie support and magical information boxes to inform each individual visitor about changes to projects. This will definitely be magical. Your mother will know her school fees did some good.

Related posts:

  1. GitHub Badge for your Blog with 100% guarantee of more coolness The killer app for JavaScript in the 90s was...
  2. newjs = newgem for JavaScript projects; free TDD suite Want to start a new JavaScript project for a library...
  3. Auto-completer for my blog comments It took 4 hours to return from the town of...
  4. [Trick] Natural language DSL in Ruby Ever tried to explain DSLs (domain specific languages) to someone,...
  5. Yehuda Katz starts a blog Yehuda is the creator of autoDB – the wonderful admin...

3 Responses to “[Trick] Live Version Numbers on your blog”

  1. Matt Scilipoti says:

    Thanks for Magic Models and sparking my imagination with more ideas like this.

    1. The Magic Edition – Awesome. I love pages that inform me of changes since I last visited.

    2. Creating a convention for retrieving the Version of your Products/Projects makes it easier for you AND me to query for it. I can now programmatically compare my local version against the published version. Thanks.

    3. IMHO, I would like to keep the formatting in the sidebar – not my projects. It’s the view’s responsibility and… I don’t want to parse out the format du jour when I grab your version.
    Solution: That just requires a quick tweak to your method (move “-” to sidebar, remove from version.js). If you want to DRY up the sidebar formatting, you could make a local script.

    4. IMHO, whether you call it Cross-Site Scripting or not, it seems wrong to run a script from another server just to retrieve a version number. I hope this feeling isn’t coming from my “Web 1.0” comfort-zone.

    Possible solution: How about creating a page in our project that just returns the version number (html, xml, json)? We could then populate the sidebar values during Server-side rendering or using Ajax.

    4a. Retrieve versus Populate: This also makes it easier to create a Project Version page that programmatically retrieves the current version when the page is requested. A Rails View would work nicely for this – even handling many content types so you could request the Version in whatever format you want. I would much rather request the version (cached where necessary) than be forced to ensure the version.js file was updated every release. An Automated build will just automate the step, not eliminate it. Besides, I know how to Test the Page.

    4b. Or… this could all be unnecessary complexity. I have been known to indulge in that area from time to time. I acknowledge that it happens, but haven’t quite grown the skills to recognize it each time. Reviewing 4a makes me wonder if I also have the dreaded “buildophobia” (cured only by adequate test coverage).

    Retrieved or populated, I see merit in some variation of the Version Page becoming a convention. Can a RoR plugin be far off?
    –Thanks again, Matt

  2. Dr Nic says:

    @Matt – I certainly dumbed down the example to get straight to the point at the cost of better design. The next version will use a version.js/xml/yaml file that just returns the value and the UI will do more local processing to produce the nice effects on the blog.

    The idea of 3rd parties pinging for the version number is also very cool – just like a feed reader polls for new articles on an RSS feed every 15 mins or so. Especially if projects adopted a convention – e.g. all have a version.xml file with the same schema.

    This being the case, it would make more sense for version.js to be replaced or partners with a version.xml file or version.yaml.

    I still like the inherent fun of embedding data within a snippet of loadable code. The data only coming to life when the javascript is executed :) If the version.js was instead an RJS call to your rails app, then instead of executing document.write(VERSION), you might want the RJS code to execute a local update function:

    page.version_manager :update, @new_version

    which would execute the following JS at the client:

    VersionManager.update('0.8.1')

    And you’d just need to provide the VersionManager.update callback function in a library.

    If it were your server and 3rd parties wanted to call your RJS action, but they wanted to be able to specify their own callback action in the params, then you are now being super sexy. The 3rd party can easily use your RJS action for XSS without having to do any processing of data. They just insert and the resulting JS will invoke their VersionManager.update callback function with the result.

    Remember, you can’t use Ajax to request data from a 3rd party site, so XSS is sometimes all you’ve got. AdSense uses it – probably the most pervasive use of XSS in the world. No callbacks, no interaction – you just trust google will execute nice JS on your site.

    So, even if the solution includes providing a version.xml file, 3rd parties may want a configurable callback action option anyway, just because that’s all they can use on their own site.

    Now we’re getting complex – we’re providing 2+ ways to get the data (xml and callback invocation). That’s ok if you’re generating the two files (the callback method would be hardcoded here). But really, what we’d like is for RubyForge to generate these values for us from their own data. Then we wouldn’t need to write an explicit version.js/xml file at all!!

    Sniff. I smell a good idea here. First person to write a public wrapper for RubyForge’s Release values per project file, that provides 3rd parties with raw XML and YAML release version strings, and a configurable callback method action, gets extra Christmas presents.

    It makes too much sense for someone who wants to release a micro-public utility site themselves NOT to do.

    You also get an extra Xmas present if you convince Ruby Central to provide a nice API into their RubyForge database.

  3. Dr Nic says:

    Ok, more thoughts.

    An API for providing access to data to 3rd parties would need to provide the following variations:

    1. Raw data – XML/Yaml/JSON; useful by 3rd party servers that can retrieve data from 3rd party sites – your site – and manipulate and send it to their clients
    2. Javascript callback; called within XSS context only – – your returned javascript invokes a callback function on the 3rd party site. Best to allow the option of the 3rd party specifying the name of the callback, though this makes caching harder.
    3. Variable setting; user as per #2, but the returned javascript sets a known variable with the returned JSON value. Why? So that you can now access within your own inline javascript. E.g. if the variable VERSION is upated with a version value, then a 3rd party might use the following: <script src=”http://yoursite.com/getdata”></script> <script>alert(“Current version: ” + VERSION);</script>

    I think I first saw this triplicate of XSS API options on http://cocomment.com but I can’t find it on their site now.

    These three API versions should be supported by the same controller action – they access the same server data – and the required value might be selected by a params setting: context = raw/callback/variable.