Improve versioning

[johnkslang]

There was a request to have glslang versioned with a major.minor.patchlevel triple. Since this is primarily associated with glslang as a SPIR-V generator, that's essentially what the triple will version, but will also reflect the validator and both GLSL and HLSL inputs to making SPIR-V.

(Something similar was being done by a client-side hook, which stopped working and is fragile because it depends on the client machine.)

So, planning to look at the existing issues around versioning/tagging, as well as industry standard practice, and have some discussion here. Should look something like the following:

In major.minor.patchlevel:

• patchlevel should go up in value with each bug fix, possibly being the number of commits that have been made to the repository
• minor would go up with added functionality (or fixes that a big enough to be considered adding functionality)
• major would likely be the current SPIR-V generator version, which is currently bumped for potentially backward incompatible code generation changes (but maybe is not sufficient to capture backward incompatible changes in how the front-end interprets shader source)

Current behavior of -v is to print this, which already includes the number of commits (defunct, currently at 2000, see https://github.com/KhronosGroup/glslang/blob/master/make-revision) as a patch level, and the SPIR-V Generator Number proposed as the major number:

Glslang Version: Overload400-PrecQual.2000 12-Apr-2017
ESSL Version: OpenGL ES GLSL 3.20 glslang Khronos.Overload400-PrecQual.2000 12-Apr-2017
GLSL Version: 4.60 glslang Khronos.Overload400-PrecQual.2000 12-Apr-2017
SPIR-V Version 0x00010200, Revision 3
GLSL.std.450 Version 100, Revision 1
Khronos Tool ID 8
SPIR-V Generator Version 4
GL_KHR_vulkan_glsl version 100
ARB_GL_gl_spirv version 100

Command-line options should change to:

• --version as a synonym for -v, with the first line of output containing the major.minor.patchlevel triple
• -dumpfullversion print just the bare major.minor.patchlevel triple
• -dumpversion synonym for -dumpfullversion

Any input?

[linuxturtle]

I very much like where you're going with this. Thank you for considering it! At what point would you tag the git repository? From a packaging standpoint, it would be great if you could simply tag when you think the major/minor numbers should change. That makes it quite simple to create a reproducible version string like you describe above for any commit with:

git describe --tags | sed 's/\(.*\)-.*/\1/'

[jeremy-lunarg]

This looks pretty good.

There's a semi-continuous-delivery model at play with respect to the Vulkan SDK. We don't deploy every commit but we try hard to minimize surprises when it comes time to deploy an SDK. That said, we'd like a way to enumerate each commit in the versioning scheme; even if each commit isn't deployed. This would let us integrate glslang into the Vulkan SDK at an arbitrary cadence.

If the patch level correctly reflected the number of commits, then I think that would work for us.

[dneto0]

Your definitions for the major.minor.patch lines up well with "Semantic Versioning" https://semver.org/
(which seems to be very popular). Using SPIR-V generator number seems good.

As for the mechanics (not sure if you were asking about this aspect):
I see Glslang's make-revision updates a source file. That's stable in the sense that everyone gets the same thing. But I think that would also entail making a lot of commits in order to keep it up to date (?).

For SPIRV-Tools, I opted to use a script to generate an include file at build time (and it's not checked into the source tree.) That generated version string can be queried via an API call.

Details: a script reads the v2018.2-dev line in the CHANGES file for the analog of the major.minor parts, and incorporates the git hash of the commit you're on as the least-significant part of the version number. Git hashes are not sequential so a commit count would fit better with semantic-versioning.

Note: When I incorporate Glslang and Shaderc into the Android NDK, the integration flow uses merge nodes, so the same content in this GitHub repo would end up with a different commit count (and git hash). Not sure if there's anything we can do to fix that.

I've had feedback with SPIRV-Tools and Shaderc that for shared libraries, people want a SONAME that uses semantic versioning. I haven't implemented that.

[dneto0]

Another question is how to treat the dependency on SPIRV-Tools transforms for HLSL legalization. Sometimes bugfixes or enhancements arrive via that channel.

[dneto0]

Three more data points about semantic versioning itself.

• Google's abseil library (core C++ libraries, open-sourced) does not use semantic versioning. Titus Winters has strongly-held arguments against semantic versioning. See his CppCon'17 talk (starting 18 minutes in) https://www.youtube.com/watch?v=tISy7EJQPzI&feature=youtu.be&t=18m00s . Key criticisms:
  • You can't always tell what's a breaking change; and
  • Semantic Versioning gets roughly quadratically difficult to satisfy in a system with a large dependency graph.
• the Angular library just started using semantic versioning, as better than what they had before: https://opensource.googleblog.com/2016/09/angular-version-2-proprioception.html
• LLVM and Clang stopped making 3.x releases and ceased their weak compatibility promise. Now each release (every 6 months) gets a new major version, no matter what.

Overall, I think semantic versioning is probably a net win, but ¯_(ツ)_/¯

[johnkslang]

FYI, I was earlier using this for a commit number:

#!/bin/sh
...
echo \#define GLSLANG_REVISION \"`git describe --tags --abbrev=0`.`git log --oneline | wc -l`\"
...

But, with a client-side hook, which is too fragile, with multiple machines and committers.

[johnkslang]

Another question is how to treat the dependency on SPIRV-Tools transforms for HLSL legalization. Sometimes bugfixes or enhancements arrive via that channel.

Since the SPIRV-Tools getting used changes infrequently compared to commits, it makes sense to bump the minor number for each update.

[johnkslang]

FYI, I'm moving to having the semantic versioning in place, but separating that aspect (basically, policy) from final decisions on automation and other mechanisms in general. Current mechanism can be considered a placeholder, but want the basic versioning in place.