Choose a version scheme for the Marketplace release

[maelvls]

tl;dr: our marketplace versions can look like "1.1.0+gcm.1": the 1.1.0 is the cert-manager version and gcm.1 is used whenever we want to change the deployer (e.g., bugs in the deployer's helm chart). No confusion on our side, no confusion on the user's side. Note that all the images (including non-cert-manager ones like preflight) will end up with the same 1.1.0+gcm.1 due to Marketplace requirements.

---

The marketplace has a notion of "application version"; in this issue, I want to present the different aspects we should consider in order to choose a versioning scheme.

Consideration 1: avoid confusion for the customer between "marketplace version" and "cert-manager version"

A user who lands on the jetstack-secure-for-cert-manager solution page is (very likely) aware of the cert-manager versions; using a marketplace versioning scheme that follows the cert-manager versions would make the experience consistent.

Consideration 2: requirement of retagging of all images under the same Marketplace tag

Currently, we retag all the cert-manager, google-cas-issuer, ubbagent, preflight images under one fixed version, let's call it the "marketplace version" (gcm version for short). The reason why we must retag using one single tag is so that we abide by the schema.md, which states:

When users deploy your app from Google Cloud Marketplace, the final image names may be different, but they will follow the same release tag and name prefix rule.

Consideration 3: only the minor version is displayed on the marketplace (e.g., just 1.2, not 1.2.0)

From the "create release" page:

A version should correspond to a minor version (e.g. "1.0") according to semantic versioning (not a patch version, such as "1.0.0"). Update the same version for patch releases, which should be backward-compatible, instead of creating a new version.

Only create versions for tags that you want in your final application (i.e. no "test" versions) since published versions cannot be immediately deleted.

Consideration 4: Marketplace version bumps with regards to cert-manager version bumps

We need a way to keep a clear mapping between the version of cert-manager and the version on the Marketplace.

Consideration 5: Marketplace versions require semantic versioning

A version should correspond to a minor version (e.g. "1.0") according to semantic versioning (not a patch version, such as "1.0.0"). Update the same version for patch releases, which should be backward-compatible, instead of creating a new version.

We might want to use something like a build number for the Marketplace updates using a + (not a - since it indicates a pre-release such as 1.0.0-alpha.1):

1.1.0+gcm.1             # 1.1.0 is the cert-manager version

Note that in the UI the user would still just see the minor revision only:

1.1

[maelvls]

cc @james-w @RiichardCC

[maelvls]

I think the 1.1.0+gcm.1 approach is the good one: we bump the marketplace release every time we cut a new release of cert-manager. No confusion on our side, no confusion on the user's side.

I'll see if we can actually do a 1.1.0+gcm.1 release right now by checking if the UI accepts the version or not 😅

[maelvls]

Looks like Docker itself is not semver compliant w.r.t. tags. The spec, visible in reference.go, is used by Kubernetes which calls ParseNormalizedNamed to validate image references.

couldn't parse image reference "gcr.io/jetstack-mael-valais/jetstack-secure-for-cert-manager/ubbagent:1.1.0+gcm.1": invalid reference format

Cf distribution/distribution#1201 (from 2015)

[maelvls]

After a discussion where James Westby pointed the fact that using the "pre-release" - in the version would be fine since we are always going to have the -gcm.X suffix anyways, Josh agreed to use the tag 1.1.0-gcm.1 and I agreed with Josh on the fact that the valid tag 1.1.0_gcm.1 is ugly.

Jake also brought the fact the OLM (OpenShift Operator Marketplace) only accepts a dash (-) at the end of versions.

→ let's go with 1.1.0-gcm.1 then!

[maelvls]

This morning, @JoshVanL brought up a valid point: why did we choose to drop the prefix v in our versions? I propose to re-open this issue and continue the conversation here.

Reasons:

• All the docker images have to be tagged using the "unique" marketplace version,
• The marketplace version must follow the semver v2 spec (as per the organize-releases documentation),
• When setting the marketplace version to v1.1.0-gcm.1, the mpdev verify tool (logs) would error with

  Step #29 - "verify": config_helper.InvalidSchema: Invalid schema publishedVersion "v1.1.0-gcm.1"; must be semver including patch version
  

Looks like 1.1.0-gcm.1 is a valid semver version and v1.1.0-gcm.1 is not?

cc @wallrj