Tuesday, August 4, 2009

Branches and Versions

A new public release will be coming tonight, to fix a Windows-crash reported by a few people. This "bugfix release" is going to be kind of a new thing for us, so I wanted to take a moment to explain how we're handling these bugfix releases and how it affects versioning.

In case you missed the earlier post on PeerBlock Versioning, the "R Number" of a release isn't actually a release number - it's the revision number of the source-code used to build that release. These numbers are used by the source-control system we in the dev team use to coordinate our efforts, and are incremented each time we a change is "committed". So this revision number identifies the exact state of the source-code at the time a release was built, and makes it easy for us to find the version of code to look at when troubleshooting problems with released versions.

Historically, each PeerBlock release has contained every change committed to the source-control tree, so r52 included every change since r33, and r71 included every change since r52. This is about to change.


For this upcoming bugfix release, we're in an interesting position. We have a fix that we want to get out to the public because it fixes a critical problem, but we don't want to release all the changes we've made since r71 because they haven't been tested enough yet and may introduce yet more bugs. So what do we do? We "branch" the code.

Imagine that the program's source-code is like a tree. We initially start out with one continuous stream of changes - this forms the trunk of the tree as we move up. At some point though, we reach a point where we want to have two different sets of source-code changes. The code now branches off in another direction so that we have two versions of the code both "current" at any given time, the "trunk" and the "branch".

That's what we'll be doing here. The Trunk version of code is where all the latest-and-greatest (and potentially unstable) changes are going. The "0.9.x Bugfix Branch" is where we'll be putting only the code we absolutely need to fix bugs in the 0.9.1 release, like this one.

With me so far?


Now most people are familiar with progam versions, so when you see PeerBlock 0.9.2 coming out tonight you'll know that obviously comes after the 0.9.1 that you're running. And when PeerBlock 1.0 comes out later on, you'll know that is a later release than 0.9.2.

The problem comes in with these "R Numbers" though. Remember, they tell us the specific version of the code used to build a particular release. The problem is, they're shared amongst all branches in our source-code "tree" - this means that if we make a change in the "trunk", our rev is incremented. If we then make a dozen more changes to the trunk, our rev is incremented a dozen more times. If we then make a change in the "0.9.x branch", our rev is incremented again.

So What Does This Mean To Me?

What this all boils down to is that our new shiny PeerBlock 0.9.2 release will have an "R Number" of probably r86 or so. And even though this number is way bigger than the r71 of PeerBlock 0.9.1, it doesn't actually include many of those 14 changes that went in, because it came from a different branch.

Going forward, it also means that one given R Number does not necessarily have more stuff in it than a lower R Number. For example, let's pretend we released a r81 Interim Release. This release would have been built from trunk, and would have contained a whole lot of new features. We then came out with v0.9.1 (r86), built from the 0.9.x branch. r86 is a bigger number than r81, but r81 actually is the "newest" build, since it has more new features built into it.

So don't trust the R Numbers anymore. Think of them as a name, and that's about it.

        --- Mark ---


  1. K cool, now I also know how software development branching works! :D
    Keep up the great work, Mark!

  2. This comment has been removed by the author.

  3. You guys are great. Seriously. I have been using PG2 since Vista first came out and have struggled to get it working in even a halfway functional manner. It's really great that you are building off the Phoenix Labs source. I'm definitely looking forward to 1.0 which I assume will include a driver signature ;)
    EDIT: Thumbs up on using boost.

  4. I agree with Praeses, you definitely just made my day with this explaination of versioning! :D

  5. Cool, glad to hear that you guys appreciate posts like this! I was kinda on the fence about this one - on the one hand I wanted to try and explain things well so that people understand what's going on with the stuff we put out, and on the other hand I wasn't too sure if anybody would actually care. =;)

    And Derek, thanks for the kind words. I'm pretty happy with how far we've come in such a relatively short time. And yes, I'm also hoping we'll be able to collect enough donations by version 1.0 to afford to sign that driver...