We are trying to decide on a good way to do version numbering for software components, which are depending on each other.
Let's be more specific:
Software component A is a firmware running on an embedded device and component B is its respective driver for a normal PC (Linux/Windows machine). They are communicating with each other using a custom protocol. Since, our product is also targeted at developers, we will offer stable and unstable (experimental) versions of both components (the firmware is closed-source, while the driver is open-source). Our biggest difficulty is how to handle API changes in the communication protocol.
While we were implementing a compatibility check in the driver – it checks if the firmware version is compatible to the driver's version – we started to discuss multiple ways of version numbering.
We came up with one solution, but we also felt like reinventing the wheel. That is why I'd like to get some feedback from the programmer/software developer community, since we think this is a common problem.
So here is our solution:
We plan to follow the widely used major.minor.patch version numbering and to use even/odd minor numbers for the stable/unstable versions. If we introduce changes in the API, we will increase the minor number.
This convention will lead to the following example situation:
Current stable branch is 1.2.1 and unstable is 1.3.7. Now, a new patch for unstable changes the API, what will cause the new unstable version number to become 1.5.0. Once, the unstable branch is considered stable, let's say in 1.5.3, we will release it as 1.4.0.
I would be happy about an answer to any of the related questions below:
- Can you suggest a best practice for handling the issues described above?
- Do you think our "custom" convention is good?
- What changes would you apply to the described convention?
Best Answer
IMHO version numbers are like product names; important in that they're visible but unimportant in that they're decoration rather than content.
Still the version number, like a product name, carries meaning. And the most important thing you can do is avoid confusion. So here are some common expectations with respect to version numbers. To the extent that these exceptions are not met, the user will probably be confused:
Version numbers are monotonically increasing
This is probably the most obvious expectation, and at the same time the least likely to actually be true. At-a-glance, the user expects that version 2.3.5 comes after version 2.2.17, and has the same or better technology. But of course 2.3.x is a development branch, and 2.2.x is stable, and 2.3.5 actually was release back in 2004 and the 2.2 branch is still actively being worked on and 2.2.17 was released just last April and contains... well, you get the idea. You might as well just call version 2.2 "Potato" for all the meaning that the number carries. Welcome to version "Potato-17"!!
Similar Versions are Upgradeable/Compatible
If I have version 3.7 on my computer, and 3.8 comes out with all new shiny frozbots, I expect that with some upgrade or patch or whatever, my 3.7 can become 3.8 with no interruption. But if I'm on 3.7 and you release 5.2, I'm not so optimistic. Of course, I'd rather be pleasantly surprised rather than disappointed.
The first digit is significant
I wouldn't even bother to mention this if Java wasn't so prominently confusing on the matter. Unless someone told you, you would not expect that "Java 7" was actually version 1.7. And the first time you heard this, you response was almost certainly: "What? .. Why?"
Clearly the purist will say that the major version number will only change if the platform change is not backwards-compatible. But do you actually intend to drop backwards compatibility ever? Often major version revs are a marketing decision not a technical one; the Java absurdity comes from both camps having it their way at the same time, to almost comical effect.
Finally
As I just mentioned, version numbers are often as much about marketing as they are about technology. And that's OK, since that's kind of what version numbers are for: the inform you at a glance as to what's new about the software. Big number change means big functionality change. Small number change means almost no functionality change. That's what people expect. Whether it's true or not determines whether or not your version numbers carry the same meaning that your users think they do.
-- EDIT --
I forgot to mention this, but Caleb pointed it out nicely: Don't use version numbers to indicate anything important (e.g. stable/unstable) without making it otherwise explicit elsewhere. Yes, you know that the odd minor version number indicates development, but that makes one of us. Debian's "unstable" release moniker is a good example; or you could also use a totally separate product name; "Frozbot 1.2" for your product name, and "Devbot 1.3" for your development version.