nythrix's picture

OpenTK versioning scheme

This has popped out before without leaving much of a trace. With 1.0 knocking at the door, I'd like to start a discussion by writing down my thoughts. Ideally this thread should give birth to a properly documented versioning scheme for OpenTK.

Major - major architectural changes, substantial parts (or all) of library rewritten or new, major changes in GL/AL/CL, breaking changes
Minor - internal changes spanning across several classes/parts of library, new bits of GL/AL/CL exposed, a large amount of bugfixes, backward compatible (unless...?)
Revision - class-bounded internal changes, "average amount" of bugfixes, added method overloads for convenience (without new functionality), backward compatible.

In order to keep it simple I propose to NOT introduce a build number, and use the denominations "alpha", "beta", "rc" followed by a number only with breaking changes.

Another proposal would include the date/time into the version signature. I'm not too keen on that basically because I never know what's happened in between. Tracking the precedent/follow up version is not simple either, if the library isn't released regularly.

I hope you have a couple of minutes to put down your idea and explain why it should/shouldn't be used by OpenTK.

Edit: use the denominations "alpha", "beta", "rc" followed by a number only with breaking changes.


Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
the Fiddler's picture

I pretty much agree with this system, with two minor alterations:

  • According to http://www.mono-project.com/Assemblies_and_the_GAC, "common practice is to update the major and minor version numbers for changes that break backwards compatibility." This means that we should not change the Minor version number unless we introduce a breaking change.
  • Moreover, we need a way to differentiate between 1.0.0-beta-2 and 1.0.0-final when all we have is a dll on disk.

With that in mind:

  1. Major - as you propose, bumped only for large, incompatible architectural changes.
  2. Minor - should not bumped. Once we break backwards compatibility, we'll have to ship and install multiple binaries (one for each incompatible version). Which means we shouldn't break backwards compatibility without a very good reason.
  3. Revision - bumped for each new backwards-compatible version.
  4. Build number - codified to reflect dev, beta, rc and final status: numbers from 001 to 099 denote alpha builds; from 101 to 199 betas; 201 to 299 rcs; and 300 is the final build.

Under this scheme:

  • 1.0.0.300 (1.0.0-final) is the upcoming 1.0 release.
  • 1.0.1.002 (1.0.1-alpha-2) defines a work-in-progress snapshot for a future 1.0.1 release that will introduce new features but not break backwards compatibility.
  • 2.0.0.201 (2.0.1-rc-1) is the first release candidate for a 2.0 release that breaks compatibility with our current API.

I'm not entirely happy with this scheme, however: the second number is pretty much useless and the build number is pretty arcane.

Another possibility would be to use dates, like this: 1.0.9.12 (December 2009, compatible with the 1.0 API), 2.0.10.09 (September 2010, compatible with the 2.0 API). I actually like its simplicity, but it also has some issues: what happens if we release more than one version per month? Use release date like: 2.0.20091201? (2009 December 01, compatible with the 2.0 API)

Finally, we need to decide whether we wish to install OpenTK into the GAC. The more I read and see, the less I like this idea as it complicates deployment both for OpenTK and for consuming applications. Even Microsoft seems to advice against placing applications in the GAC, so maybe it's best to just display the library to "Add References" and be done with it.

nythrix's picture

I have the impression that
...common practice is to update the major and minor version numbers for changes that break backwards compatibility." This means that we should not change the Minor version number unless we introduce a breaking change.
and
Minor - should not bumped. Once we break backwards compatibility, we'll have to ship and install multiple binaries (one for each incompatible version). Which means we shouldn't break backwards compatibility without a very good reason.
are directly related to the GAC. Staying out of it gives you more freedom. Personally, I like the idea of bumping minor with new GL/AL/CL releases.
Your proposed build number might look a bit cumbersome. However, if you're a normal user who uses a stable release than you won't see but a 300 trail. If you like living on the edge, then you should know what build means and how to use it.
The date might be easier to understand for the end user. However, given that OpenTK's users are developers the versioning system should reflect the changes under the hood as much as possible. 1.4.2 -> 1.5.0 sounds better than 1.0.0942 -> 1.0.0943, if you managed to include support for GL3.3 last week.
Formats for date versioning include YYYYMM, YYYYMMDD, YYYYWW (week 01-53), YYYYDDD (3-digit day of year) and more. Hence, several releases in one month are no real problem.

Icefox's picture

If I may, a version numbering scheme that I've seen used before (in Python? I dunno) is this:

Major - Changed every time there is a non-backwards-compatible change
Minor - Changed every time there is a backwards compatible change; ie, functionality added, but no old functionality altered or removed.
Bugfix - Changed every time a bugfix release is made; no new functionality added or removed, aside from bugs being gone.

This seems reasonable to me, and makes the (fairly strong) promise that any application that works with version A.B will work with version A.X for any X > B. However, it might be suited better for projects that have longer release schedules; I don't know what OpenTK's development process is like (yet).