Change version number strategy

[bethesque]

Currently the version number strategy uses the M.m.p from the pact_broker gem, and adds an extra number to the end to signify the release. eg. 2.106.1.1 is for gem version 2.106.1 and release 1 (releases start at 0). The release number is bumped when the pact_broker gem hasn't changed, but something related to the Docker image packaging has (eg. ruby version bump, alpine version bump, other gem dependency bump, changing or fixing something to do with the application setup etc)

When the base docker image (alpine) is upgraded, there may be breaking changes introduced (eg. at a certain alpine version, support for Docker < 20 was dropped).

The current versioning scheme does not allow us to indicate the presence of breaking changes to the underlying Docker image without the pact_broker gem itself (which as no knowledge of the Docker project) incrementing a major version.

The current tagging system does have the advantage, however, of allowing easy identification of the pact_broker version from the tag - it would be good to maintain that.

Proposal - start a new versioning scheme using that allows breaking changes to be conveyed for either the pact_broker gem OR some aspect of the underlying Docker image, while also including the pact_broker gem version.

Proposed format: M.m-pactbroker<pact_broker_gem_version>

The M.m would be incremented if there were changes to either the packaging or the gem, as appropriate.

The current major version is 2, so to allow the numbers to keep incrementing, I suggest we start with 3.0-pactbroker2.106.0 (or whatever gem version we're at at the time of the change).

[TimothyJones]

The semver spec already covers this, I think.

The proposed format with the dash makes it look like a prerelease version from a semver perspective, which I think is potentially confusing. I would say that the underlying broker version would more correctly be listed as build metadata (since it's information about what is built, and not a pre-release indicator).

For this reason, I think <Major>.<Minor>.<Patch>+pactbroker.v<pact_broker_gem_version> would be the most appropriate format.

Unfortunately, docker tags don't support + as a character (which is annoying, since people often use the tags to put semver version numbers in 🤷 ). As a compromise, you could do something like:

<Major>.<Minor>.<Patch>_with_pactbroker.v<pact_broker_gem_version>

to make it clearer that it's not a prerelease (or a standard semver tag, generally).

[TimothyJones]

For those playing along at home, people have been complaining about docker tags not being semver-compatible for a number of years now. There's an open issue against the relevant spec, but it doesn't look like it has much traction :(

[bethesque]

Yeah, I looked at making it a proper semantic version, but the lack of support for + killed that.

[bethesque]

The idea is to follow the docker conventions I've seen in docker images like these (node and ruby):

[TimothyJones]

As far as I can see, that would cover all the cases. I like it!