@jberkus Josh, after reading your blog post I don't feel like I'm comfortable with help1.txt. Right now atomic expects man-formatted file named help.1, so I would like the list of expected filenames to be:

help.1
README
README.md

What do you think?

The https://github.com/projectatomic/ContainerApplicationGenericLabels definition of the HELP label for images is defined as "Command to run the help command of the image". The way Atomic CLI help was designed was as follows:

• If a HELP label exists, execute the command in the label.
• If a HELP label does not exist, look for a /help.1 file and display it using groff.

Again, this is because the HELP label was defined to allow users to have an alternate way to display help including a simple cat of a file that says "For more information about this image go to http://foobar/help"

That said, I think the general idea of allowing more types of help formats is a good thing and I would be very supportive of that. The thing I object to in the proposal is where it is suggested that for images with very little help, they should put the help text in the label itself. I don't like this use case because it is not in line with the label definition. We could change the label definition as one thought. Or we could use a label like HELP_TEXT or HELP_SHORT for that use case.

@baude thanks for feedback!

From the blog post:

This file will be submitted with the image proposal, and will be included
bout inside the container image and available online from
fedoraproject.org. The Help label will link to that URL.

Would it be okay then if the HELP label looked like this?

LABEL HELP="curl -s http://pkgs.fedoraproject.org/cgit/docker/cockpit.git/plain/README.md?h=f25"

This way the definition of the HELP label will be kept and the solution also satisfies the requirement.

Regarding text content:

 Images that need very little documentation (like libraries) will have that in the Help label as text. 

I'm in favor of moving such documentation to a different label. description label fits well:

Name         |  Required  |  Description
--------------------------------------------------------------
description  |  no        |  Detailed description of the image

@jberkus @dustymabe @maxamillion @baude are you okay with this?

@ttomecek i actually was thinking something more like this:

LABEL HELP='http://pkgs.fedoraproject.org/cgit/docker/cockpit.git/plain/README.md?h=f25'

The user can then choose to open that in the browser or use curl. I think what @baude was saying is that this doesn't fit the command description because it's not a "command to run".

We could get around this by having:

LABEL HELP='echo http://pkgs.fedoraproject.org/cgit/docker/cockpit.git/plain/README.md?h=f25'

or for containers with very simple "help":

LABEL HELP='echo "run the container like docker run fedora/apache"' 

Not sure if this is great, but it would work.

Unless we want to offend the spec that defines the label or change it, I think @dustymabe is on the right track. Use something like a echo. Again, happy to make changes to the atomic cli to have a secondary help label that we could just display as plain text. So if the help label is not existent but the secondary is, we'd just display the secondary one.

I personally don't feel competent enough to decide this. @jberkus what do you think about @dustymabe's proposal, would that be okay?

So:

• The reason for using HELP instead of "description" is the atomic CLI. Otherwise, I'd have used "description". So I'm fine with that switch ... except that atomic CLI has no interaction with "description", does it?
• "help1.txt" is due to someone's misinterpretation of "help.1", so that's fine.
• the reason we often need a help file is that the Docker LABEL format is extremely cumbersome with text more than a few lines.

So, let's back up on this requirement. Here's the essense:

The user of the container image should be able to access a moderately detailed description of how to use the image (equivalent to a man page), including the list of things mentioned above, whether or not they have access to public internet at the time.

Given that, it suggests that help files must exist both in the image and at the URL. For Atomic CLI, that's a bit of a dillemma. For users wanting to decide whether to install an image, we'd want the URL to take precedence, but for users who have a copy of the image and don't have connectivity, we'd want the local file to take precedence. That's assuming that the atomic CLI can respond to commands about an image it hasn't downloaded at all. Can it?

Do we want to simply discard the option of having a short description with no file? That'll only apply to a minority of images anyway.

Ref issues #243 #267

New requirements:

1. Every image is required to have a "description" label, which will be 1-3 lines of human-readable text on what the image is for. This description is meant to be searchable by skopeo.

2. Images are required to have either a "help" label or a "help" file, the latter being preferred. They should not have both.

