Geeks With Blogs

Doug.Instance Improving the world one post at a time

To me the answer of whether or not you need version control is simple - do you have users?  If the answer is yes, then you need version control.  Note that "version control" is not the same as "source control".  Source control refers to maintaining history of your source code.  Version control (also known as "configuration control" or "configuration management") is more than that.  Version control, as its name indicates, means tracking versions of your software.

The best way to illustrate the purpose of version control is through a simple example:

You develop an application.  While developing the application you go through several iterations throwing away large chunks of code, refactoring, redesigning, etc.  Finally you are happy with the application and you publish it.  Just to make this example more tangible, let's say it is a web application so now you have deployed it using your favorite hosting provider.  One way or another, you get some users who regularly visit your web site.

Your users like your application, but you know it could be better.  You start a massive redesign and start to totally refactor everything.  Next thing you know, you get a message from your web hosting provider saying they are implementing new security measures and if you are doing XYZ, you will need to change to ABC by the end of the month.  The good news is this change just requires a few lines of code and the even better news is you can include this in your new version with your massive redesign.

It is now the last day of the month.  Life has happened (as it tends to) and your new version is not ready.  You now have less than 24 hours to complete a massive redesign, test, migrate data, and deploy.  Now you realize a simple truth:

THIS WOULD BE SO MUCH EASIER IF I HAD MY ORIGINAL PRODUCTION SOURCE CODE!

Now this is a very simplistic and probably somewhat unlikely situation.  After all, you probably are at least zipping up or otherwise backing up copies of your code.  There is a good chance you are doing this when you release a new version.  If you are doing that, then you are doing some version control.  However, if you don't have a process you follow for EVERY VERSION then you run the risk of running into the problem I described above.

So here are some simple rules to follow to make sure you have everything you need to properly maintain production code while continuing to develop new and exciting features.

Rule #1: Create a "Main" Branch

The idea of "branching" or "forking" may be completely foreign to you and if not, you still might not think about it if you aren't using source control.  Branching means that you make copies of your code along logical paths.  To have logical paths you need to have a begining and that beginning is your main branch.  In this case, I am referring to a physical folder typically called "Main".

The most important aspect of your main branch is that it contains EVERYTHING required for the application.  That means common code, 3rd party code, 3rd party libraries, documentation, media, etc.  This ensures that you always have the correct version of all of those external resources for that specific project.  That may even mean using local copies of assemblies instead of the GAC to ensure you can control which version you are using.  You don't want an application to sit on the shelf for a year and break because you upgrade a component that's registered in the GAC.

For me, a typical main branch folder contains the following subfolders:

  • Bin (Folder for binary references typically from 3rd parties)
  • [Project].Web (Web application source code)
  • [Project].DataAccess (Data access library source code)
  • [Me].Utilities (My common code)

Rule #2: Create a Release Branch

Copy EVERYTHING from your main branch folder to a new release branch.  Typically this would be a subfolder underneath a "Releases" folder (i.e. "Releases\1.0").

Rule #3: Don't Touch the Release Branch

No matter how trivial you think a change might be, don't make it in your release branch.  This is perhaps the most important aspect of this process - retention of your released code.  Even bug fixes which look simple on the surface can lead down a rabbit hole of problems which could cause you to end up with mangled and inoperable code - exactly what we are trying to avoid.

If you have one or two bugs to fix, branch from your release branch to another release branch (i.e. "Releases\1.0.1") and make your fixes there.  If you have ongoing development (long-term work on new features or enhancements), create a "Development" branch (i.e. "Development" folder).

Rule #4: Merge Often and CAREFULLY

The reason we call this "Branching" and not simply "Copying" is because it implies that there is a "split" in the development process.  Consider your development can go down two paths - one to maintain what is in production and one to make long-term enhancements.  Merging allows those two paths to converge into a single set of source code.

Merging simply means taking the changes from the two different branches and combining them.  You can do this manually or by using a "diff" or "merge" tool.  Manual merging means that if you make a bug fix in a new release branch, you would then make the same change in your main and development branches.  This is perhaps the most thorough method because it ensures that you make each change incrementally and indivdually.  It isn't necessarily the most efficient method and there are many tools available to allow you to merge changes to multiple files relatively easily.

So the obvious question is where do the changes actually get combined?  As I mentioned earlier, the main branch is the beginning of your logical branching path.  In fact some people refer to this as your "trunk".  All merging should happen back through your main branch.

Merge CAREFLULLY however. Your main branch should be your "Gold" copy of your application.  Only merge back to main once you are sure that your changes are complete and fully tested.  After you merge, make sure that you didn't introduce any new bugs simply through the mechanics of merging.  For example, your "most recent" version of your code may be from a recent bug fix.  However, other changes in your development branch have made the bug fix obsolete.  If you overwrite the "older" file with the "new" bug fix, you could introduce new bugs.

Summary

The basic process looks something like this:

  1. Develop your application in your "Main" folder containing EVERYTHING you need for your application.
  2. Once you are ready to release your first version, create a copy of your or "Branch" in a "Release" subfolder under a "Releases" folder (i.e. "Releases\1.0").
  3. Use your release branch to deploy.
  4. Create a "Development" branch folder as a copy of your main branch which should now match your latest release.
  5. Do your ongoing (long-term) development in the development branch folder.
  6. For bug fixes, create a new release branch from your previous release branch and make your fixes there.
  7. "Merge" any changes from your release and development branches back to your main branch.  This may require a "diff" tool.  Merge from release to development via main.  Merge back to main ONLY once everything has been tested and is ready for release.
  8. Copy your main branch to a new release branch.
  9. Repeat from step 3.

Your file structure would look something like this:

  • [Project]
    • Main
      • Bin
      • [Project].Web
      • [Project].DataAccess
      • [Me].Utilities
    • Releases
      • 1.0
        • Bin
        • ...
      • 1.01
      • 1.02
      • 2.0
    • Development
      • Bin
      • ...

References

Microsoft has some very good guidance on source control which is specifically related to Team Foundation Server, but hidden between the lines of this guidance is good version control guidance and a lot of the foundation for what I describe above.

This Stack Overflow post has a good collection of diff tools by OS and free vs. pay.

Before You Post That Comment

Note that this process is about "Version Control" NOT "Source Control".  How you would branch and merge would be somewhat different if you are using a source control system to keep track of your source code history.  The process outlined above is specifically intended to be used when you are NOT using source control.

Posted on Thursday, December 22, 2011 10:48 PM | Back to top


Comments on this post: Practice Version Control Now...Thank Me Later

No comments posted yet.
Your comment:
 (will show your gravatar)


Copyright © Doug Lampe | Powered by: GeeksWithBlogs.net