Document best practices for version label usage?

[krobertson]

Wanted to have a short discussion on what some thoughts were about "best practices" for version label usage in ACI images.

In the spec, version is just a label, and label values are just strings. However, the version label is also a special one in that it plays a more prominent role in the discovery process than other labels.

In particular, looking at version settings and practices around prefixing the version string, such as with a v. Other fields within AppC that enforce version semantics like the acVersion field focus on prefixes, and are simply 0.7.4. JSON examples for the ACI format include version labels with 1.0.0 as the value. However, actual usage wise, the etcd ACI image uses v2.3.0 as the value.

Although agree with labels generally be freeform strings and don't want strict settings around the version label, being too undefined here does have end-user implications. Someone using a container engine that supports AppC could end up getting whether the app they're wanting to use is prefixing versions or not. This is something that also exists in the Docker ecosystem with no clear guidelines.

So instead of a strict requirement, thinking it may make sense to have some written best practices to help guide image authors.

I think it'd also be good to look at some common ways in which the version label could be used, since version itself could be rather ambiguous.

Some common usages may be:

• latest (obviously)
• Release version, such as 1.2.3, 1.2.3+git, v0.1.0-120-g122abae (git describe --tags format)
• Plain build number, such as auto generated images from a dev CI system
• Branch/commit tags, such as images from a CI system
• Feature defintions, thinking of the Docker image concourse/busyboxplus:git or concourse/busyboxplus:iptables

Any others?

Personally, I'm sort of torn on "to v or not to v". Some examples:

• coreos.com/etcd:v2.3.0 looks better than coreos.com/etcd:2.3.0
• coreos.com/etcd,version=2.3.0 probably looks better than coreos.com/etcd,version=v2.3.0

@iaguis @jonboulle @philips

[sgotti]

@krobertson If you leave the version label as any other label (free form string) then you can do any suggestion but it'll remain a suggestion. There'll be no implications on the discovery logic or some implied behaviours. An user can continue to use anything.

If you make it special and enforce its usage (for example semver type) then you should also defines the impact that this will have on the current specification (discovery, dependency matching etc...).

Additionally discovery can be based on anything other than the version label and/or additional labels (ex build etc...) can be used.

Regarding to "latest" behavior I opened various issues.

The main problem is on how to implement latest. I opened #575 trying to clarify an actual hidden behavior and proposed two PR to remove this and make a pure meta tag based "latest" pattern #580 #581.

Then @mpasternacki made a good proposal to decouple image labels (that are fixed) from image tags (that are dynamic). Based on it I opened #584 for RFC.