I’m surprised how frequently I hear this question. To me it’s rather simple, but when I explain my mental model to others I usually hear, “Oh, that’s simple!” So it seems many do not share this model.
I did a blog post on a more restricted site some years ago, and I’m doing a new version here to a broader audience. Note that I’m using Team Foundation Server (TFS) 2010 and 2012 for source code control (SCC). For that environment, here is an excellent source of information from the ALM (Application Lifecycle Management) Rangers: http://vsarbranchingguide.codeplex.com/
Train Travel
I know many of you have travelled trains in Europe or at least heard of their good reputation. For the post I’ll use catching a train from your company to the customer as the analogy. I’ll start with the case where there are multiple trains set to depart and your code isn’t onboard the train it needs to be. Then I’ll come back to the case where your code is onboard – specifically the special case where you don’t branch. (Agile code)
So your code is the passenger and its stop is the customer. And each release is a different scheduled train.
When is your code going to the customer?
So the most important question is “When is my code going to the customer?” That is, which release is it going into? And if it is like most code, it needs to not only catch that train, but ALL other trains that leave in the future.
Take Responsibility
As a developer, your value lies in the delight a customer has when they get your code. If they never get your code you’re not going to be adding value. It is your responsibility as the developer to make sure you code catches the right train and gets to the customer. Some organizations try to put systems in place because developers didn’t do it right. That’s treating the symptom. The developer is responsible – not CM, not Testing, not the Product Owner.
It is your responsibility as the developer to make sure you code catches the right train and gets to the customer.
Simple Branching Overview
To help with the conversation I’m going to use one of the simplest diagrams from one of the earlier versions of the Ranger documentation:
I told you it would be simple. So here we have the Main branch, a Development (Dev) branch, and a Release branch.
Main
The Main branch has no parent and should be the only branch that has no parent. In the diagram both Dev and Release are child branches of Main.
Release
This is the train that will leave the station the earliest.
Dev
The Dev or Development branch is used on occasion when you are about ready to have another train leave the station (i.e., you are fixing to branch again to create another release branch) and you have code that should not be on that train.
How they work together
So we have Release, Main and Dev. Let’s say that we have three upcoming releases – v1, v2, and v3. So it should be clear that Release is where the v1 code resides. And let’s say that we coding going on in Main for v2 and in Dev for v3. Here are some of my general rules or Key Points.
Key Points
- A developer’s job isn’t done until their code is in Main.
- Fix the code in the branch that will get to the customer first. Then merge back to Main. (Reverse (child to parent) integrate, don’t Forward (parent to child) integrate your code.)
- Merge back to Main as soon as possible (while you remember all the context for the change).
- The further away from Main the branch is, the fewer changes it should have. (No branch should have more change sets than Main.)
- You should branch before you certify a release.
- You should ship from the branch you certified.
- Only bugs should be fixed in branches that will go to a customer – no feature development allowed.
Those are the bullets – let’s look at these in more detail.
When your code makes it to main, then it will make all future trips to the customer. With rare exception, that is where you want your code to end up. Your job is not done until your code is in Main.
Now, when you are certifying a Release branch or plan to ship a patch/update/service pack, whatever you want to call it, out of the Release branch you should fix bugs there. That is typically where the bug was discovered – either by testing or by the customer. So check in your code there, then merge it back to main. In more complicated scenarios you might have to merge back through several other branches to get to Main. As we know, once you’re in Main you can’t Reverse Integrate (merge from child to parent) any more because Main has no parent! Now your code is safely onboard for all future departures.
Questions about the Key Points
Why is the developer responsible for merging back to main? 1) They will know the context of the change better than anyone in the event there are merge conflicts. 2) They should take the responsibility for adding value by insuring their code is on board to get to the customer and add value.
Why can’t I fix it in Main first, then merge to Release? Quality and timing. The bug was probably found in the Release branch. Even if it wasn’t, that is the first branch that will make it to the customer – focus on getting that right first. There is also a chance that the code fix in Main is not the same due to other code changes. Finally, you get it into the Release sooner so it can be tested.
Why should there be fewer changes the further you get away from Main? This is really and observation. Every time I’ve seen something different, that meant something in the environment was wrong. If you see more changes in another place than Main (with perhaps the exception of a temporary Dev branch) then you should investigate for issues.
Examples
Bug fix for next release – v1. I have a bug that needs to be fixed in v1. Fix the bug in the Release branch and perform a merge back to Main and check it in.
I’m working on a v2 feature. Check your code into Main (you’re so lucky.)
I’m working on a v3 feature. Check your code into the Dev branch. Are you done? No! It might be two months before the organization decides it is time to merge all the changes from Dev back to Main, but you should make sure once that merge is done that you are confident all your code made it.
Special Case – Agile Code
I’ve had the good fortune to work on some truly Agile projects that had Agile code. Let me define agile code by using Michael Feathers’ definition of Legacy code (from memory), “Legacy code is any code that is not covered by automated tests.” By contrast, Agile Code is code that IS covered by automated tests. The result of working with Agile Code is that you know immediately if something is broken – your test(s) broke. So you should never actually check in any bugs, maybe design flaws, but not bugs. On truly Agile projects I’ve never had more than one branch. Now you might point out, “What if you are working on large features that should get to the customer until a future release and not the current?” For that rare occasion I’ve always implemented something that would let me control whether that feature is ready to be released. I has the great side benefit that I can change my mind at the final hour – in either direction. That means I can handle, “We aren’t ready for Feature A! Pull it!” as well as “The team finished the feature sooner than expected, let’s ship it!” I’ve actually had both happen.
On truly Agile projects I’ve never had more than one branch.
Summary
So – which train does your code need to catch? Put it on that train and then make sure it is aboard all other trains by properly merging it back to the Main branch.