VIP13: VMOD versioning

Our current best practice for versioning vmods is:

libvmod-foo-VMODVER[+GITBRANCH].tar.gz

VMODVER is a running number of versioning scheme of your choice. I suggest starting at 0.1 and bumping to 1.0 when you are happy with the code. Next big feature release is 2.0, bugfix after that 2.1 and so on. Keep going and use 2.10 if it comes to that.

To avoid coordination between branches, each branch has their own versioning sequence. (1.13 may exist both in 4.0 and 4.1.)

GITBRANCH is tied to your git/development system branch. If you only have one master branch, you can either skip it or use "+release" for future proofing and to avoid it looking like a git snapshot.

GITBRANCH should be the branch name. Underscores are not permitted. You may prefix it with "v" or "varnish" if you think that looks neater. Remember, it is the git branch name, not the Varnish major version.

The build system should be adopted for defining an ABI level that is checked at vmod build time. This check should also support a hard Varnish gitref, for vmods that uses interfaces not covered by the VRT ABI contract.

Any distribution packages (rpms/debs) built from a source package should have the built VRT ABI set as Require.

Examples:

libvmod-foo-1.1.tar.gz  (vmod-foo has a single branch called master)
libvmod-foo-1.1+release.tar.gz  (vmod-foo's master branch, others exist)
libvmod-foo-1.14+release.tar.gz  (vmod-foo's master branch, bugfix release 13)
libvmod-foo-1.15+release.tar.gz  (vmod-foo's master branch, another bugfix release)

libvmod-foo-1.14+4.0.tar.gz (vmod-foo's 4.0 branch, standalone.)
libvmod-foo-1.14+v4.0.tar.gz (vmod-foo's 4.0 branch, prefixed.)
libvmod-foo-1.14+varnish4.0.tar.gz (vmod-foo's 4.0 branch, long prefix.)

libvmod-foo-1.15+release.tar.gz
libvmod-foo-1.15+v4.0-plus.tar.gz

When a package is packaged for distribution, it would look like:

vmod-foo-1.14+4.0-1.x86_64.rpm
vmod-foo-1.14+4.0-1.deb

Goals

The source tarball name of a vmod should indicate:

• Which feature level this vmod package has.
• Which Varnish version(s) you can expect it to work with.

Discussion

Internally Varnish has a VRT (Varnish RunTime) ABI level. It is used at VCL load time to find out if the VMOD going in is compatible. Confusingly enough, Varnish 4.1 has the ABI level 3.0, Varnish 4.0 has 2.1. In practice it collides heavily with the normal Varnish version string, and as such would be very confusing for a user in a tarball name.

Skipping tarball releases and working for git directly is currently not a viable option. Tarball is the standard way to distribute open source software.

Putting GITBRANCH into the package name is possible, but you end up with libvmod-foo-v4.0.so, which is rather unruly to import in VCL.

Moving GITBRANCH before VMODVER is possible but should be avoided. It doesn't help sortability, and it doesn't make the version name clearer.