descriptor.md: Add the urls attribute instance in the Examples #437

zhouhao3 · 2016-11-03T09:18:32Z

Signed-off-by: zhouhao zhouhao@cn.fujitsu.com

coolljt0725 · 2016-11-03T09:26:26Z

descriptor.md

@@ -115,5 +115,8 @@ The following example describes a [_Manifest_](manifest.md#image-manifest) with
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "size": 7682,
  "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"


missing , at the end of this line

wking · 2016-11-03T14:58:06Z

descriptor.md

+  "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
+  "urls": {
+    "https://example.com/example"
+  }    


Trailing whitespace.

philips · 2016-11-17T04:15:25Z

LGTM

wking · 2016-11-17T05:26:21Z

descriptor.md

+  "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
+  "urls": {
+    "https://example.com/example"
+  }


urls should be an array, not an object.

updated,thanks

wking · 2016-11-17T05:48:19Z

e1332db looks good to me.

jonboulle · 2016-11-17T20:12:48Z

LGTM

zhouhao3 · 2016-11-18T02:54:26Z

@philips Please re-LGTM, thanks

zhouhao3 · 2016-11-21T01:35:31Z

@vbatts @stevvooe PTAL

stevvooe · 2016-11-21T20:02:09Z

Rejected.

The urls field is not exemplary of descriptors.

We could add another section explaining the handling of the field, when encountered.

wking · 2016-11-21T20:47:44Z

On Mon, Nov 21, 2016 at 12:02:09PM -0800, Stephen Day wrote:

The urls field is not exemplary of descriptors.

It might be exemplary for a nondistributable layer? Maybe we could
show one of those?

stevvooe · 2016-11-21T21:07:49Z

It might be exemplary for a nondistributable layer? Maybe we could
show one of those?

Yes, I would keep the example narrow. Basically, "if you see one like this, try to grab the content from the urls before resolving remotely".

wking · 2016-11-21T21:39:03Z

On Mon, Nov 21, 2016 at 01:07:49PM -0800, Stephen Day wrote:

It might be exemplary for a nondistributable layer? Maybe we could
show one of those?

Yes, I would keep the example narrow. Basically, "if you see one
like this, try to grab the content from the urls before resolving
remotely".

Do we even need explanatory text? That should already be covered by
the property spec. I was thinking this section would look like:

Examples

The following example describes a Manifest…[snip same as now]

  {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 7682,
    "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
  }

The following example describes a non-distributable layer:

  {
    "mediaType": "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip",
    "size": 10815,
    "digest": "sha256:67877ffadef141079c71284ce7d8302e4d05fedc4be397f32f99bc6e97a00cb4",
    "urls": [
      "https://example.com/base-layer.tar.gz
    ]
  }

stevvooe · 2016-11-21T21:45:45Z

@wking Yes, we need explanatory text, because a lot of people won't understand that a layer with urls but without the media type isn't nondistributable. Again, as I have said about a million times, context is important.

wking · 2016-11-21T22:01:01Z

On Mon, Nov 21, 2016 at 01:45:46PM -0800, Stephen Day wrote:

@wking Yes, we need explanatory text, because a lot of people won't
understand that a layer with urls but without the media type is
nondistributable.

So make it a minimal pivot from the “common case” example:

Examples

The following example describes a Manifest…[snip same as now]

  {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 7682,
    "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
  }

If the manifest was available outside of CAS, you could add locations to urls:

  {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 7682,
    "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
    "urls": [
      "https://example.com/example-manifest"
    ]
  }

stevvooe · 2016-11-21T22:14:09Z

So make it a minimal pivot from the “common case” example:

Common sense isn't so common.

It also makes assumptions about the reader's prior knowledge and their understanding of when urls should be used and when it should not be used. For such a powerful feature, we need to make sure that users can infer implications and apply it to the right scenarios such that it will work in a plurality of environments.

wking · 2016-11-22T05:25:40Z

On Mon, Nov 21, 2016 at 02:14:09PM -0800, Stephen Day wrote:

It also makes assumptions about the reader's prior knowledge and
their understanding of when urls should be used and when it should
not be used. For such a powerful feature, we need to make sure that
users can infer implications and apply it to the right scenarios
such that it will work in a plurality of environments.

As it stands, the ‘urls’ property definition has no warnings at all
[1](and the spec portion landed in #169 without warnings either). If
you feel the field needs warnings or SHOULDs and SHOULD NOTs, it seems
like we should start by adding them where the field is specified.
Then any ‘urls’ examples can refer readers to that canonical
description.

stevvooe · 2016-11-23T03:37:52Z

Then any ‘urls’ examples can refer readers to that canonical
description.

Or, we can use examples to demonstrate exemplary use cases, with appropriate context, like I requested here.

zhouhao3 · 2016-11-29T02:10:07Z

So what you mean is that in the examples to add urls, there must be relevant instructions？

vbatts · 2016-11-30T21:35:45Z

Is this discussion blocking this from being merged? or can it happen in a follow-up?

stevvooe · 2016-11-30T22:54:32Z

The problem here is that the urls field, which isn't supposed to be used in the common case, is part of the only example.

Make a separate example showing the use of urls with the example in a context that helps explains its role.

zhouhao3 · 2016-12-01T05:41:09Z

@stevvooe @wking You mean this change? I feel it does not need to modify, urls and other optional attributes on the same, can appear in the example, if according to you mean, whether to all options in the example to illustrate?

jonboulle · 2016-12-01T11:50:33Z

descriptor.md

@@ -116,4 +116,15 @@ The following example describes a [_Manifest_](manifest.md#image-manifest) with
  "size": 7682,
  "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
 }
+
+If the manifest was available outside of CAS, you could add locations to urls:


In the following example, the descriptor indicates that the referenced manifest is retrievable from a particular URL:

Signed-off-by: zhouhao <zhouhao@cn.fujitsu.com>

stevvooe · 2016-12-06T00:35:10Z

LGTM

@q384566678 Sure, I guess this works. I cannot get the original revision.

zhouhao3 · 2016-12-06T01:15:48Z

@jonboulle @philips PTAL

wking · 2016-12-06T06:45:33Z

bc78dcc looks good to me too.

vbatts · 2016-12-06T16:10:09Z

LGTM

coolljt0725 reviewed Nov 3, 2016

View reviewed changes

wking reviewed Nov 3, 2016

View reviewed changes

wking reviewed Nov 17, 2016

View reviewed changes

jonboulle reviewed Dec 1, 2016

View reviewed changes

descriptor.md: Add the urls attribute instance in the Examples

bc78dcc

Signed-off-by: zhouhao <zhouhao@cn.fujitsu.com>

vbatts merged commit c2ba0e3 into opencontainers:master Dec 6, 2016

vbatts mentioned this pull request Jan 27, 2017

Bump version for v1.0.0-rc4 #537

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

descriptor.md: Add the urls attribute instance in the Examples #437

descriptor.md: Add the urls attribute instance in the Examples #437

zhouhao3 commented Nov 3, 2016

coolljt0725 Nov 3, 2016

zhouhao3 Nov 3, 2016

wking Nov 3, 2016

philips commented Nov 17, 2016 •

edited by caniszczyk

Loading

wking Nov 17, 2016

zhouhao3 Nov 17, 2016

wking commented Nov 17, 2016 via email

jonboulle commented Nov 17, 2016 •

edited by caniszczyk

Loading

zhouhao3 commented Nov 18, 2016

zhouhao3 commented Nov 21, 2016

stevvooe commented Nov 21, 2016

wking commented Nov 21, 2016

stevvooe commented Nov 21, 2016

wking commented Nov 21, 2016

stevvooe commented Nov 21, 2016 •

edited

Loading

wking commented Nov 21, 2016

stevvooe commented Nov 21, 2016

wking commented Nov 22, 2016

stevvooe commented Nov 23, 2016

zhouhao3 commented Nov 29, 2016

vbatts commented Nov 30, 2016

stevvooe commented Nov 30, 2016

zhouhao3 commented Dec 1, 2016

jonboulle Dec 1, 2016

zhouhao3 Dec 2, 2016

stevvooe commented Dec 6, 2016 •

edited by caniszczyk

Loading

zhouhao3 commented Dec 6, 2016

wking commented Dec 6, 2016 via email

vbatts commented Dec 6, 2016 •

edited by caniszczyk

Loading

descriptor.md: Add the urls attribute instance in the Examples #437

descriptor.md: Add the urls attribute instance in the Examples #437

Conversation

zhouhao3 commented Nov 3, 2016

coolljt0725 Nov 3, 2016

Choose a reason for hiding this comment

zhouhao3 Nov 3, 2016

Choose a reason for hiding this comment

wking Nov 3, 2016

Choose a reason for hiding this comment

philips commented Nov 17, 2016 • edited by caniszczyk Loading

wking Nov 17, 2016

Choose a reason for hiding this comment

zhouhao3 Nov 17, 2016

Choose a reason for hiding this comment

wking commented Nov 17, 2016 via email

jonboulle commented Nov 17, 2016 • edited by caniszczyk Loading

zhouhao3 commented Nov 18, 2016

zhouhao3 commented Nov 21, 2016

stevvooe commented Nov 21, 2016

wking commented Nov 21, 2016

stevvooe commented Nov 21, 2016

wking commented Nov 21, 2016

Examples

stevvooe commented Nov 21, 2016 • edited Loading

wking commented Nov 21, 2016

Examples

stevvooe commented Nov 21, 2016

wking commented Nov 22, 2016

stevvooe commented Nov 23, 2016

zhouhao3 commented Nov 29, 2016

vbatts commented Nov 30, 2016

stevvooe commented Nov 30, 2016

zhouhao3 commented Dec 1, 2016

jonboulle Dec 1, 2016

Choose a reason for hiding this comment

zhouhao3 Dec 2, 2016

Choose a reason for hiding this comment

stevvooe commented Dec 6, 2016 • edited by caniszczyk Loading

zhouhao3 commented Dec 6, 2016

wking commented Dec 6, 2016 via email

vbatts commented Dec 6, 2016 • edited by caniszczyk Loading

philips commented Nov 17, 2016 •

edited by caniszczyk

Loading

jonboulle commented Nov 17, 2016 •

edited by caniszczyk

Loading

stevvooe commented Nov 21, 2016 •

edited

Loading

stevvooe commented Dec 6, 2016 •

edited by caniszczyk

Loading

vbatts commented Dec 6, 2016 •

edited by caniszczyk

Loading