$ABI docs need clarification: which includes constitute $ABI vrt?

[nigoroll]

From a VMOD developer perspective, there should be clear and concise documentation about exactly what is allowed for $ABI vrt, namely which includes can be used. I guess the main question is really about cache.h, is it part of VRT or not? If it is was not, we would have changed the VRT version quite often in the past for no good reason (but we already know that and the decision was made as a safety measure). Also, there will be almost no VMOD which does not make use of the workspace API, so $ABI vrt would probably be quite useless for all practical purposes.

Right now, our documentation is either vague or contradictory. Some findings:

• https://github.com/varnishcache/varnish-cache/blob/master/doc/sphinx/reference/vmod.rst

If it complies to the VRT and only needs to be rebuilt when breaking changes are introduced to the VRT API, use vrt.

Yes, but which files constitute that API?

• https://github.com/varnishcache/varnish-cache/blob/master/doc/sphinx/phk/apispaces.rst#vmod-apiabi-levels

good level of detail (namely, includes the actual file names), but out of sync with reality

• https://github.com/varnishcache/varnish-cache/blob/master/include/vrt.h#L122

Might suggest that cache.h was part of the ABI

[dridi]

Might suggest that cache.h was part of the ABI

OH, so that's why I was convinced that cache.h was part of VRT until @bsdphk gave me a definitive no.

Some things from libvarnish.a like VSB are also considered VRT material.

It would be nice indeed to have this properly documented somewhere.

[slimhazard]

I guess the main question is really about cache.h, is it part of VRT or not? If it is was not, we would have changed the VRT version quite often in the past for no good reason (but we already know that and the decision was made as a safety measure).

Has there been a Varnish release that didn't bump the VRT version? It may have happened, but if so then it's been exceedingly rare (I for one don't remember any such release).

Certainly there have been a variety of considerations, but leaving cache.h out of VRT has not, in practice, contributed to keeping VRT at the same version from one release to the next, since that (almost?) never happens.

[slimhazard]

Come to think of it, releases with new micro-versions (for bugfixes or VSV fixes) don't usually change the VRT version. It's the six-month releases that, with few or no exceptions, bump up VRT.

[dridi]

On stable branches like 6.0 currently we only allow minor VRT bumps, and it lasts well beyond 6 months.

[bsdphk]

IMO our versioning has never worked particularly well, partially for lack of discipline, partially for inability to fully grasp the versioning consequences and partially because the 'fault-lines' are indeed very unevenly drawn.

[bsdphk]

Bugwash consensus: Yes, needs fixing, by defining what we want in ABI=vrt and the documenting.

WS makes sense, but should probably grow its own vrt_ws.h include, to be sucked in by cache.h

In general, we should aim to use vrt_*.h for ABI=vrt

[nigoroll]

TODO from bugwash:
review existing vmods and compile a wishlist of interfaces for addition to VRT
from Dridi: HTTP_* functions maybe?

[slimhazard]

I'd just like to bring up that in times like this (a VSV with the attendant Varnish fix versions), $ABI vrt makes life much easier. All VMODs with $ABI strict need to be rebuilt, only to update the commit ID, but no such effort is necessary for VRT-compatible VMODs.

So the resolution of this issue will make the world a little bit happier!