Releases, tags, branches, etc

[ernestojpg]

Hi all,

If I understood correctly this project is a fork of the original varnish-modules one, that will try to keep the project up-to-date.

Regarding this, I have a couple of questions:

1. Could you please move the tags from the original repository so that we still have the original versions of the project? (0.15.0, 0.14.0, 0.13.0, etc)
2. Is there any plan for releasing a new version of the project with latest changes?
3. Will you follow a different version convention for avoiding clashing with the ones in the original repository? Specially if you want to keep different branches for each of the main Varnish versions (6.0, 6.1, 6.2, etc)

Regards.

[nigoroll]

Hi @ernestojpg

1. I have pushed the existing tags to this repo

2. Right now, my main focus is to provide a version of varnish-modules which works with newer versions of varnish-cache. As such, I would think that it includes all the latest changes. Could you please let me know what exactly you are asking about?

3. Yes, so far I have kept version-specific branches as opposed to the approach to make a single branch compatible with different varnish-cache versions.

[ernestojpg]

Hi @nigoroll !

1. Thanks for pushing the tags from the old repo!
2. Currently the project has 4 main branches: 6.0, 6.1, 6.2, and master, but no new tags/releases have been created yet, so we don't know when we should consider the branches stable enough. Also, imagine that I wanted to create a binary package or docker image with the code in branch 6.2. What version should I put to my package/image? just 6.2? Note that what we have in branch 6.2 today could be different to what we will have tomorrow, as it is a branch. In this case, if not tags/releases are created I will have to call my package/image something like 6.2-20190904, which is fine. My question was if you were going to create tags like 6.0, 6.1, 6.2, 6.2.1, 6.2.2, etc (or any other versioning convention that you decide) or you wanted to continue using only branches?
3. Is it your intention to backport new features in the master branch into older branches such as 6.0, 6.1, or 6.2? Or new features will only be in master?

By the way, congratulations for your great work with this module.

Regards.
Ernesto.

[nigoroll]

Hi Ernesto,
to answer 2 & 3 combined: So far, the sole purpose of this repo has been to make the vmods available for newer varnish-cache versions than what the upstream repo supports. Until now, there were no plans to maintain new features not present in the upstream.
This has just changed yesterday as I have merged the first feature only present in this repo and not upstream.
Looking forward, we will decouple this repo more, and you are absolutely right that we should tag releases. A convention like 6.2.1 would, IMHO, clash with varnish-cache release versions, so something like 6.2-0.16.0 would seem sensible to me. Suggestions welcome.

[slimhazard]

There's an unfortunate conflict between tagging/versioning the present fork, and maintaining the versioning from upstream. Tbh I don't what the hell to do about that.

I strongly recommend making no attempt whatsoever to make the VMOD version names resemble the Varnish version names, with something like 6.2.1-0.16.0. Just don't do it. Because:

• It's not uncommon for VMODs to remain compatible across a stretch of Varnish versions. Most of the time, when there is a range of micro version numbers (like 6.0.0 to 6.0.4, or 6.2.0 to 6.2.1), it's rather unlikely that the VMODs do not remain compatible (particularly if they declare $ABI vrt). And sometimes a VMOD doesn't have to change even for major Varnish version changes. So importing the Varnish versions into the VMOD versions would be messy and unnecessary -- we could easily have multiple version names pointing to the same commit level.

• A format like 6.2.1-0.16.0 is asking for trouble with code that parses version names. In particular, it's smart if the versioning of distro packages such as rpm and deb matches the version names in the git tags; and systems like rpm & deb are rather strict about the version format (they usually expect a single release sequence number after the -). I suggest the format $major.$minor.$micro and nothing else, it's as close to universal as this sort of thing can get.

• Speaking of rpm & deb & friends, they are much better at expressing compatibility relations between versions. Let them do it with their Requires and Provides and so on, rather than try to build the info into version names.

• There's nothing wrong with branches in a VMOD repo such as 6.0, 6.2 etc that correspond to the Varnish versions (which are also on branches in the varnsh-cache repo). Since a tag for the VMOD version that's meant to be compatible with a Varnish version will usually tag a commit on one of those branches, it's not hard to tell what goes with what.

• If a version gets tagged for compatibility with a Varnish version, announce it in the git -a -m message. These are easy to find. git show $tagname tells the story, and the git-hosters, such as this here web site, list it all for you. Look on the "Releases" tab of a github project, or the "Tags" link of a gitlab project.

[slimhazard]

