config.md: Rename ociVersion -> ociRuntimeVersion

[wking]

Now that we have multiple OCI specs. Reported by
@jonboulle.

Generated with:

$ sed -i 's/ociVersion/ociRuntimeVersion/g' $(git grep -l ociVersion)

[vbatts]

Hold on this.

On Wed, Apr 6, 2016 at 5:45 PM, W. Trevor King notifications@github.com
wrote:

Now that we have multiple https://github.com/opencontainers/image-spec
OCI https://github.com/opencontainers/runtime-spec specs. Reported
https://github.com/opencontainers/image-spec/pull/6/files/bf5c3f6b30cf326ee3e64849c8eb4c953500dd25#r58699357
by
@jonboulle https://github.com/jonboulle.

Generated with:

$ sed -i 's/ociVersion/ociRuntimeVersion/g' $(git grep -l ociVersion)

---

You can view, comment on, or merge this pull request online at:

#371
Commit Summary

• config.md: Rename ociVersion -> ociRuntimeVersion

File Changes

• M config.md
  https://github.com/opencontainers/runtime-spec/pull/371/files#diff-0
  (6)
• M runtime.md
  https://github.com/opencontainers/runtime-spec/pull/371/files#diff-1
  (4)
• M schema/schema.json
  https://github.com/opencontainers/runtime-spec/pull/371/files#diff-2
  (6)
• M specs-go/config.go
  https://github.com/opencontainers/runtime-spec/pull/371/files#diff-3
  (2)

Patch Links:

• https://github.com/opencontainers/runtime-spec/pull/371.patch
• https://github.com/opencontainers/runtime-spec/pull/371.diff

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#371

[wking]

There was some discussion on this proposal in today's meeting 1.
The main alternative proposal seemed to be image-spec-style media
types 2. Looking over [3,4], the media-type approach looks similar
to JSON-LD's @context [5,6]. Using JSON-LD would certainly give us an
approach that has had some thought put into it, although I'm not
particularly familiar with it myself. And it also makes life easier
for consumers, since they can notice and complain about an
unrecognized @context value, but would have a harder time tracking
version → ociVersion → ociRuntimeVersion → … without a human reading
the spec ChangeLog. @context also gives us the multiple-schema
support I was stumbling towards with [7,8], and that gives bundle
authors a convenient way for to clarify the interpretation of whatever
they put in ‘annotations’ [9](or anywhere else in their JSON).

I haven't been able to dig up anyone talking about putting JSON-LD and
SemVer together. The Schema.org folks store frozen versions of their
schemas [10,11], but say “Note that schema.org release numbers are not
generally included when you use schema.org” [10,11]. There's also a
schemaVersion property, but it lists only ~10 domains using it 12.
And see 13 where Dan Brickley says:

Semver.org is interesting but the terminology doesn't directly map
from APIs to schemas.

I'm not convinced (the distinction between a schema and an API is not
clear to me). But we could either write our own ‘semanticVersion’
property, or leave the SemVer-ness implicit in the @context.

All of these approaches (ociRuntimeVersion, mediaType, and @context)
avoid the current ociVersion ambiguity. Is there a reason to prefer
mediaType over @context?

[wking]

“How are we going to version config.json?” came up again today 1.
The issue there revolved around hypothetically dropping support for a:

"mac-address": "default"

on Solaris even though the ‘mac-address’ property remains in the spec
and the ‘default’ value was never mentioned (instead, the in-flight
Solaris docs refer to external docs 2).

To me, versioning is about communicating the intended semantics for
the config settings (like JSON-LD's @context and @id properties). So
if a value (like ‘default’) is meaningful in an earlier iteration of a
property, and not meaningful (or meaning a different thing) in later
iteration of that property, it's a SemVer major bump for that property
3. Runc has currently (permanently?) dropped versioning 4 to
avoid having to bump ociVersion to get an old-version bundle running
on a new-version runtime even though the changes between versions
didn't impact the subset of properties used in bundle's config. And
there has been similar discussion around versioning image manifests
[5,6].

While getting an IRI for each property 7 may seem tedious, it's easy
to automate, and we already have steps in that direction in the JSON
Schema [8,9]. The JSON Schema ids are RFC 3986 URIs 9, while
JSON-LD @ids are RFC 3987 IRIs 7, but that distinction is probably
not a big deal for us.

Anyhow, I'm happy to work up a JSON-LD PR if folks feel like that has
a chance of being accepted ;).

[crosbymichael]

Yes, lets hold on doing this because it would be much better to keep the two in sync instead of having two different versions that interop with each other.

[wking]

On Fri, Apr 29, 2016 at 03:03:09PM -0700, Michael Crosby wrote:

Yes, lets hold on doing this because it would be much better to keep
the two in sync instead of having two different versions that
interop with each other.

The two what in sync? Is that “we want similar versioning for the
image-spec and runtime-spec repositories”? If so (and that makes
sense to me), I'm happy to spin off the JSON-LD ideas to dev@.
Although I think I have a clear enough idea of how they'll work to
submit a PR to anchor discussion. In any case, clarity on what you
think the next steps are and when/where they will be taken would be
good ;).

[wking]

On Fri, Apr 29, 2016 at 03:45:46PM -0700, W. Trevor King wrote:

On Fri, Apr 29, 2016 at 03:03:09PM -0700, Michael Crosby wrote:

Yes, lets hold on doing this because it would be much better to
keep the two in sync instead of having two different versions that
interop with each other.

The two what in sync? Is that “we want similar versioning for the
image-spec and runtime-spec repositories”? If so (and that makes
sense to me)…

Ah, maybe you meant “we want both image-spec and runtime-spec to use
the same ociVersion identifier, and will lock their release cycles
together”. That moves in a less granular direction, and doesn't
sound like a good plan to me (why would the runtime care if the image
format got bumped?). And it was sounding like locked release cycles
were not part of the plan [1](which does make sense to me).