Friday, May 28, 2010

Attention Open Source Developers...

When you keep contributing to an open source project, the project community will eventually reward you by granting you committer rights. However most open source committers don’t realize that committership is a big responsibility. The moment you become a committer of a project, you become responsible for each and every line of code in the project code base. Every single change you make to the project source code affects other committers in the project and all the people around the world who use that software. Therefore as a committer you should stick to some kind of a policy or a code of conduct which governs how you make changes to the project source code. The following is a list of items that I think should be in such a policy. I’m not implying that I have always followed this policy in the past. Rather, I always try my best to stick by it:
1. Before anything else, if your contribution involves API changes, you MUST take the matter to the project mailing list. You MUST NOT make any API changes without notifying your fellow committers and the user base. Sometimes you might feel that the API change you are about to do is rather small, unimportant and trivial. For an example you might spot a spelling mistake in a method signature and feel the urge to correct it immediately. But still, an API change is an API change. If somebody’s using the misspelled method, your change will break his/her code. Also some developers tend to think that certain interfaces in the code base are “not so important” and nobody is using them, and therefore it is ok to make changes to them. Developers like that don’t really understand open source. The truth is there are no unimportant APIs in open source projects. When you make project source code open, you are basically inviting the rest of the world to use that code, develop on top of the APIs to do whatever they want with it. So even though you don’t know it, there could be hundreds of people out there who use the “unimportant” interface you are about to change.
2. Always crate an entry in the project issue tracker to keep track of your contributions. Almost every open source community maintains an issue tracker. At Apache and at WSO2 we mainly use Atlassian JIRA. Whenever you are about to make a change to the source code, consider creating a new entry in the issue tracker before you check-in the patch. In my opinion there are only two excuses for not creating an entry in the issue tracker:
  • Adding some descriptive comments to the code (note that comments and Javadocs are two different things)
  • Refactoring some private attributes or private methods of a class (eg: renaming a local variable)
Once you have created the entry in the issue tracker, make sure you get it assigned to yourself. Once the relevant changes are checked-in to the code base, mark the entry as resolved. It doesn’t look very professional when you have dozens of open tickets which are not assigned to anyone. It is also not nice to have tickets in the work-in-progress mode, even after it has been fixed on the source code.
3. While making changes to the source code, always follow the coding conventions accepted by your project community. If you come across any badly written or poorly formatted code fix them then and there. Refactor as you go. However do not make any functional changes, which are not relevant to the problem you are attempting to solve. If you come across old functional issues while fixing some other issue, report them on the issue tracker and leave them to be fixed in a future iteration. Generally it’s not a very good idea to solve multiple problems by one commit. That can make things harder to keep track of.
4. When you are actually committing a patch to the code base, make it a point to properly log the changes you are about to check-in. I often commit code into the Apache Subversion repository and WSO2 Subversion repository. Whenever I make a contribution, I always add a couple of lines to the SVN commit log, describing my changes. If it is like a rather large patch, I would mention a summary of the changes in bulleted point form. Also in your commit log message, you MUST mention the ID of the corresponding issue tracker entry. This can really help you track down changes in the future. At Apache and at WSO2 we have integrated JIRA with the Subversion repository. Whenever someone checks a bit of code into the SVN, with a JIRA ID in the commit log message, the relevant JIRA entry gets updated with the information related to the commit (see example). This makes it really easy to identify all the changes done in the source code to resolve a particular issue.
So there you have it! In my opinion, every open source developer should adhere to these key guidelines, whenever making a change to the project source code.
Having said that, an open source committer should never feel uneasy, to make changes to the project source (unless it is specifically restricted by the community - as in the case of a release). If you have done some changes to the code, and if you are confident that the changes you have made are accurate and necessary, you should feel free to check them into the code base. Same applies for patches contributed by the non-committers as well. If a patch solves the problem at hand to a satisfactory level without violating the boundaries of the current design, committers should take necessary steps to check it in. The solution doesn’t have to be “perfect”. At Apache we follow a commit-then-review (CTR) policy, most of the time. This model enables developers to get code changes into the project as early as possible, without worrying too much about the impact they may have on the project. Once the changes have been checked-in, they can be reviewed and fine-tuned as necessary.
However, during my career I have come across developers who at times leave issues open for weeks just because the available patches are not ‘perfect’. While the patches provide a satisfactory solution to the problem at hand, these developers always manage to find some small, irrelevant limitation in the patch, which can be easily fixed in a future iteration. They make it an excuse to not commit the patch. These developers, unfortunately, haven’t grasped the true spirit of open source. They don’t realize that the whole point of open source is to attract as much contributions as possible and correct any problems they might have, as we go on.
Before I wrap up, I’d like to reemphasize that open source committership gives you great power and authority over your project. We all know what comes with great power. Yes, it’s “great responsibility”. So use your powers with care and caution!

Thursday, May 20, 2010

A Different Experience...

Last week, I got the opportunity to visit yet another interesting part of the world – the Middle East. I have been to the Dubai airport before, while on my way to United States. But transits don’t count, right? So last week I visited the city of Amman, the capital of the Hashemite kingdom of Jordan. I was there for a whole week. It was not the trip I expected, but in a really good way.
Let’s start with the weather. I was expecting the weather to be burning hot with tons of scorching sunlight. It turns out the weather over there is actually better and far more comfortable compared to the usual weather in Colombo. The temperature is almost as same as in Colombo (around 30 degrees Celsius) but the humidity is nearly 0. So it’s actually very comfy. And during the nights the temperature would drop to something around 18 degrees Celsius resulting in some very cold nights and mornings. I also learnt that they have the usual four seasons over there at Jordan. They even get some snow showers during the winter. Who knew?
The city of Amman is indeed one of the largest, most developed and beautiful cities I’ve ever been to. It’s very clean and tidy for a capital of a country. I was kind of surprised to not see much pedestrians walking around the town. But the roads are always full of vehicles all the time (even at midnight). So I guess pretty much everyone owns a vehicle. I also got to see quite a number of Ferraris and Porches storming the highways. I also realized that travel costs are actually very low in Amman. You can get a taxi anywhere and travel about 4 km for 0.75 Dinars (~ 1 USD).
Amman is also full of great hotels, restaurants, cafes and various shops. Truly great place for tourism I should say. Somewhere close to down town they have a street called the ‘Rainbow Street’. The street full of night clubs, restaurants, coffee shops and book shops is a great place to go and get something to eat and chill down for a while. They also have these huge shopping malls at Amman– larger than any mall I’ve ever been to. If you ever get to the city of Amman please make some time to go and visit the Mecca mall or the City mall.
Something has to be mentioned about the people of Jordan too. They are really nice and friendly. People at Amman are always full of smiles and have nothing but nice things to say. During my short stay I was even offered a couple of lunches and one great dinner.
Unfortunately for me I didn’t actually get anytime to go and visit the real tourist hotspots in Jordan, like the city of Petra or the Dead Sea. But then again, it’s always nice to have something to look forward to.