Wednesday, February 4, 2015

My First Open Source Contribution!

I have been wanting to get involved in an Open Source project for awhile now but have always felt it was no small undertaking and if I am honest, a little intimidating. Either you have to build a project from scratch, get involved in a project at its inception or get involved in a project that is already in development. Each of these options requires a lot of effort with the later probably being the most popular option.

Whilst working on a pet project where I was attempting to build dynamic reports / dashboards I was using the Jquery.Sparklines charting framework for my inline charting and I noticed that the bullet chart was not working as I was expecting it too. The line and bar charts allowed me to specify a min and max value at initialization to define the value range that the chart would be displaying. This would set the scale for the chart so it made visually comparing charts possible as they were all render using the same scale. Strangely, the min and max values for the bullet chart were being ignored with max value for each chart being determined by the max value from the values supplied to be displayed by the chart. This resulted in each bullet chart having a different scale and made visually comparing bullet charts impossible.

Inspecting the Jquery.Sparkline source code revealed that it was not checking if a min and max value had been specified. Instead, it was determining the min and max range for the chart from the values supplied to be displayed by the chart.

min = Math.min.apply(Math, values);           
max = Math.max.apply(Math, values);

Looking at how some of the other charts handled this, I saw the pattern in use was a ternary statement which checks if a min or max value has been specified, if so use this, otherwise determine these values from the data values supplied. My update using this pattern looks like this:

min = options.get('chartRangeMin') === undefined  
  ? Math.min.apply(Math, values) 
  : options.get('chartRangeMin');
max = options.get('chartRangeMax') === undefined 
  ? Math.max.apply(Math, values) 
  : options.get('chartRangeMax');

Now the bullet charts are rendered with the same scale as they all have the same max value specified and a visual comparison is possible.

In the context of my report, the bullet charts now give a much better visual report of how students are performing against one another.

Creating a Pull Request in GitHub was surprisingly easy, especially now that a forked branch of a project can be used in the pull request as you no longer require any privileges on the project that you want to contribute to. It's made the whole process pretty much ceremony and friction free. For details on how to make a Pull Request from a forked branch check out this tutorial.

You can find my pull request here.

It's a very small update and contribution but it's a start. There is additional logic being applied to the min value which would need further consideration and possibly lead to a modification to my pull request but it's the start of a conversation with the project owners at the very least.

I have learnt that it is important to find an Open Source project that you have an interest in when searching for projects to make a contribution to. It's even better if you have a vested interest because you are using the project or are looking to use the project. Previously when looking for projects to contribute to I was looking at shiny new projects instead of looking at projects which I was using.

Contributing to an Open Source project can also help you improve your coding skills as it gets you reading other people code. I picked up a number of patterns and coding techniques whilst perusing the Jquery.Sparklines project that are worth further consideration and study.

If you feel getting involved in an Open Source project is a little intimidating you are not alone there. Find a project that you are interested in (and preferably use) and start by making a small contribution (bug fix, test code, documentation). As they say, "from small beginnings come great things".