cmd/oci-image-tool: add manuals #180

runcom · 2016-07-22T14:41:15Z

Signed-off-by: Antonio Murdaca runcom@redhat.com

runcom · 2016-07-22T14:41:21Z

wking · 2016-07-22T14:46:13Z

If we're getting more formal about documenting oci-image-tool, I
recommend following ocitools and putting most of the docs in something
that can turn into a man page 1.

runcom · 2016-07-22T14:49:40Z

If we're getting more formal about documenting oci-image-tool, I
recommend following ocitools and putting most of the docs in something
that can turn into a man page [1].

if maintainers are ok with that, I'll do that - right now I don't think it's necessary, ocitools otoh is already used a lot more and more mature (it's also already packaged in some distros).

wking · 2016-07-22T14:53:50Z

On Fri, Jul 22, 2016 at 07:49:41AM -0700, Antonio Murdaca wrote:

If we're getting more formal about documenting oci-image-tool, I
recommend following ocitools and putting most of the docs in something
that can turn into a man page [1].

if maintainers are with that, I'll do that - right now I don't think
it's necessary, ocitools otoh is already used a lot and more
mature.

Hopefully oci-image-tool will be mature and well-used soon ;).
Starting with a man page saves us from having to identify that point
and transition the README to a man page later.

runcom · 2016-07-22T14:58:10Z

and transition the README to a man page later.

I'd still have a README - why not?

wking · 2016-07-22T15:01:35Z

On Fri, Jul 22, 2016 at 07:58:11AM -0700, Antonio Murdaca wrote:

and transition the README to a man page later.

I'd still have a README - why not?

