annotations.md: added useful annotations #636
Conversation
| @@ -22,4 +22,7 @@ This specification defines the following annotation keys, intended for but not l | |||
| * **org.opencontainers.image.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS) | |||
| * **org.opencontainers.image.documentation** URL to get documentation on the image (string, a URL with scheme HTTP or HTTPS) | |||
| * **org.opencontainers.image.source** URL to get source code for the binary files in the image (string, a URL with scheme HTTP or HTTPS) | |||
| * **org.opencontainers.image.version** [Semantic versioning-compatible](http://semver.org/) version of the packaged software. | |||
| * **org.opencontainers.image.revision** Source control revision identifier for packaged software. | |||
| * **org.opencontainers.image.vendor** Name of the distributing entity, organization or individual. | |||
There was a problem hiding this comment.
How does it differ from org.opencontainers.image.authors?
There was a problem hiding this comment.
Authors are usually restricted to specific people. This also allows the case where authors are different than the vendor or distributor.
| @@ -22,4 +22,7 @@ This specification defines the following annotation keys, intended for but not l | |||
| * **org.opencontainers.image.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS) | |||
| * **org.opencontainers.image.documentation** URL to get documentation on the image (string, a URL with scheme HTTP or HTTPS) | |||
| * **org.opencontainers.image.source** URL to get source code for the binary files in the image (string, a URL with scheme HTTP or HTTPS) | |||
| * **org.opencontainers.image.version** [Semantic versioning-compatible](http://semver.org/) version of the packaged software. | |||
| * **org.opencontainers.image.revision** Source control revision identifier for packaged software. | |||
There was a problem hiding this comment.
I think we need org.opencontainers.image.vcs (e.g. "git") for this
There was a problem hiding this comment.
That is covered by .source.
There was a problem hiding this comment.
Yes, but implementations needs to invoke HTTP request for determining the VCS, if we suppose .revision to be machine-readable.
So, if we want to use .source for this purpose, I think we need to allow git:// scheme for .source.
EDIT: (but this is supposed to be human-readable only? then I think the current description SGTM)
There was a problem hiding this comment.
@AkihiroSuda This is really meant to be human-readable. I think we'd have to do a little more specification here to make source work correctly across implementations.
There was a problem hiding this comment.
@AkihiroSuda I just wanted to clarify that while these aren't explicitly specified, it doesn't mean they can't have machine readable values. If we over-specify, we risk alienating unfamiliar or obscure source control systems. Tools could totally consume these values and attempt to checkout source code.
Other label schema projects include the following items that are not yet included in OCI Images. This PR adds support for `version`, `vendor` and `revision` to bring parity to OCI defined image labels. Signed-off-by: Stephen J Day <stephen.day@docker.com>
stevvooe
force-pushed
the
extend-image-schema-annotations
branch
from
4190a14
to
350d5f2
Compare
|
|
so, are these fields effectively duplicating what label-schema has defined?
so users might expect to see both?
…On Wed, Apr 5, 2017 at 3:35 PM Stephen Day ***@***.***> wrote:
- Added licenses field.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#636 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAEF6eJH26KoqAbxEZlel7nio0EpD0Y_ks5rs-0bgaJpZM4MzQF1>
.
|
Doesn't that make sense to do if the fields are useful? Maybe I am misunderstanding label schema but isn't it just a proposal for the naming, relying on it for useful information as part of the image spec standard does not make much sense. |
OCI already has about 70% of what label-schema.org provides. Should we delete those fields, as well?
These are annotations. What is the issue with that? They are completely compatible. I am extremely confused about the push back here. |
|
I am extremely not pushing back, but rather curious
…On Wed, Apr 5, 2017, 16:23 Stephen Day ***@***.***> wrote:
so, are these fields effectively duplicating what label-schema has defined?
OCI already has about 70% of what label-schema.org provides. Should we
delete those fields, as well?
so users might expect to see both?
These are annotations. What is the issue with that? They are completely
compatible.
I am extremely confused about the push back here.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#636 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAEF6VH6W7sAoRlkjm9LhtuKSuAneLDjks5rs_hMgaJpZM4MzQF1>
.
|
:) In general, I think adding these to OCI will create better adoption. Considering we have the bulk of these already, going the extra distance seems quite harmless. |
|
I kind of agree with #635 (comment) - ending up with duplicate annotations for exactly the same thing seems unfortunate, especially when these are both quite nascent efforts. Turning this around, let's assume we merge this PR, I wonder if label-schema folks would be okay making a reference to the official values here? I am not hugely fussed about whether the conventions live here (as I endorsed at a while back), or externally in label-schema, but it would nice if we could consolidate.
I don't understand this point; what's the difference here exactly? |
|
@jonboulle While I wasn't for adding these labels in the beginning, I do see that there is a desire for them in the community. As it stands, 70% of the label-schema labels were already in OCI, minus the And adding them here doesn't mean label-schema has to go way. They are namespaced and should generally be compatible. If a user only needs these base labels, they can use those. If more or different functionality is required, then they can adopt something else. |
|
After some amount discussion, while the adding of these keys is innocuous, I think the issue is: This effectively is seeking to shadow the patterns put forth by the label-schema.org, without providing a path to why they should switch. While I would rather just point reference to an existing convention, perhaps the conversation here would be one of bringing in the label-schema (adopting it) such that their existing prefix is reserved and the fields are directly honorable. (with discussion around not including the Regardless, the addition of these fields or adoption conversations were agreed to not be blocking of a |
|
I hope it's ok for me to jump in and add my 2p's worth as a label-schema maintainer: I would far rather see a single set of label names rather than two! We started the label-schema project with the idea of helping the community settle on a single convention for common labels. Two conventions is worse than one, and confusing. If the OCI spec is the right place to define the convention, I for one say we should retire label-schema in its favour and point at the OCI spec. That said, there are now over a thousand public images that have already adopted the label-schema convention. Is there usage out there for org.opencontainers labels? Whatever, we should just settle on ONE set of names so that we can achieve the original objective of saving users from defining multiple labels to convey the same information about their image to multiple vendors or tool. |
|
Also, I'll add that I absolutely don't have a preference about whether the convention gets documented within the OCI doc itself, or it references the label-schema doc. It makes very little difference to end users! |
|
@lizrice thanks for your input and openness! Agreed on all fronts - one is
better than two :-)
Am 12.04.2017 18:55 schrieb "Liz Rice" <notifications@github.com>:
… Also, I'll add that I absolutely don't have a preference about whether the
convention gets documented within the OCI doc itself, or it references the
label-schema doc. It makes very little difference to end users!
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#636 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ACewNxIvKQwGf0beOrpsywXOKfPiD_NAks5rvQFygaJpZM4MzQF1>
.
|
|
@vbatts @jonboulle @lizrice If we have the end users in mind, adopting this PR is the best approach. Indeed, there are roughly 1000 images that include label-schema labels, but this is out of 400,000 public images, which is about 0.25%. The actual usage of these images and the number of users impacted by a split will be low. While the number of OCI images in existence is currently very low, it will have almost immediate adoption across several container platforms, easily eclipsing the current adoption of label-schema. I understand the idea that creating a "duplicate" namespace for these labels seems redundant, but we've already duplicated other parts of images in the pursuit of OCI. For example, OCI created an entirely new set of mediatypes for objects already specified and implemented in Docker. Creating a "conversion schema" is the approach taken thus far in OCI and I don't see why we would depart from this model. From a technical perspective, this provides much better control over the specified components, without breaking compatibility and providing an well-defined upgrade path. I'd also like to point out that the licensing, ownership, governance and copyright of label-schema.org isn't quite clear. For something that we envision to have large adoption, this ambiguous situation isn't ideal. Given that OCI already has the legal basis covered, we can side step the possible issues that may come up. I'm sure this could be resolved, but I think hesitation here against an OCI release will have a negative effect adoption. If our goal is industry uniformity, adopting this PR into OCI is best chance. We will have clear adoption, clear governance, copyright, licensing and ownership. While doing so will mean that label-schema may go away, the very existence will have ensured that they landed here, achieving the original goals of the project. That sounds like a success to me! |
|
Taking advantage of the work OCI have done to sort out legals etc SGTM. For all the folks who already use or contributed to the existing label-schema work, it would be nice to see that acknowledged and agree a way to communicate the advantages of moving over to an OCI-blessed standard (rather than just have it silently "go away"). Conversation about this f2f in Austin next week? @amouat and I will both be in town. |
|
@lizrice @caniszczyk Should we also reference Project Atomic Generic Labels, as well? Seems like we should have a whole section that includes back references to source material for OCI, including the original specification links for the image config and manifest types. This could also serve to provide solid historical context and help with implementors trying to support several formats. As far as label-schema's messaging is concerned, that is purely up to the maintainers of that project. If they want to endorse OCI's labels and move on to something else, that would be great for achieving the goal of centralization. We can figure out the details in the f2f. |
|
@stevvooe @lizrice SGTM, added it to the agenda and I think the suggestion is fair, do the @opencontainers/image-spec-maintainers have any other comments? https://docs.google.com/document/d/1z5Cv7CdFeSmYJDH8xznPc1SWhjigtxG_mTfl6aqYabk/edit |
|
@vbatts Let's get this merged, per the agreement made in the OCI F2F meeting. |
|
LGTM |
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers#636 [2]: opencontainers#501 (comment) [3]: opencontainers#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers#636 [2]: opencontainers#501 (comment) [3]: opencontainers#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers#636 [2]: opencontainers#501 (comment) [3]: opencontainers#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers/image-spec#636 [2]: opencontainers/image-spec#501 (comment) [3]: opencontainers/image-spec#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers/image-spec#636 [2]: opencontainers/image-spec#501 (comment) [3]: opencontainers/image-spec#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers/image-spec#636 [2]: opencontainers/image-spec#501 (comment) [3]: opencontainers/image-spec#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers/image-spec#636 [2]: opencontainers/image-spec#501 (comment) [3]: opencontainers/image-spec#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of comma-separated short identifiers, which have unclear semantics (are the delimiters AND or OR?). I don't see any discussion of the syntax for this field in [1] (which landed it), but I'd floaded license expressions before in the sub-thread starting at [2]. Greg had pushed back against my earlier proposal (licensing information on descriptors) with [3]: > No, that's not going to work at all, you can't properly describe the > license for a whole layer in any form of a string that could be > standardized or parsed. SPDX is great for describing the individual > licenses of things, but not for a collection of things, which almost > always has an arbitrary license (example, what's the license, in a > simple string, for a Ubuntu base layer?) But SPDX License Expression are both more expressive and better defined than the current comma delimiters. Everything you could have said with the comma-delimited string you can say more clearly with a SPDX License Expression. And because the syntax is not OCI-specific, you're more likely to be able to find tooling that handles these values out of the box. [1]: opencontainers/image-spec#636 [2]: opencontainers/image-spec#501 (comment) [3]: opencontainers/image-spec#501 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Other label schema projects include the following items that are not yet
included in OCI Images. This PR adds support for
version,vendorandrevisionto bring parity to OCI defined image labels.Signed-off-by: Stephen J Day stephen.day@docker.com