Ruby on Mail

Contributing to TMail

Here is a blunt truth, TMail is what we (that is you and me) make it.

I have had a few people asking how to contribute to TMail, so I thought I would quickly do a write up on how to go about it.

First things first, go to the TMail Mailing list and subscribe and let us know what you want to attack, while this is definitely not a requirement to writing a patch, maybe someone else has the same problem and / or is mid fixing it, plus, we're basically a nice bunch of people ;)

Then, if you are new to this sort of thing you should go and read this great write up by Dr Nic which covers the basic steps on how to check out, patch and submit fixes to code. This also applied very well to TMail.

Then, you need to get a copy of the latest TMail trunk code. You do this like so:

baci:~ mikel$ svn checkout tmail

This will check out the most recent version of TMail from the source tree at RubyForge. Once you have this, the first thing you should do is run the test suite. There are over 4000 assertions run by the test suite to make sure all is OK. This also gives you a stable datum of "When I got it, it was working so I just have to make sure it stays working...". To run the tests, do this:

baci:~ mikel$ cd tmail
baci:~/tmail mikel$ rake test
(in /Users/mikel/tmail)
/usr/local/bin/ruby -Ilib:test ((SNIP))
Loaded suite /usr/local/lib/ruby/gems/1.8/gems/rake-0.8.1/lib/rake/rake_test_loader
Finished in 0.456426 seconds.

204 tests, 4014 assertions, 0 failures, 0 errors

If you get any errors at this point, post to the TMail Mailing list and let us know, tell us what version of Ruby you are running, and what platform you are on as well as any error output from the tests. If you can fix it, go ahead!

Now that you have the trunk version, you need to write your patch and submit it. If you are making a code change, you should write a test driven change, if you are new to this, you can find a great screen cast by James Edward Gray II on TDD with Textmate. This will give you the basics of what a test drive change is and how to go about it. For all you RSpec fans, I am seriously considering moving the testing framework over to BDD and RSpec, if you want to get on board and help out, that would be great!

Once you have written your test, run rake test again and watch it fail. This is a key part of Test Driven Development. Then write your change in the code.

Once you have written your code, run rake test again, and your test should now pass and every OTHER test should also pass. If this is the case, then well done! You have just made a test driven change to the TMail library.

Now you need to make the diff file of what you have done against the library. You do this using the svn diff command. First however, you should update your code, just in case someone else has updated the source tree between you checking it out and writing your patch. So, you do both like this:

baci:~/tmail mikel$ svn up
At revision 206.
baci:~/tmail mikel$ svn diff > my_well_named_patch_file.diff
baci:~/tmail mikel$ 

Note: If while doing the SVN UP anything was updated, you should re-run your tests using rake test to make sure your patch didn't just go stale :)

Next step is peer review. Go open a patch ticket on the RubyForge tracker, in it, select the right category and group for the patch you have made (if there isn't one that matches, leave it as none and then mention this in the description field). Give your ticket a name, and then attach your file.

It is a good idea to then go to the TMail Talk list and let everyone know about your patch. Then we can check it out, suggest changes or commit it if all is good.

That's it! Easy hey? Once you have submitted patches, it gets easier and you get to bask in the glory of being a committer to Ruby's most popular mail handling library.