Short (80 chars) and long (Markdown-formatted) descriptions for images

[dhrp]

This is a ticket to discuss a new format for the container image description(s). The topic was brought up before in #556 and dotcloud/docker-index#45.

The proposal:

• One 80 character field (short description), plain, no tabs, no newlines.
• One big field (long description), allowing either Markdown or ReST (In which I would favor Md)

Doing so would allow the docker client to show easily readable search results (descriptions). The docker index can easily show rich descriptions, and the Docker client could show it, for example when an exact match is given: e.g. docker search dhrp/sshd will give the full text.

In dotcloud/docker-index#45 @johncosta pointed out a good usecase which requires a longer, more structured description. And amongst other things #556 shows we need to fix the description shown in the client.

Questions

1. What do we do with the docker file? Does it also contain these two description fields? None? Just the short description?
2. How do we handle tags? Does every tag has its own description or do we allow different descriptions for different tags.
3. How do we get people to add descriptions? (Set repository description from the client #596).
4. Do we use Markdown or ReST for the long description?

/cc @johncosta @kencochrane @vieux

[dhrp]

And here is what I think:

1. Just the short description
2. Descriptions are for an entire repository, not specific for a tag.
3. We should at least /allow/ the client to set the short description from the client, this will/ should propagate to the API. It is important to have descriptions, so people will find more images more easily.
4. I'd say Markdown. Outside the Python community more people are familiar with Markdown, in a big part because it is github's standard.

[johncosta]

@dhrp very nice summary!

1. +1 for just the short description in the Dockerfile
2. +1 for entire repository (vs by tag)
3. +1 for allowing the client to set the short description from the
   client.

How do we get people to add descriptions?

One approach might be to do the combination of:

A) not show matched results if a description isn't available - or said
another way, the reward for having a (short) description is that you show
up in search results

B) show a warning (cli & index) that projects without descriptions will not
show up in search results.

  4. +1 for Markdown

On Fri, May 31, 2013 at 4:50 PM, Thatcher notifications@github.com wrote:

And here is what I think:

1. Just the short description
2. Descriptions are for an entire repository, not specific for a tag.
3. We should at least /allow/ the client to set the short description
   from the client, this will/ should propagate to the API. It is important to
   have descriptions, so people will find more images more easily.
4. I'd say Markdown. Outside the Python community more people are
   familiar with Markdown, in a big part because it is github's standard.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/769#issuecomment-18770813
.

[shykes]

Scheduling for 1.0 since we're locking down the packaging format

[creack]

ping @dhrp. Any news on this?

[dhrp]

@creack I think I should ask you that question. I'd love to see this feature

See also:

#2167 with text about adding it to the dockerfile
and
#2956 for a patch

And
#1137 with information about how it is stored and displayed

[tianon]

I think this would be excellent in the context of stackbrew, where we currently don't have any good way to set the long or short descriptions of the images besides having someone benevolently set those attributes after the fact.

In the case of those, that's something that could be added to stackbrew instead, and not be tied to a specific tag (like anything we put in the Dockerfile today would be), but I'd love to see a generic solution for this, even for non-trusted and non-official builds.

What I'd like to see this used for in stackbrew especially is pointing people to a good place to report any issues with the images, especially since it's a little convoluted to find out the best way to report problems (comments on the images might as well go to /dev/null right now, since they have to be checked manually by the stackbrew image maintainer :P).

[olberger]

For traceability / auditability needs, I find it extremely important to be able to understand / check how images I can download and run have been produced. Having a kind of formal meta-data about the source of an image, not only a descriptive text would then be a nice improvement, IMHO.

[thaJeztah]

Just a thought; can we use labels for this? I.e.;

com.docker.distribution.description="My fantastic image!"

[thaJeztah]

Talked briefly with @stevvooe on this, and the registry V2 manifest specification has a provision for this.

[jessfraz]

Hello!
We are no longer accepting patches to the Dockerfile syntax as you can read about here: https://github.com/docker/docker/blob/master/ROADMAP.md#22-dockerfile-syntax

Mainly:

Allowing the Builder to be implemented as a separate utility consuming the Engine's API will open the door for many possibilities, such as offering alternate syntaxes or DSL for existing languages without cluttering the Engine's codebase

Then from there, patches/features like this can be re-thought. Hope you can understand.