Re^2: Versioning modules in a package

Major: XX - this incremented only when the external interface to the code was changed or extended.

Midor (middle order): YY - Zeroed when the Major version increments.

Minor: ZZ - Incremented every time a modification was made that made no changes to internal or external APIs.

This looks like a great numbering system; I think I'll give it a try.

It's interesting to compare your XX.YY.ZZ system with Perl's major.minor.patchlevel system. Obviously, "midor" releases of Perl tend to change the external interface, although most old code seems to run fine. Major releases are few and far between, with no guarantees of backwards compatibility. Bugfix releases are fairly rare, which is kinda nice -- the interesting thing about fixing bugs in a language is that it does change the external interface, though not the way it's specified.

There's also the hidden semantics of the "midor" number's parity, where an even number indicates a "production" release and an odd number a "development" release. Until now, I'd never really thought about it, but on further reflection I don't like it. The "hidden" field annoys me. There's no reason not to cat on a "-devel" or "-release" tag on the version number -- or at least, none that I can think of.

It seems like your numbering scheme works best when there are a moderate number of releases and a lot of refactorings going on, and especially with internal-release code that isn't going to be used by the world at large. Putting the midor number (internal changes) ahead of the minor number (bug fixes) strikes me as a developer's way of doing things; customers wouldn't notice the internal API changes, but damn straight they'd notice the bug fixes. Perl's versioning system seems better for a slower-paced project, with lots of undocumented (at least in the version number) internal-development releases and a few major public milestones.

Here's another question: how does this sort of thing apply to a file format? After a very little reflection, it seems to me that every change in a format's syntax or semantics deserves a "warning - old files are probably incompatible" numbering change. Adding new stuff to the format -- provided that most parsers will be clever enough to warn-but-ignore stuff they don't understand -- won't break compatibility in the same way, so new features deserve only a minor increment. But that's bass-ackwards from the way I tend to think about version changes! What gives?

-- F o x t r o t U n i f o r m Found a typo in this node? /msg me % man 3 strfry

Comment on Re^2: Versioning modules in a package

Replies are listed 'Best First'.
Re^3: Versioning modules in a package by BrowserUk (Patriarch) on Oct 04, 2004 at 22:39 UTC
The odd/even number midor builds denoting development and maintainance tracks isn't that unusual. It serves to solve the parenial problem of separating the two which is essential for a developing product. You can only really avoid it once a product moves in to "Maintainance only" status. In a nutshell, this is to solve the problem, that having just released a version; say 5.8(.0), you have four sets of changes to track: Bug fixes arising from customer discovery. Bug fixes from internal discovery. New and/or modified internal apis. New and/or modified external apis. You need to be able to apply the first two to the last released build so that it can be sent out to customers with forcing them to wait for a new midor release to be tested, packaged and released. This allows small fixes that only affect a single file to be sent as just that file without compromising compatibility. If changes to internal or external apis are involved, it requires shipping a complete set, which effectively means a full release. To accomodate the two tracks, it is necessary to fork the codebase. Whilst 5.8-maint and 5.8-devel are possible, it makes life hard in all sorts of small ways to have alpha designations. The consistancy (my favorite watchword) that comes from sticking with the same numbering scheme by going the odds/evens route can simplify many things. Personally, I think I favour .50 nomeclature. At the release of 5.8, the codebase is split into 5.8.1 and 5.8.50--maintainance and development respectively. In a very large project, a 3 digit minor might be required, but usually not. On the file format thing. If the file format changes in a way that is not backwards compatible. The interface has changed. That is a major version change. If within the existing file format semantics, new syntax can be added such that it will be parsed by older parsers, but not be functional, this is an internal api change. A midor increment is called for. Changes that correct mis-interpretations of the existing syntax or semantics to bring them in line with the published api's are minor changes. The fly in that ointment is the case of a discrepancy between the published api and the way the parser parses the file, where the erroneous behaviour is found to be useful, or even preferable to the documented behaviour. In this case, the answer depends on who discovers it, how big a customer they are, and how many others will complain if the documentation is brought in line with the code rather than the other way around. Pragmatism rules here. The classic example of this was when DEC tried to drop support for a little known (and used) hybrid real-time/time-sharing OS they had called IAS (if memory serves?). Three customers complained when the announcement went out. DEC very pragmatically negotiated an agreement with the 3 customers that they would pay somewhat more for their service agreements in order to keep maintanance team going for a further 10 years. A very pragmatic decision when the three customers were General Electric, General Motors and the US DOD! I may have misremembered the details, but the basis of the story is true Examine what is said, not who speaks. "Efficiency is intelligent laziness." -David Dunham "Think for yourself!" - Abigail "Memory, processor, disk in that order on the hardware side. Algorithm, algorithm, algorithm on the code side." - tachyon	[reply]

Replies are listed 'Best First'.

Re^3: Versioning modules in a package
by BrowserUk (Patriarch) on Oct 04, 2004 at 22:39 UTC

The odd/even number midor builds denoting development and maintainance tracks isn't that unusual. It serves to solve the parenial problem of separating the two which is essential for a developing product. You can only really avoid it once a product moves in to "Maintainance only" status.

In a nutshell, this is to solve the problem, that having just released a version; say 5.8(.0), you have four sets of changes to track:

Bug fixes arising from customer discovery.
Bug fixes from internal discovery.
New and/or modified internal apis.
New and/or modified external apis.

You need to be able to apply the first two to the last released build so that it can be sent out to customers with forcing them to wait for a new midor release to be tested, packaged and released. This allows small fixes that only affect a single file to be sent as just that file without compromising compatibility. If changes to internal or external apis are involved, it requires shipping a complete set, which effectively means a full release.

To accomodate the two tracks, it is necessary to fork the codebase. Whilst 5.8-maint and 5.8-devel are possible, it makes life hard in all sorts of small ways to have alpha designations. The consistancy (my favorite watchword) that comes from sticking with the same numbering scheme by going the odds/evens route can simplify many things.

Personally, I think I favour .50 nomeclature. At the release of 5.8, the codebase is split into 5.8.1 and 5.8.50--maintainance and development respectively. In a very large project, a 3 digit minor might be required, but usually not.

On the file format thing.

If the file format changes in a way that is not backwards compatible. The interface has changed. That is a major version change.
If within the existing file format semantics, new syntax can be added such that it will be parsed by older parsers, but not be functional, this is an internal api change. A midor increment is called for.
Changes that correct mis-interpretations of the existing syntax or semantics to bring them in line with the published api's are minor changes.

The fly in that ointment is the case of a discrepancy between the published api and the way the parser parses the file, where the erroneous behaviour is found to be useful, or even preferable to the documented behaviour.

In this case, the answer depends on who discovers it, how big a customer they are, and how many others will complain if the documentation is brought in line with the code rather than the other way around. Pragmatism rules here.

The classic example of this was when DEC tried to drop support for a little known (and used) hybrid real-time/time-sharing OS they had called IAS (if memory serves?). Three customers complained when the announcement went out. DEC very pragmatically negotiated an agreement with the 3 customers that they would pay somewhat more for their service agreements in order to keep maintanance team going for a further 10 years.

A very pragmatic decision when the three customers were General Electric, General Motors and the US DOD!

I may have misremembered the details, but the basis of the story is true

Examine what is said, not who speaks.

"Efficiency is intelligent laziness." -David Dunham
"Think for yourself!" - Abigail
"Memory, processor, disk in that order on the hardware side. Algorithm, algorithm, algorithm on the code side." - tachyon

[reply]