Tuesday, January 8, 2008

6 Areas To Think About Source Code Management

It has been a while since my last post. I took some vacation from work to be able to spend time with my family during the holidays, and they have taken all my time. Now, I am back to work and back to post, and I will continue where I left.

I finished the year talking about seven strategies we should define before starting a software development project. In this and subsequent posts, I will give you the reasons why you should plan ahead and implement those strategies. I will not talk about specific processes or tools. You should evaluate what fits your current situation, but I will point out the things you should think about and what the relevance is for each of the strategies.

Since the first strategy I mentioned was Source Control Management, I will begin the series explaining the areas you should think about when you implement a Source Control Management strategy. I know, you are already using a Source Control Management System (SCM), but an SCM is a tool, and we are not talking about tools. Do you have a strategy on how to use your SCM? Does everyone in your team understand and agrees with your strategy? Your answer might be yes, but keep reading, you might find a couple of things you have not think about.

1. Managing Source Code Changes

If there is something you can be sure about any project is there are going to be changes. In software development, changes in a project usually translate to source code changes. Your Source Code Management strategy should establish how changes are made, and who is allowed to make the changes.

This seems very simple, and for the most part it is. However, there are certain times when things get a little bit tricky, and your strategy should define what needs to happen when things are not as straight forward as usual.

Source code changes might break the build or destabilize a feature. When that happens, you may choose to allow developers to keep submitting changes and hope for the best, or you may opt to lock your SCM database until a fix is found. Maybe, you decide on an option that lies somewhere in between. You may want to evaluate the situation and make a decision based on feedback from your build process, your development team, or the QA team.

Everything is good as long as your strategy defines what the procedure should be, your policies are consistent, and everyone buys into it. Otherwise, you will be making the decision when problems arrive, pressured by the current state of affairs, and with little understanding of the true impact of your decision.

Furthermore, the next time you run into a similar situation, you will second-guess your previous choices, and you will be tempted to handle things different. This will cause enormous confusion in your team and will increase the chances of someone making further mistakes.

You should plan for these situations, and your strategy should define how they will be handled. Allow your team to participate in the design of your strategy and listen how certain policies will impact their work, but always keep in mind that your source code and the stability of the product should come first.

2. Documenting Changes

We all know source code is going to change, but there is always a reason that triggers the change. We might be adding features, removing features, or fixing defects. Whatever the reason is, we, most likely, will forget about it in a few days.

Our Source Code Management strategy should define how we are going to document changes, so we can go back and review and understand what triggered certain change, how was implemented, and which source files were touched.

You may decide to use submission notes stored in your SCM or send an e-mail message to the entire team when a change is submitted. You may want to get fancy and create an RSS feed your team can subscribe to and receive the latest information about the on going changes to the project. Whatever you do, you need to define how changes will be documented.

I cannot tell you how many hours I wasted researching a problem going through useless submission notes because there was not a establish procedure on how to properly document a change. Most developers are very proud of their work and will spend as much time as needed documenting the changes they make. Most of the time. Until, they have to fix a critical bug the day after the application was released to create a hot-fix for an important customer.

During hectic times, good developers forget about many things, and the easiest thing to forget is to properly document changes because "in theory" it will not impact the end result. However, a few weeks after we release our hot-fix a new problem is found, we review the latest submission notes, and we cannot seem to find what might have caused the problem.

Evangelize about the importance of properly documenting changes. Create a standard template or form that will help your team to properly document submissions. Make it easy for everyone to document changes so your team can see the value.

3. Parallel Development

In any software development team bigger than, say... one developer, development occurs in parallel. Your team might be working on different features at once, work on new features might be done in parallel with the stabilization of completed features, or a team is working on the back-end of a feature at the same time as the UI layer. Parallelism is necessary to implement features quicker and more effectively.

What this really means is that changes in the source code are coming from every direction, and your Source Code Management strategy should plan for that. The bigger the changes are, like adding new features, the bigger the impact on the stability of a project.

You may decide to create separate branches for new features; you may decide all development should go to the same main branch. That is up to you to decide, but make sure your decision fits your needs and that everyone is clear on what the protocol is.

