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!
No comments:
Post a Comment