4 Tips To Help Find the Root of a Bug in an Open Source Project

A few months ago, a friend came over to borrow my car. Since I hadn’t driven the car in a while, when he set the key in the ignition and turned, nothing happened. The engine had died. For most mechanics, this is where they begin diagnosing the problem. Using the process of elimination, and having already established the obvious checkpoints like whether gas is in the tank, they begin to listen to the sound of the car when it tries to crank.

Much like a car, an open source project comprises many components. Since source is readily available, it is easy to begin modifications to make it your own. The biggest frustration comes when you’ve built your engine, added all the bells and whistles and it just will not start up, or there’s something that is not performing right. As such, the key to finding the root to any problem in an open source project or code is to be able to peel back the many layers until you are left with the least amount of components that can be causing the problem.  

As you go through your diagnostic steps and begin debugging, here are a few tips to keep in mind:

1) Roll out your project in stages

Rolling out the project in stages creates layers that can be peeled away. In a Liferay project, these different stages can be your custom plugins, your portal-ext, authentication, cluster and web server setup, database and jvm settings. Each time a stage is completed, you can test for functionality. Once things are all put together, and you happen to run into an issue, you can isolate and test individual components. For example, should you try using one node instead of a 4-node cluster? Start undeploying hooks to see if the issue still exists. If you take something off and the issue disappears, then you know where to begin looking.

2) Document everything

It is crucial to provide detailed documentation of code that is changed as well as the order that things were performed. This will play a role in knowing where to put things back once you take the engine apart to find your root cause.

In many open source projects, you need to modify the code directly in order to make changes.  Documentation can be tedious and lengthy. With Liferay, modifying the source directly should be the last thing you do. Using hooks, plugins and the portal-ext.propeties file, you can create customizations that can be easily undeployed at a moment’s notice. This helps make it so that you don’t have to document every single line of code that you want to modify.

3) Have a repeatable test case

Be sure to have a specific step-by-step test case that can consistently replicate the issue observed. Every time you make a modification, you will want to go through the exact test case. If you have a documented test that is too general, you may not see the issue occur but might have still missed a step. Having the test case can require extra time in the beginning, but it will ultimately save you time in the end.

With Liferay programs like Selenium can be used to create automated test cases that will replicate the issue.  In this case you would build the test and run it everytime you change something.  This is beneficial because it can also be used in your QA environment to ensure that the bug does not resurface after development is complete.

4) Peel off or layer on

When does the bug occur exactly? To find out, you can either begin peeling layers off the entire system or start from scratch and begin layering on. Understanding common symptoms will allow you to peel multiple layers at a time and start from a strategic spot.

When you employ these four tips, along with the help of a good developing team, you will be able to identify the location of your bugs and get one step closer to a successful project.