Watching all github forks

I like watching what other people do with my code. It often gives me ideas about how to improve the API or what features to add. I can also get a feeling of what the user thinks of my code: if he uses it differently it's an indicator that he either doesn't agree with my design choices (whether they were conscious or not!) or he's struggling to understand some of the concepts, which I may have left implicit or undocumented. In a nutshell: a different perspective.

For code published on github, this is easy to do: just watch the forks. But I always seem to miss some fork, so here's a script that watches all forks in a github network:

You can get your github API token from https://github.com/settings/admin

Going further, I like doing these reviews from gitk. So here's another script that adds all repositories in a network as remotes:

I then run a "git fetch --all" and browse the commits in gitk.

Of course, this works on networks with relatively few forks or not a lot of activity. YMMV.

An overview of my OSS projects

Some time ago I was talking with Michael Maddox about OSS project visibility and long-term maintenance, and one of the things he pointed out is the importance of having a central place that lists all your OSS projects. Not only that, but also which ones are active at any moment. I fully agree with him.

A profile page at ohloh does just that. Ohloh sorts projects by last commit date, and it shows a nice commit activity graph for each project, so you can see exactly what anyone is working on at any moment (provided that he/she has registered the projects on ohloh, of course).

Github profiles also sort projects by last commit and show activity by project and by contributor.

Still, I think it's worth posting a summary every once in a while for reference and maybe even raise awareness about the projects, since most of them are little and quite specific. So allow me to toot my own horn for a bit and list my projects so far:

• SolrNet is probably my best-known project. It's an Apache Solr client for .NET. I started it back in 2007, and the latest release as of this writing was a couple of months ago. Docs are on Google Code, binaries are available also on google code and via NuGet. Over the years the project got contributions from many people. Thanks!
• SolrIKVM is an Apache Solr server for .NET. It uses IKVM to port Solr Java binaries to .NET. I explained the rationale behind this project in a recent blog post. It's not production-quality yet. I don't expect to spend much time on it but I'm willing to help if interested people are willing to collaborate.
• GDataDB is a database-like interface to Google Spreadsheets for .NET. I wrote this back in 2008. Last year it got some attention and patches and I released another version in October 2010. Binaries are available on github and via NuGet.
• Quartz.NET web console: an embeddable web manager for Quartz.NET (a job scheduler) I wrote last year. Binaries available on github and NuGet.
• NHibernate web console is another embeddable web console for NHibernate-based web applications I wrote in 2009. It lets you query and browse your NHibernate-mapped database directly from your application. Binaries available on github and NuGet.
• Boo web console: yet another module that embeds Boo in your web application. I wrote this one back in 2009. Basically, with this you can run any code within your live web app. Binaries available on github.
• OpenX.Net: .NET client for the OpenX API, one of the most popular open source ad servers. Written in 2009. Binaries available on github and NuGet.
• ElmahFiddler is a little module that adds a Fiddler SAZ trace to ELMAH error mails. I wrote it about a year ago, and even though I didn't officially release it and haven't touched it in a few months, I've been using it in production and is stable.

On the F# front, I've started a few projects. This is where I'm currently spending most of my OSS time.

• Figment is a web framework inspired on Sinatra and Compojure. Original blog post here.
• FsSql is a functional wrapper around ADO.NET. Blogged here and here. Recently released 0.1, available on GitHub and NuGet.
• FsFormlets is an implementation of formlets based on the original papers. I wrote some articles about formlets recently, and I'll write some more in the near future.
• CsFormlets is a layer on top of FsFormlets that makes it usable on C# and VB.NET. I still have to blog about this one.

I've also been a proud member of the Castle team since 2009. Although I haven't really contributed much code to the core projects (only the occasional patch), I've been more in a support role, answering questions from users on the mailing list and stackoverflow about just anything Castle-related, writing articles about it, helping migrating Castle to git.

I also wrote some Castle-related projects:

• Quartz.NET integration for Windsor: as the name says, it's a Windsor facility that integrates the scheduler Quartz.NET. Blogged about it here and here.
• Castle.Windsor.Lifestyles: additional lifestyles for Windsor, blogged about it here.
• Castle.Fax: the first OSS project I wrote, back in 2007. It includes a facility to integrate Windows Fax Services, which can run on a client or a server. It also includes an IMAP monitor so you can send faxes via email, and a web manager to check the state of the fax server. I haven't touched this since 2009 and I no longer use it (and nobody else, it seems), so I guess it qualifies as a dead project.

As a contributor to other projects:

• FAKE: I added support for Gallio and some other things that I needed to replace MSBuild in SolrNet.
• GitSharp: I had a brief participation, helped automating the build and setting up continuous integration.

Most of my projects grew from scratching my own itches and are in production, except the F# projects which are more research-related. This doesn't mean they're not production-worthy, they just have a different origin and focus.

Browsing open source code history

There is a killer characteristic of open source that seems to be often overlooked: the ability to browse the source code history.

This will sound trivial to many, but it's something that I've seen a lot in questions asked on stackoverflow.com and other forums. People ask: "why has feature X changed?" "Why am I getting an exception P since I upgraded project Q to version R?"

The first thing you need to do is assume there is a good reason for that change and set out to find it, instead of considering it a bug in the OSS. Keep yourself humble, remember that the people working on OSS are generally very smart and really know what they're doing.

And the really generic answer to such questions would be (without any intention of being harsh): you can usually find out yourself.

An example: this stackoverflow question (here summarized):

In the previous version of NHibernate (2.0.1) the following property will validate:

internal virtual BusinessObject Parent
{
  get { /*code*/ }
}

However, in 2.1 it errors saying that the types should be 'public/protected virtual' or 'protected internal virtual'. Why is this requirement now there?

Now I've been using NHibernate since 0.83 but I'm no expert in NHibernate internals. Despite that, I was able to answer the question by doing this:

1. Check-out NHibernate's source.
2. Grep the source code for "public/protected virtual". Only result is NHibernate.Proxy.DynProxyTypeValidator.
3. Go to NHibernate's Fisheye, browse to DynProxyTypeValidator.
4. Browse the file's history, starting from the latest diff (at the time of writing it's this one), looking for changes in the proxy validation exception message.
5. Only two diffs back I find the relevant commit.
6. The commit message says:
   - Fix NH-1515 (BREAKING CHANGE)
   - Minor refactoring of proxy validation stuff
7. Go to NHibernate's JIRA. Browse to NH-1515. Read the issue description.

That's it. No special knowledge needed. This process could be further simplified by using Fisheye's search instead of locally grepping (but I never seem to get good results from Fisheye) or getting NHibernate from github instead of svn and then grepping with git-grep or gitk. Browsing history with svn is so painfully slow that I prefer to do it with Fisheye.

By the way, this is the same approach I use on closed code at work when my boss asks me "Hey, this feature used to behave differently! When and why did we change it?" (and this happens a lot)

This is where best practices like specific commit messages, atomic commits and good issue tracking really pay off.

Documentation? I save that for stuff that this approach can't possibly handle.