How should OpenBrush version numbers work?

[billyquith]

There are different ways to do this.

• https://en.wikipedia.org/wiki/Software_versioning
• https://semver.org/

[billyquith]

If we followed semantic versioning we'd only upgrade the major number when we broke something like the file format. We don't intend to do this, but we do want to show progress. There are numerous (ahem) examples of projects that upgrade the major number when they are really minor changes (Chrome, Firefox) and there are examples of projects that only increment the patch version when they have added features (SDL2). I think we should look at it something like "achievement.feature.fix".

• achievement is a major new feature which required significant work and takes the project forwards.
• feature is added functionality or refinements of current version.
• fix is minimal change to fix a bug/mistake/oversight with backwards compatibility to minor version.

Within the application we may also release API(s) which have proper semantic versioning. So, say we "go public" (so people need to depend on support and consistency) with an HTTP protocol to allow interaction with Javascript (or whatever), externally to OB, we could apply semantic versioning (properly) to this (because there are rules!)

So we might release OB 1.2.0, with HTTP API 1.6.0. But OB might be quite stable so there might be OB 1.3.0 which only adds HTTP API 1.7.2. I.e. the versions are independent of each other.

[mikeage]

Strictly speaking, semantic versioning is not currently relevant for Open Brush; the first item in the spec states (https://semver.org/#spec-item-1):

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.

That objection notwithstanding, I think that the guideline of "major version == achievement" is a sensible rule of thumb.

We currently increment the third number for each automated build; I think that's valuable, although perhaps we might want to consider a -rcX or -preX or -postX suffix instead. I don't particularly care which method we adopt; I don't much care for how CI integrates with the name "patch" but is really "minor contribution" instead of "minor release", but I admit that I don't have a better formally defined alternative.

[billyquith]

We maybe don't need a patch number. Build number is enough.

[TimAidley]

The original Tilt Brush dropped the '1.' bit from the start of its version numbers at around version 7 or so, and just incremented in whole numbers for each release, with minor numbers for bugfix releases. My feeling about version numbers is that the major.minor.bugfix type of numbering really works best for software where you buy a specific version of it. So for instance you buy FunctionNamer 3, and that gets you some minor updates in FunctionNamer 3.1 and 3.2, and bugfix updates in FunctionNamer 3.2.1, but once FunctionNamer 4 comes out, you have to pay for it again (maybe with a discount). What this means is that the choice of major version is driven by creating repeat sales for users who want the latest version. I think with something like Open Brush the major version doesn't need to be gated in quite the same way, and the Chrome / Firefox / Tilt Brush system makes more sense.

…

On Mon, 16 Aug 2021 at 12:25, Bill Quith ***@***.***> wrote: If we followed semantic versioning we'd only upgrade the major number when we broke something like the file format. We don't intend to do this, but we do want to show progress. There are numerous (ahem) examples of projects that upgrade the major number when they are really minor changes (Chrome, Firefox) and there are examples of projects that only increment the patch version when they have added features (SDL2). I think we should look at it something like "achievement.feature.fix". - achievement is a major new feature which required significant work and takes the project forwards. - feature is added functionality or refinements of current version. - fix is minimal change to fix a bug/mistake/oversight with backwards compatibility to minor version. Within the application we may also release API(s) which have proper semantic versioning. So, say we "go public" (so people need to depend on support and consistency) with an HTTP protocol to allow interaction with Javascript (or whatever), externally to OB, we could apply semantic versioning <https://semver.org/> (properly) to this (because there are rules!) So we might release OB 1.2.0, with HTTP API 1.6.0. But OB might be quite stable so there might be OB 1.3.0 which only adds HTTP API 1.7.2. I.e. the versions are independent of each other. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#160 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA65PGVEEKLWCG5QTHBMPDLT5FQ2JANCNFSM5CILFJNA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .

[billyquith]

If we make a major version with significant changes there may be bugs. We might release minor bug fixes for the previous major version. We could have beta versions, but you end up with the same issue: a different major version and two versions that you are fixing. Many projects have a "bleeding end" and "stable" release, OB has experimental flag but I believe we want to get rid of this and roll the experiments into optional configuration. And doing large structural changes with gated code is a just a minefield.

[mikeskydev]

To be honest i forgot that TB incremented it's major often! I think that might be a good example to follow, and users are going to be more receptive to that versioning if Tilt Brush used it.

One of the things that might be worth considering is the versioning of the .tilt files, which i guess in a sense is a kind-of public facing API? Should this be versioned alongside Open Brush or should we take care to maintain as much backwards compat as we can? I believe .tilt was versioned against TB itself previously.

[TimAidley]

There is versioning in .tilt files, but the version did not get updated with every release - only when something in the file format changed.

…

On Mon, 16 Aug 2021 at 13:32, Mike Nisbet ***@***.***> wrote: To be honest i forgot that TB incremented it's major often! I think that might be a good example to follow, and users are going to be more receptive to that versioning if Tilt Brush used it. One of the things that might be worth considering is the versioning of the .tilt files, which i guess in a sense is a kind-of public facing API? Should this be versioned alongside Open Brush or should we take care to maintain as much backwards compat as we can? I believe .tilt was versioned against TB itself previously. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#160 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA65PGQT5HXNKKIS6UJ6HD3T5FYVXANCNFSM5CILFJNA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .