config: reference common label conventions

[vbatts]

This has come up a couple of times on the weekly discussion, but the PR
had not been followed through with.

label-schema.org is a convention that follows the practices outlined in
OCI. Provide here only as a reference example of label usage.

Signed-off-by: Vincent Batts [email protected]

[vbatts]

cc @lizrice

[wking]

Fixes #485? I'd rather see the reference land in [1]. I'm not sure why #501 didn't setup a link to annotations.md for Labels, but maybe we want to do that? [1]: https://github.com/opencontainers/image-spec/blob/v1.0.0-rc5/annotations.md

[jonboulle]

Why not annotations too?

[vbatts]

Nothing stopping that, but the convention is based on image labels

…

On Apr 4, 2017 10:14, "Jonathan Boulle" ***@***.***> wrote: Why not annotations too? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#635 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEF6fPUS8WBDK_cHaMUUbUdvZsMNQedks5rslBPgaJpZM4MyMuU> .

[jonboulle]

I suppose (IMHO) we still haven't clearly described the use cases for one vs the other.

[stevvooe]

@vbatts I've filed #636 to bring the OCI annotations/labels to feature parity with label-schema, minus the docker/rkt.cmd stuff.

In general, these style of annotations work best when sitting on the actual image config, rather than manifests or indexes. They can be "pulled up", which makes them indexed, in a sense, but pushing them down to the image config minimizes the possibility of them being lost in transit.

It would be good to add this line:

Labels SHOULD use the annotations defined in annotations.md.

[vbatts]

That's cool, though it still of benefit for such a community convention to have reference of it's usage. No?

…

On Tue, Apr 4, 2017 at 2:39 PM Stephen Day ***@***.***> wrote: @vbatts <https://github.com/vbatts> I've filed #636 <#636> to bring the OCI annotations/labels to feature parity with label-schema, minus the docker/rkt.cmd stuff. In general, these style of annotations work best when sitting on the actual image config, rather than manifests or indexes. They can be "pulled up", which makes them indexed, in a sense, but pushing them down to the image config minimizes the possibility of them being lost in transit. It would be good to add this line: Labels SHOULD use the annotations defined in annotations.md. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#635 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEF6SHbpwnv6gAAgPbp4bey5aYPxRXpks5rso5RgaJpZM4MyMuU> .

[stevvooe]

@vbatts Yes, but it seems better if we just have them defined here. I am not saying remove the reference, just point them towards using the annotations. #636 ensures we have all the equivalent annotations from label-schema.

In that vein, I see this PR being the following:

Labels SHOULD use the annotations defined in annotations.md.
There are community conventions available for image labels, for example Label Schema.

[vbatts]

@stevvooe I see. Perhaps I'll do that in a separate PR because the label rules could just point to ./annotations.md#rules

[wking]

Yes, but it seems better if we just have them defined here. I am not saying remove the reference, just point them towards using the annotations. #636 ensures we have all the equivalent annotations from label-schema.

I don't see the point to having OCI-named “equivalent annotations” for keys that don't directly impact image-spec or runtime-spec use-cases. So if we expect to have image-spec or image-tools code acting on the keys, having an OCI-named key makes sense. But I don't see any OCI-repo use-case for “packaged sofware version” (and the goal seems to be just human-readable anyway), so adding OCI-named keys seems like a needless community fragmentation. Why would users want to use the OCI-named keys when they could use the existing org.label-schema.version, etc.? And having to support both in tooling seems like tedious busywork for no practical gain.

[vbatts]

@wking conversation for the other thread (#636), but agreed

[vbatts]

rebased (moved stuff to annotations.md to keep DRY)

[stevvooe]

@vbatts Does this need to be modified after #636? Do you want to carry this for the compatibility table?

[vbatts]

@stevvooe i reckon a compatibility table would cover any references that this PR would be attempting to achieve.