If you are using several branches for your parallel development, you must define how changes will be propagated between branches, who will be responsible for the integrations, and the exact procedure to perform a correct integration. You want to keep all active branches as close as possible to minimize integration problems. Your strategy should define under which circumstances a new branch should be created and when the branch will be considered closed for development.

Provide your team with guidelines that will help them stay as close as possible to the latest revision of the project. Ideally, they should stay as close as possible to the latest successful and stable build to minimize the impact of a bad submission on their work.

Invest on training. Provide your team with the necessary training on the SCM tools you use and make sure everyone understands and follows your strategy. Listen to your team on the policies that get on their way and make appropriate changes.

4. Rolling-Back Changes

So far, I have been talking about what you should consider and define when introducing changes in your source code. But most of the time, we forget to think about how we are going to roll-back a change that we made and is no longer necessary or caused more problems than it solved.

Your Source Code Management strategy should define how changes will be reverted. This is a tricky operation because sometimes it is hard to know what the status will be or should be after we perform the roll-back. We should define a set of guidelines that will help performing this operation in a successful way, at least, most of the time.

Everyone in your team should know how to roll-back a change they made. Provide them with the necessary training to perform this kind of operations. Make sure they understand how the tools work, and they feel comfortable using them.

5. Going Back In Time

Just thinking about it gives me the chills. All of the sudden, someone thinks is a good idea to fix a problem in an old version of your software, and you need to go back in time, get the snapshot of your project from years ago, make the necessary changes, and release a patch for an older version of your product.

Well, if your Source Control Management strategy has not planned for that, you are probably going bananas right now. You might get lucky and a simple "sorry, we cannot do that" will deviate the attention to more important tasks like getting the next release out the door. Sometimes, luck is not on your side, and your favorite sales person has already promise the fix to an important customer who cannot wait for your next release which contains the fix.

You should be able to go back to any point in time (or at least any important point in time), and retrieve the exact snapshot of your application back then. Probably, this is not the only thing you need to do, but it is a good start. If you have not defined a strategy that allows this kind of operation and proved that it will work, the chances of success are zero, null, none.

Always consider the most extreme cases and plan for them. They probably never happen, but when they do, you will be glad you have a plan.

6. Natural Disasters

Last, but not least, your Source Code Management strategy should define the policies by which your source code will be kept safe under any circumstances. Hard-drives crash, servers go down, and once in a while Mother Nature plays a trick on us.

It is your responsibility to define a back-up strategy, but most important, it is to define a restore strategy that you know it works. You can have all the back-ups in the world, but if you are not able to restore from them, they are basically useless.

Things can go terribly wrong. When that happens, we feel the pressure on our shoulders, we cannot think clearly, and it seems the world is about to end. It is not the best time to think. If we have a plan, we stick to the plan. Hopefully, we also tested the plan before we put it into practice, and we are comfortable enough it is going to work. We still feel the pressure and the adrenaline rush, but we know there is light at the other end, and it feels good.


The source code you produce is the most important asset you have. You have to define how you are going to manage it, and how you are going to keep it safe. A consistent strategy will help your team to follow the correct procedures under any circumstances. Your team should provide you with feedback on what is working and what is not, and you should listen and evolve your strategy to insure guidelines are improved and followed.

Needless to say that an SCM system will help you manage your source; that is what SCM systems do, but you and your team should be the ones deciding which tools are good for your situation. When you decide, make sure everyone in your team is properly trained on the tools you are using. Also, make sure they actively participate elaborating your strategy. Talk to them and do not be afraid of changing policies that are not working. People learn from experience, and it is almost impossible you will get your strategy right the first time around.

1 comment:

richard said...

i want to share some thoughts about developing bugs free source code.Developers should identify the defects in their source code in the early stage of the software development process. This may help people to save more time and money arising out of software defects. Developers can use static tool like Coverity Prevent for analyzing source code for fixing defects. Using Coverity Prevent developers can fix defects like memory leak, dangling pointer, uninitialized date etc. Coverity Prevent ,
used by the Department of Homeland security to scan many open source projects.you can get more info at at http://www.Coverity.com