3. The Help file can be named "help.1" or "README.md". It must be COPYd into the image and reside in the root directory.

4. If the maintainer prefers a "help" label, the label should include an executable command which displays a help page in some reasonable text format. Minimally, this could be as simple as "echo 'How to use this image'".

5. For users who don't use the Atomic CLI, we will offer simple instructions on how to display the help ("docker run --rm some:image /bin/cat help1.txt && /bin/cat README.md").

6. We will do nothing with URLs for the time being. Instead, we will implement a HELPURL system at some later date when we have the resources to do so completely automatically. In the meantime, help files are browseable on dist-git.

Does this work for everyone? In this case, the only required change to "atomic help" is supporting README.md. The reason we want that, btw, is for Github user friendliness.

seems reasonable. one small change I would make is that the description be only 1 line. I would prefer to only have one line even if it is a long line, I think.

Example of multi-line description is here: https://hhorak.fedorapeople.org/httpd-docker/Dockerfile
I think it works still quite well and looks better in the Dockerfile than one long line IMO.

Anyway, the New requirements seem fine to me, with those thoughts:

ad 3: I expect that OSBS in Fedora uses atomic-reactor that is able to convert and add the README.md from dist-git to help.1 and add the COPY command into the Dockerfile. Why not use this feature? It would limit the maintainer's responsibility to maintain README.md only.

ad 6: There is an 'url' label in the generic guidelines if anybody wants to point users to some URL: https://github.com/projectatomic/ContainerApplicationGenericLabels/

I like the new requirements: it should be clear to finish the implementation.

Is atomic meant to interact with description label in any way?

Example of multi-line description is here: https://hhorak.fedorapeople.org/httpd-docker/Dockerfile
I think it works still quite well and looks better in the Dockerfile than one long line IMO.

Yes, but what you are doing is breaking up what will be a single line into multiple lines when you define it. That is perfectly fine IMHO. What I didn't want was newlines in the actual value. I think what you have is fine, assuming I understand everything correctly.

You also have SUMMARY and DESCRIPTION. I think what we were proposing for DESCRIPTION actually matches more closely with what you have for SUMMARY. I know this is taken from rpm world, I just wonder if we need both.

Anyway, the New requirements seem fine to me, with those thoughts:
ad 3: I expect that OSBS in Fedora uses atomic-reactor that is able to convert and add the README.md from dist-git to help.1 and add the COPY command into the Dockerfile. Why not use this feature? It would limit the maintainer's responsibility to maintain README.md only.

I don't think we knew about this feature. Do you have a link to more details?

ad 6: There is an 'url' label in the generic guidelines if anybody wants to point users to some URL: https://github.com/projectatomic/ContainerApplicationGenericLabels/

interesting. I like it. url could be useful and I really like vcs-type, vcs-url, and vcs-ref as well. Is it able to automate adding those labels into the image with OSBS as well?

ad 3: I expect that OSBS in Fedora uses atomic-reactor that is able to convert and add the README.md from dist-git to help.1 and add the COPY command into the Dockerfile. Why not use this feature? It would limit the maintainer's responsibility to maintain README.md only.

I don't think we knew about this feature. Do you have a link to more details?

Big part of the atomic-reactor functionality is available via plugins, and this feature is available in the pre_add_help plugin:

https://github.com/projectatomic/atomic-reactor/blob/master/atomic_reactor/plugins/pre_add_help.py

The tool go-md2man is used to convert the README.md to help.1

So, for 3, we'll say that the maintainer needs to supply a help file, but they don't need to COPY it into the image, because OSBS will do that?

@jberkus it depends what configuration OSBS in Fedora is using. @maxamillion can you clarify?

We should also update https://fedoraproject.org/wiki/Container:Guidelines#LABELS with info that help label is meant to be command, not text.

Closing, all changes have been made per discussion.

I am still working on the PR for atomic.

I just updated the atomic PR: https://github.com/projectatomic/atomic/pull/941

The PR is merged: new release of atomic will be able to handle the workflow defined in this thread.