cmd/oci-image-tool/main.go: Add description with supported versions

[wking]

In the --version output.

I expect image-tools to support a range of spec versions, not just a single one. For example, once image-spec cuts 2.0, image-tools should still be able to process 1.x images for some reasonable deprecation period. image-spec is setting us up for that possibility by using the v1 package for the Go types that are likely to change. And SemVer means that if we can unpack a 1.3 image, we can also unpack 1.2, 1.1, and 1.0 images. So I think we want this to be printing, uh:

specs: 0.3.0-dev

now. Once we bump our vendored library to catch up with opencontainers/image-spec#354, we should be showing:

specs: 1.0.0-rc1

Once 1.0 is cut we should show:

specs: 1.0.0

Once 1.1 is cut we should show our position in the 1.x series:

specs: 1.1.0

And then when 2.0 is cut we should show our positions in both the 1.x and 2.x series. If 2.0 happened after 1.1 (without a 1.2, etc.), that would be:

specs: 1.1.0, 2.0.0

Spun off from here.

[xiekeyang]

Maybe we had better to announce in README that image tool support downward compatibility for spec, instead of listing series of versions.

specs: 1.1.0, 2.0.0
How can we get many versions? I worry that it will confuse consumers.

[wking]

On Tue, Nov 08, 2016 at 07:59:59PM -0800, xiekeyang wrote:

Maybe we had better to announce in README that image tool support
downward compatibility for spec, instead of listing series of
versions.

I don't think we plan on supporting 1.0 forever. I also don't expect
a hard cut-over from 1.x to 2.0. Are there no plans for supporting
both 1.x and 2.0 for some transition period? Or is the plan to never
hit 2.0? ;).

specs: 1.1.0, 2.0.0

How can we get many versions? I worry that it will confuse
consumers.

It doesn't seem that confusing to me. Eventually image-spec makes a
backwards incompatable change and cuts 2.0. I expect folks with 1.x
images to have a gentle migration path. The “specs:” line makes it
clear that that image-tools build continues to support their images.

If, instead, they see:

spec: 2.0.0

it's less clear to me what a user with a 1.x image will do. Do they
optimistically attempt to pull/unpack? Do they take a look in the
README for a backwards compat plan? Neither of those sounds
particularly user-friendly to me.

[vbatts]

but it is only the image-spec. This seems confusing. If there are multiple versions covered, it is not different specs per se.

[wking]

On Tue, Feb 14, 2017 at 05:40:04AM -0800, Vincent Batts wrote: but it is only the image-spec. This seems confusing. If there are multiple versions covered, it is not different specs per se.

So “OCI Image Format Specification versions:”?

[vbatts]

:-\ maybe? On Tue, Feb 14, 2017 at 12:59 PM, W. Trevor King <[email protected]> wrote:

…

On Tue, Feb 14, 2017 at 05:40:04AM -0800, Vincent Batts wrote: > but it is only the image-spec. This seems confusing. If there are > multiple versions covered, it is not different specs per se. So “OCI Image Format Specification versions:”? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#36 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEF6VqcApEF_FzBsQCzC5LqRdPQDCDQks5rceuTgaJpZM4KQhWe> .

[wking]

On Tue, Feb 14, 2017 at 01:54:27PM -0800, Vincent Batts wrote: :-\ maybe?

Or maybe use ‘specs’ (or ‘spec’, or whatever you want), and document it in the man pages: -v, --version Print version information and exit. The output format includes the following fields: … specs: A space-delimited list of supported OCI Image Format Specificiation versions. When multiple versions are supported, the highest version for each major number will be listed. … If you don't have particular wording in mind, I suggest we just pick something and move on. We can always cycle back around and remove any remaining ambiguity later, but deciding to only support a single version at a time seems short-sighted.

[zhouhao3]

version option has benn changed, and spec is no longer used, so closing this.

[wking]

On Mon, Jul 10, 2017 at 11:34:00PM -0700, Zhou Hao wrote: `version` option has benn changed, and `spec` is no longer used so closing this.

It looks like they were dropped in #103, but I don't see any discussion there about why the ‘spec(s)’ entry was dropped. Perhaps we should re-open this PR and restore the line? Or add a ‘version’ command that provides more detail than the current [1]? Otherwise it's not clear to me how a user is supposed to discover what image-spec version their oci-image-tool build targets, short of tracking the image-tool commit / version back to GitHub and reading the source. [1]: https://github.com/opencontainers/image-tools/blob/144d94513ae640edca038a0b1c3ecc9e28890272/cmd/oci-image-tool/main.go#L34-L36

[zhouhao3]

@wking I think you can add the spec/specs in version option information, and then we talk about whether it is feasible.

[wking]

Rebased around #103 with 5157b15 → aad3305, and now output looks like:

$ ./oci-image-tool --help
NAME:
   oci-image-tool - OCI (Open Container Initiative) image tools

USAGE:
   oci-image-tool [global options] command [command options] [arguments...]

VERSION:
   0.2.0-dev commit: aad33053bc134ea29484856c85413a64b01a2583

DESCRIPTION:
   Tools for working with OCI images.  Currently supported specifications are:

   * OCI Image Format Specification: 1.0.0-rc5
   * OCI Runtime Specification: 1.0.0-rc5
…

[wking]

Travis failed with:

$ make lint
checking lint
WARNING: vet: no files to lint
WARNING: vetshadow: no files to lint
make: *** [lint] Error 2
The command "make lint" exited with 2.

but master is failing the same way, so I expect that failure is orthogonal to this commit.

[Mashimiao]

@wking restarted CI, seems good. Please rebase your PR