A README should defer to the man-page (opencontainers/runtime-tools#47) to
stay DRY.

runcom · 2016-07-22T15:07:09Z

A README should defer to the man-page (opencontainers/runtime-tools#47) to
stay DRY.

but we don't have a man page yet and what I've added is dry enough for now - I can remove the Usage to be referenced in future man pages but examples are good there and ocitools have them as well

wking · 2016-07-22T15:17:43Z

On Fri, Jul 22, 2016 at 08:07:10AM -0700, Antonio Murdaca wrote:

A README should defer to the man-page (opencontainers/runtime-tools#47) to
stay DRY.

but we don't have a man page yet and what I've added is dry enough
for now…

I'm just saying that if the decision is “we don't want a man page yet
because $REASONS”, we want to be clear on those reasons so we know
when to re-evaluate. If the issue is “because I don't want to put in
the time to set that up”, I'm happy to file a man-page conversion
against this branch later today.

runcom · 2016-07-22T15:20:08Z

If the issue is “because I don't want to put in
the time to set that up”, I'm happy to file a man-page conversion
against this branch later today.

that's not the issue - I'm only saying a README.md with examples can go in w/o waiting to have man pages and that can come as a follow on (by me as well of course). Anyhow, I'll work on man pages asap

wking · 2016-07-22T15:26:06Z

What examples would you put in a README that wouldn't go in the man page?

runcom · 2016-07-22T15:31:31Z

What examples would you put in a README that wouldn't go in the man page?

I'm not saying they should not go in the man page - I'm saying this is adding some example the same as the https://github.com/opencontainers/ocitools README is doing (https://github.com/opencontainers/ocitools/blob/master/man/ocitools-validate.1.md doesn't have examples in it but the README does, so take this PR as the README side of what ocitools already contain). I'm sure either of the two isn't following the other...

as said, I'll add some man pages stub

wking · 2016-07-22T16:10:24Z

On Fri, Jul 22, 2016 at 08:31:32AM -0700, Antonio Murdaca wrote:

What examples would you put in a README that wouldn't go in the
man page?

I'm not saying they should not go in the man page - I'm saying this
is adding some example the same as the
https://github.com/opencontainers/ocitools README is doing
(https://github.com/opencontainers/ocitools/blob/master/man/ocitools-validate.1.md
doesn't have examples in it but the README does…

Ah, I think that should be fixed in ocitools. Filed as
opencontainers/runtime-tools#142.

Signed-off-by: Antonio Murdaca <runcom@redhat.com>

runcom · 2016-07-22T17:13:39Z

man pages added...

wking · 2016-07-22T17:24:03Z

cmd/oci-image-tool/man/oci-image-tool-unpack.1.md

+**oci-image-tool unpack** [src] [dest] [flags]
+
+# DESCRIPTION
+`oci-image-tool unpack` unpacks a given OCI image into a directory suitable to be used with `runc`.


It's probably worth drawing a clear distinction between unpack and create-runtime-bundle here. That distinction is mostly around rootfs-or-not and config translation.

sure, any suggestion on the language?

On Fri, Jul 22, 2016 at 10:25:35AM -0700, Antonio Murdaca wrote:

+# DESCRIPTION
+oci-image-tool unpack unpacks a given OCI image into a directory suitable to be used with runc.

sure, any suggestion on the language?

For unpack, something like:

Validates an application/vnd.oci.image.manifest.v1+json and unpacks
its layered filesystem to DEST.

For create-runtime-bundle, something like:

Validates an application/vnd.oci.image.manifest.v1+json and unpacks
its layered filesystem to DEST/rootfs, although the target directory
is configurable with --rootfs. See oci-image-tool-unpack(1) for
more details on this process.

Also translates the referenced config from
application/vnd.oci.image.serialization.config.v1+json to a
runtime-spec's config.json.

On Fri, Jul 22, 2016 at 10:35:50AM -0700, W. Trevor King wrote:

Also translates the referenced config from
application/vnd.oci.image.serialization.config.v1+json to a
runtime-spec's config.json.

Probably worth working in DEST/config.json there somewhow. Maybe:

Also translates the referenced config from
application/vnd.oci.image.serialization.config.v1+json to a
runtime-spec-compatible DEST/config.json.

wking · 2016-07-22T17:27:56Z

On Fri, Jul 22, 2016 at 10:13:40AM -0700, Antonio Murdaca wrote:

man pages added...

They look pretty good to me. Do we expect additional command-line
tools in image-spec? If so, Makefiles for building the man pages will
be simpler if we use man/ instead of cmd/oci-image-tool/man/.

runcom · 2016-07-22T17:31:23Z

If so, Makefiles for building the man pages will
be simpler if we use man/ instead of cmd/oci-image-tool/man/.

I put them there just in case we'll have a dedicated repo for oci-image-tool and generally to keep them there not to clutter the repo root

wking · 2016-07-22T17:39:18Z

On Fri, Jul 22, 2016 at 10:31:26AM -0700, Antonio Murdaca wrote:

If so, Makefiles for building the man pages will
be simpler if we use man/ instead of cmd/oci-image-tool/man/.

I put them there just in case we'll have a dedicated repo for
oci-image-tool…

+1 to that 1 ;).

vbatts · 2016-07-25T18:53:06Z

LGTM

philips · 2016-07-27T20:58:31Z

Is this generated somehow? Ideally the help text and the docs stay in sync.

In any case:
LGTM

wking · 2016-07-27T23:53:09Z

@runcom, would you like to file a follow-up with the details on unpack
vs. create-runtime-bundle 1 or shall I?

runcom · 2016-07-28T00:30:05Z

I will @wking

Generated with: $ sed -i 's/oci-image-tools/oci-image-tool/g' $(git grep -l oci-image-tools) Typos are from e60ff1d (cmd/oci-image-tool: add manuals, 2016-07-22, opencontainers#180). Signed-off-by: W. Trevor King <wking@tremily.us>

wking · 2016-08-31T07:36:41Z

On Wed, Jul 27, 2016 at 05:30:08PM -0700, Antonio Murdaca wrote:

I will @wking

Any progress on this? I'm happy to turn 1 into a PR if you're too
busy.

philips · 2016-08-31T17:53:18Z

@runcom @wking can you file a new issue so we don't lose this?

wking · 2016-08-31T17:59:19Z

On Wed, Aug 31, 2016 at 10:53:18AM -0700, Brandon Philips wrote:

@runcom @wking can you file a new issue so we don't lose this?

I'll give @runcom 24 hours to get back, otherwise I'll just file a PR
;).

cmd/oci-image-tool: add manuals

e60ff1d

Signed-off-by: Antonio Murdaca <runcom@redhat.com>

runcom force-pushed the add-readme branch from ffa22ba to e60ff1d Compare July 22, 2016 17:13

runcom changed the title ~~cmd/oci-image-tool: add README.md~~ cmd/oci-image-tool: add manuals Jul 22, 2016

wking reviewed Jul 22, 2016
View reviewed changes

vbatts merged commit 64513b0 into opencontainers:master Jul 27, 2016

runcom deleted the add-readme branch July 27, 2016 23:51

This was referenced Aug 31, 2016

oci-image-tool.1: Fix "oci-image-tools" -> "oci-image-tool" typos #228

Merged

image: Refactor to use cas/ref engines instead of walkers #159

Closed

wking mentioned this pull request Oct 24, 2016

[README.md] Add detail description of oci-image-tool opencontainers/image-tools#48

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cmd/oci-image-tool: add manuals #180

cmd/oci-image-tool: add manuals #180

runcom commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016 •

edited

Loading

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016 •

edited

Loading

wking commented Jul 22, 2016

runcom commented Jul 22, 2016 •

edited

Loading

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking Jul 22, 2016

runcom Jul 22, 2016

wking Jul 22, 2016

wking Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

vbatts commented Jul 25, 2016 •

edited by caniszczyk

Loading

philips commented Jul 27, 2016 •

edited by caniszczyk

Loading

wking commented Jul 27, 2016

runcom commented Jul 28, 2016

wking commented Aug 31, 2016

philips commented Aug 31, 2016

wking commented Aug 31, 2016

cmd/oci-image-tool: add manuals #180

cmd/oci-image-tool: add manuals #180

Conversation

runcom commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016 • edited Loading

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

runcom commented Jul 22, 2016 • edited Loading

wking commented Jul 22, 2016

runcom commented Jul 22, 2016 • edited Loading

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking Jul 22, 2016

Choose a reason for hiding this comment

runcom Jul 22, 2016

Choose a reason for hiding this comment

wking Jul 22, 2016

Choose a reason for hiding this comment

wking Jul 22, 2016

Choose a reason for hiding this comment

wking commented Jul 22, 2016

runcom commented Jul 22, 2016

wking commented Jul 22, 2016

vbatts commented Jul 25, 2016 • edited by caniszczyk Loading

philips commented Jul 27, 2016 • edited by caniszczyk Loading

wking commented Jul 27, 2016

runcom commented Jul 28, 2016

wking commented Aug 31, 2016

philips commented Aug 31, 2016

wking commented Aug 31, 2016

runcom commented Jul 22, 2016 •

edited

Loading

runcom commented Jul 22, 2016 •

edited

Loading

runcom commented Jul 22, 2016 •

edited

Loading

vbatts commented Jul 25, 2016 •

edited by caniszczyk

Loading

philips commented Jul 27, 2016 •

edited by caniszczyk

Loading