To elaborate on Petr's point a bit: there is some ambiguous documentation about help files in Fedora now. With this issue we would like to:

1. reach consent
2. update the documentation

To be more precise:

Maintainers should include a copy of this help file in the base directory of their images.

Is this sentence about dist-git? Does it mean that image maintainers should (or even have to?) COPY help.1 /? I am asking because latest image of mine is doing COPY ./root/ /, does it violate the policy?

Container review process contains this sentence:

Required files should be: 

* Dockerfile
* help.md file

I don't personally understand whether it's a must-have or should-have. It is also inconsistent with container guidelines because those talk about help.1 and README.md.

I propose to remove the information about help files from the review process document and just have the information in guidelines only. The other thing is that we should reach conclusion on whether there is a mandatory dist-git repo structure.

I'm not sure whether this is good issue to discuss this, but I'd change the *.md example above, because:

• atomic reactor automatically adds the groff header now (https://github.com/projectatomic/atomic-reactor/commit/6183be095993b391d9a1144634c28c350712dbc6) so we don't have to ruin the markdown with those things

• tables are not converted properly by go-md2man, which is used by atomic-reactor, so I'd propose not to use tables in the readme if we want to continue generating the help.1 from markdown, but rather use something like:

**`MEMCACHED_DEBUG_MODE`**  
       Increases verbosity for server and client. Parameter is -vv

**`MEMCACHED_CACHE_SIZE (in megabytes)`**  
       Sets the size of RAM to use for item storage

**`MEMCACHED_CONNECTIONS (default is 1024)`**  
       The max simultaneous connections

We discussed this in https://github.com/sclorg/postgresql-container/pull/185 as well.

Container review process contains this sentence:
Required files should be:

• Dockerfile
• help.md file

I don't personally understand whether it's a must-have or should-have. It is also inconsistent with container guidelines because those talk about help.1 and README.md.

I totally agree. I believe we should be as specific as we can be to give a consistent help system to users. Being explicit on the help guide would go a long way.

In my mind there should be two files:

• README.md: gives a quick description/overview. This is more open ended.
• help.md: gives man like information. This should be strict.

The structure of help.md should be based of a standard template that is filled out for the specific image.

Is this sentence about dist-git? Does it mean that image maintainers should (or even have to?) COPY help.1 /? I am asking because latest image of mine is doing COPY ./root/ /, does it violate the policy?

I think as long as the file makes it into the root of the image it doesn't matter how it gets there. I think the typical way to do it would be to take the file from dist-git and copy it into the image.

In general, I do want to make sure we don't make things to complicated for new users. We definitely need consistent guidelines, but I wonder about making there be too many fields in required help files.

Can I get someone to summarize exactly what the new proposed guidelines would be (highlighting proposed changes and explicitly stating any text to remove)?

In general, I do want to make sure we don't make things to complicated for new users. We definitely need consistent guidelines, but I wonder about making there be too many fields in required help files.

Agreed, we should never make something that makes peoples lives more burdensome with little or no benefit.

Can I get someone to summarize exactly what the new proposed guidelines would be (highlighting proposed changes and explicitly stating any text to remove)?

I'll throw a template together based on the above to get us started.

README.md

A quick description and general human helpful text. Similar to what would be in a repo

help.md

Original Help

Container Guidelines: Help File

Defined:

• Volumes: map of volume name: description
• Ports: map of port_number: description
• Documentation: Link to online documentation
• Requirements: Human friendly text describing what the container needs to run
• Configuration: Human friendly text describing information on how the container is configured

Stricter Help

Mimics man style:

• Header:
  -- IMAGE_SHORT_NAME(1)
  -- Person who wrote the document
  -- Last updated
• Name: IMAGE_SHORT_NAME: IMAGE_SHORT_DESCRIPTION
• Description: IMAGE_LONG_DESCRIPTION
• Usage: Command(s) that can be used to install the container (IE: docker example, atomic example)
• Environment Variables: Two width table listing available Variable Name and Description
• Security Implications:
  -- Ports: Ports opened/used by the container (maps to Original Help's Ports)
  -- Volumes: Volumes used by the container (maps to Original Help's Volumes)
• See Also: Further reading (maps to Documentation of the Original Help)

Example and Untested Template

Note: This is not meant to be THE template, just a starting point to refine.

- {{ IMAGE_NAME|upper }}(1) Container Image Pages
- {{ IMAGE_AUTHOR }}
- {{ IMAGE_DOC_DATE }}

# NAME
{{ IMAGE_NAME }} - {{ IMAGE_SHORT_DESCRIPTION}}

# DESCRIPTION
{{ IMAGE_LONG_DESCRIPTION }}


# USAGE
{{ IMAGE_USAGE }}

# ENVIRONMENT VARIABLES

The image recognizes the following environment variables that you can set
during initialization be passing `-e VAR=VALUE` to the Docker run command.

|     Variable name        |       Description                                           |
| :----------------------- | ----------------------------------------------------------- |
{% for _name, _description in IMAGE_ENVIRONMENT_VARIABLES.iteritems() %}
| `{{ _name|upper }}`   | {{ _description}} |
{% endfor %}

# SECURITY IMPLICATIONS

## Ports
|     Port Container | Port Host  |       Description             |
| :----------------- | -----------|-------------------------------|
{% for _ports, _description in IMAGE_PORTS %}
| {{ _port[0] }} | {{ _port[1] }} | {{ _description}} |
{% endfor %}


## Volumes
|     Volume Container | Volume Host  |       Description             |
| :----------------- | -----------|-------------------------------|
{% for _vols, _description in IMAGE_PORTS %}
| {{ _vols[0] }} | {{ _vols[1] }} | {{ _description}} |
{% endfor %}


# SEE ALSO
{{ IMAGE_SEE_ALSO }}

This make sense to me, but be careful go-md2man does not transform tables yet. We have already detected the issues here https://github.com/container-images/container-image-template/issues/3

I have filed a RFE for it https://github.com/cpuguy83/go-md2man/issues/31

Issue go-md2man is closed. Transformation tables from MD to ROFF works properly.

Issue go-md2man is closed. Transformation tables from MD to ROFF works properly.

Awesome! Thanks @phracek!

so is help.md required? We have images which are basically library components. Should they have this file as well?

also, if there are images which have a single executable file, which itself supports --help, or has a man page, shouldn't that be the help?

@jberkus the pragmatist in me says library only images wouldn't need a help.md, however libraries sometimes have man pages giving some information as to how they can be used or where headers can be found, etc... so I feel like the answer could be yes. (EX: man glibc, man libxml, etc..)

In terms of those single binary images which support --help then pandoc (or similar) could be used to generate the help.md from the available man page.

So are you suggesting that FLIBS should have the capability of genating files based on --help and/or existing man pages? That would be ideal.

If we ask the submitter to do it, that has the dual issues of (a) extra work and (b) not being kept up to date.

@jberkus If it can be done automatically then it probably should be done automatically. However, there will probably be some amount of editing needed. For instance, a help.md generated from a man page will likely not have information on security considerations such as what the container mounts ports that are exposed. It probably could be automated but I'm not sure if that would be in the scope of defining a format.

Well, that's a bit of a dillema. If there's manual editing involved, then it's One More Thing To Keep Up To Date, which means it won't be.

What I'm suggesting is that we should allow automatic conversion as an alternative, even if it doesn't adhere to the format.

I believe this was meant to solidify the help and to provide information specific to the container, but I'll defer to @phracek in terms of the original reasoning for this request.

I would prefer some kind of templating, like if it is possible to generate some information from man pages I will vote for it. Something like this.

help.md.template will contain specific issues like security warnings, environment variable, mount points and stuff like that.
help.md itself can be generated like man2md and append help.md.template which is not so hard to keep up2date.

It would be awesome if all our container images required help files -- for me it's so outraging when executables don't have man pages, and the same applies for containers.

Also, if we use the template @smilner proposed, it's very easy to edit it with basic info how to use the container.

I like the idea of having in-container help, but personally one of the things I love about github is the fact that it renders README.md files so prominently. I also find myself often wanting to look at the "source" for our containers; I may not want our exact container build, but I want to do something similar or use a different base image. So we could do the same with https://src.fedoraproject.org/ ? (Which really needs a browsable UI for just containers or just modules)

@walters src.fpo does render README.md — see for example https://src.fedoraproject.org/rpms/calc. Is there something missing?

(Which really needs a browsable UI for just containers or just modules)

Like https://src.fedoraproject.org/projects/container/%2A
and https://src.fedoraproject.org/projects/modules/%2A

I think maybe what it really needs is a way for that to be discovered more easily. Currently the only way I know is to pick a specific project and then go back with the navigation breadcrumbs.

The structure defined by @smilner is fine from my point of view.
But some digging. I guess, IMAGE_NAME, IMAGE_AUTHOR and IMAGE_DOC_DATE should start with % instead of -.

One more question.
Where the help file should be stored in dist-git? In dist-git root directory or in help directory?

@phracek As long as we are consistent and the help.md and help.1 are copied to the image at / either is fine IMHO.

I don't know if this got lost because I changed topic, but if you have README.md at the top level of dist.git, this will be displayed on https://src.fedoraproject.org/. See for example

https://src.fedoraproject.org/container/tools

Now, maybe this should differ from the in-container help.md and be more focused on contributor/developer information. But I kind of think they could be the same in most cases.

@mattdm README.md still make sense IMHO. help.md/help.1 is more like a man page for users who have pulled the container and would like information on usage.

I started working a bit on the generation utility. Any ideas for decent names? Naming is the hardest part :-)

image-helpgen

or just helpgen

@jberkus thanks for the suggestions. I think helpgen is overloaded. There is a Python library and a company with that name. However, nothing came up quickly searching for image-helpgen. I'll run with that for now.

First pass on code here. Example output also provided. @phracek / @jberkus / et al

I'll be doing some clean up on the code and then, if there is no more feedback I'll make a release of the tool and open a tracking issue for the next steps.

Tagged a release: https://github.com/ashcrow/image-helpgen/releases/tag/1.0

Unless there are objections I'd like to consider this issue done and open up a few follow on issues. Specifically:

• How to provide information not normally housed in a Dockerfile to populate description fields. Example: expose doesn't describe why a port is exposed
• How to hook this into FLIBS/Container Reviews/Whatever makes sense.

Tagged a release: https://github.com/ashcrow/image-helpgen/releases/tag/1.0

straight to 1.0 :). I like it.

Fortune favours the bold!

image-helpgen looks awesome. I am glad we decided, help.1 will be present in image at location /. Now we will include some sanity checks into MTF (https://github.com/fedora-modularity/meta-test-family) or into conu(https://github.com/fedora-modularity/conu/) and detect whether help page contains proper information.

image-helpgen looks awesome. I am glad we decided, help.1 will be present in image at location /. Now we will include some sanity checks into MTF (https://github.com/fedora-modularity/meta-test-family) or into conu(https://github.com/fedora-modularity/conu/) and detect whether help page contains proper information.

Thanks @phracek! Will that be tracked in a different issue? If so maybe it makes sense for this one to close.

closing please open follow on issues if needed.