So IMO (sorry, I can't stop with this), make the VMOD versioning all about what goes on in the VMOD project itself. And document compatibility with Varnish versions by other means.

Most projects with APIs these days seem to be settling on the "semantic versioning" concept:

• bump the minor version when the API change is backwards but not forwards compatible
• bump the major version when it's not backwards compatible
• bump the micro version when the API doesn't change

Since a VMOD presents an API to VCL authors, I think this is just right.

[ernestojpg]

Hi @nigoroll , @slimhazard ,

Thanks for your comments.

Imagine that you want to release version 0.16.0 of this project (or maybe something like 1.0.0 if you wanted to decouple it from the original varnish-modules repo), and you have all features ported to the three branches, 6.0, 6.1, and 6.2. You will need three different releases/tags, right? one for each branch. How would you call each of the three releases/tags? As @slimhazard said, I would not use the Varnish's micro versions because the VMOD will probably remain compatible across all of them.

I would suggest to at least add a reference to the major varnish version that this VMOD is compatible with. For example:

• 0.16.0-uplex60
• 0.16.0-uplex61
• 0.16.0-uplex62

Or if you want to decouple this VMOD from the original varnish-modules repo, we could use, for example:

• 1.0.0-60
• 1.0.0-61
• 1.0.0-62

What do you think?

Thank you very much for this debate :)

Regards.

[slimhazard]

@ernestojpg, I too appreciate the conversation, so I hope you'll take it as friendly and respectful discord when I still say Just Say No. %^)

I didn't say don't use Varnish's micro version numbers, I said don't use any part of the Varnish version number at all in the VMOD version numbers. Absolutely positively none of it.

The format you've suggested interferes with the versioning schemes used by RPMs and deb packages, and install tools like rpm, yum, apt and dpkg are unforgiving about the version format. If a package version doesn't follow their rules, then it will not work with the install tools.

Both RPM and deb expect a format like this (deb also has an optional epoch prefix):

$major.$minor.$micro-$release

The $major.$minor.$micro part is expected to match the versioning of the software being packaged. $release is a single, increasing decimal number starting from 1, and it is bumped when there are changes related only to the packaging itself, not the software being packaged. So if $major.$minor.$micro stay the same but $release increases, then the thing inside the package hasn't changed, but something about the package build has been fixed or improved.

Again: yum and apt & friends will refuse to work with packages that don't follow their naming scheme. So the suffixes -60, -61 etc get in the way; or else versioning for VMOD packages will have to use some kind of workaround, so that the package versioning is necessarily different from the VMOD version; which would be Not Good.

Also, using -60, -61 and so forth implies that there necessarily has to be new VMOD versions for at least different minor versions in Varnish. But as I said, that's not always true for a VMOD. It's quite possible for a VMOD to be compatible with Varnish over all of 6.0.x through 6.2.x, for example. And even across major Varnish version changes. It wouldn't surprise me if there are VMODs right here in varnish-modules that haven't had to change since Varnish 5, or even further back than that.

On the other hand, maybe a VMOD version does have to change due to the change of a Varnish micro version. That's unusual, but it certainly can and has happened. In that case, a -60 portion of a VMOD version number meant to identify the Varnish version number wouldn't be precise enough.

Whether or not a VMOD has to change due to changes in the Varnish major, minor or micro version is quirky and unpredictable. It depends on what the VMOD does, and which parts of the internal Varnish APIs it uses (Varnish development has little compunction about changing internal APIs that break VMODs). That largely depends on what the VMOD is for, and they're all different.

"I want to see the compatible Varnish version number in the VMOD version number" is a short-sighted goal, doesn't see through to the bad consequences or the range of actual possibilities, and attempts to solve a problem that is much better solved by other means.

Worth mentioning that I've run into many of these problems over the years, and have learned the hard way that the "Varnish version in the VMOD version" idea is fundamentally flawed from the ground up. We can avoid a lot of headaches by getting it right from the start. I admit that I'm ranting here a bit (more than a bit), and that comes from not wanting to predictably repeat a mistake that I've regretted in the past.

So, Just Say No. I'm not saying use 0.1% or 0.01% of Varnish version names in VMOD version names, I'm saying use exactly 0.0%. Never ever, none whatsoever, never again.

[ingvarha]

This of course popped up again with the newly released varnish-6.5.0.

I maintain varnish and varnish-modules in Fedora. I'm considering switching to this repo as upstream for my varnish-modules package. As expected, I'm also a bit puzzled on how to work with modules on different targets.

First, the %release tag in rpm may include any alphanumeric and a few other characters, meaning schemes like these are valid:

varnish-modules-0.17.0-0.2.klarlack.git.4d6593c2.fc32

or even

varnish-modules-0.17.0-0.2.klarlack.git.4d6593c2.varnish650.el8

From my egoistic point of view, the best had of course been if a main branch with timely releases had just compiled against all supported variants of varnish. Then, while building the package, I may just make the varnish-modules package depend on the varnish version it is built against.

Keeping different version combos of varnish/varnish-modules in different repos, yum/dnf will figure out the rest while installing.

This way I may happily forget about using the varnish version in the varnish-modules package name.

Ingvar

(Btw, rpm also has the concept of epoch. It is just seldom used, and avoided when possible)