Mistakes to make your Gem a PITN

Because of course we all have pains in the neck and nowhere else. And let me warn you: the timeframe in this post is messed up because I wrote it in the past week or so trying to avoid ranting every day; so when I say “today” or “yesterday”, it’s quite relative

So I’m still going on with the ports to ruby-ng of the dev-ruby ebuilds; I gave priority to the packages that are needed for Typo (which is the software I use for this blog) so I could also test them properly first hand. The results aren’t excessively bad I’d say, actually the space wasted on my server was reduced; I had to make a fix to my remove-3rdparty Typo branch to be able to use the new will_paginate gem (since the new version in gemcutter does not have the mislav- prefix like the one from github had), but the result is, after all, not bad at all.

As I said before there are quite a few common problems with gems that I’d like to point out, so that future Ruby Gem developers will try to avoid repeating such mistakes:

• missing licensing information, or too much licensing information: while Gentoo is definitely not Debian, nor we’re Fedora, and thus we tend to have a much more “relaxed” approach in term of licensing for all the packages falling out of the system set (since we don’t redistribute binaries but only sources), it’s not really that nice when a package is lacking all kind of licensing information, or where the LICENSE file and the README file provide conflicting licensing information;
• missing tests, specs, or missing data files: I found quite a few gems that don’t package their tests (or specs if they use rspec), or that package the spec files but not the datafiles they use; this is quite a problem since it makes the package unverifiable; this gets even more nasty when the files are not even in the upstream repository!;
• bogus build-time dependencies: this almost happened today with addressable (even though, kudos to its author, addressable itself is quite nice to work with!), as gemcutter reports a build-time dependency over launchy … and indeed it’s there, in declaration; on the other hand the only thing it’s used for is opening the rcov output in a browser, and that’s not even needed to run the Rakefile; the bottom-line is that I didn’t need to push launchy and configuration in the main tree (both had the previous noted problems) even though the gems declare them as needed — this is one reason why I don’t think we should “auto-generate” ebuilds;
• single version dependencies: if you only allow a precise version of another gem to be used with yours, you’re going to play catch-up ad infinitum to make sure that your gem is usable; Hans was bitten by this with cucumber, and I sidestepped it in activewebservice for Typo, since the gem required Rails 2.3.3 (or 2.3.4 depending on the version) while I wanted to run the last secure one (2.3.5);
• fork the code like bunnies: this is probably caused by the bad habit of GitHub to propose forking code continuously; the already-mentioned actionwebservice is quite problematic from that point of view: 2.3.3 version was released by datanoise, 2.3.4 by dougbarth and we now got two possible gems for 2.3.5;
• use a not maintained documentation system: while RDoc is almost standard in the Ruby world, I found two packages last night (sinatra and rack-test) that use an alternative system based on haml: Hanna which unfortunately only works with an older version of RDoc; for this reason, the documentation for neither is built and installed.

There are probably more common mistakes that you have to look forward for in the future, but this at least is the first list, although it’s probably rehashing most of the stuff I have ranted about in the past.

And one important announcement here: if you care about Ruby 1.9, you should know that we’re currently in a huge mess: a lot of code fails tests with Ruby 1.9 so I’ve been dropping support for it everywhere it cannot be tested. Similarly it happens for JRuby, even though for different reasons often. And to test all the packages to re-add Ruby 1.9 when needed is going to take quite a bit of time. For this reason, you really should either try to help out by testing it yourself, or find a way to support us through the job (I can be hired for the task).