#243 Require DESCRIPTION label for FLIBS containers
Opened 7 years ago by jberkus. Modified 7 years ago

We should require a "description" label in FLIBS containers. This would contain a long, narrative description of the container and how it's supposed to be used, intended for human readability. This would include, for all containers:

  • what service/software the container provides

It would also include all of the following which are applicable to the container:

  • what purpose it fulfills in a larger infrastructure
  • what each VOLUME in the container is for and what kinds of storage they need
  • any details about dependencies on other container images
  • links to documentation or software project pages
  • any special requirements the container has (like lots of RAM, or sound server access)
  • details on any required configuration, or links to documentation on configuration

Metadata Update from @jberkus:
- Issue tagged with: VFAD, containers

7 years ago

Metadata Update from @jberkus:
- Issue untagged with: VFAD
- Issue set to the milestone: 2017-03-10 VFAD

7 years ago

Do we want to include something like io.k8s.description and io.k8s.display-name too? Both labels also describe the image in some way, and both are used by tools like Kubernetes/OpenShift to display information about an image.

Update from VFAD:

The HELP label will link to a verbose description of how to use the container. For containers needing substantial instructions, the maintainer will check a file into dist-git called "help1.txt", "README" or "README.md". Fedora will ensure that this file has a public link. The maintainer will also have a copy of that file in the root directory of the container. For such images, the maintainer may choose to populate the HELP label with a URL pointing to the dist-git file, but is encouraged to have a one-sentence description before the URL.

Container Guidelines to be updated soon.

Metadata Update from @jberkus:
- Issue assigned to jberkus

7 years ago

@jhogarth ok, I merged your text with mine in Container:Guidelines. Please take a look.

Also, what we discussed during the meeting was requiring the help file (which could have any of three names) in the root of the image filesystem. No?

This issue now depends on the outcome of #256

New rules found in issue #256:

New requirements:

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.

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

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

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'".

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").

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.

Updated in Wiki.

@jasonbrooks now yours for notifying the maintainers.

Metadata Update from @jberkus:
- Issue assigned to jasonbrooks (was: jberkus)

7 years ago

Login to comment on this ticket.