Prefer os tags in How to use this Image sections

[dogweather]

Problem: There's a mis-match between the description sections and how the images are actually managed. This creates unrealistic expectations by users.

We're telling users, e.g.:

ruby:version
This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

However, that simplified tag doesn't reference a stable or immutable image. E.g., recently many "older" images were updated to base off newer or different OS's.

And so, a mountain of help docs, tutorials, etc. all advise to use that simple label type. And all the mysql-based ones are broken now. Since many people followed this advice, many production and development systems are broken as well.

Proposed Solution: All examples and instructions should use fully qualified labels such as ruby:2.6.3-buster instead of the currently advised style ruby:2.6.3.

[wglambert]

We do have a section in the faq about tags https://github.com/docker-library/faq#whats-the-difference-between-shared-and-simple-tags

Maybe we should make a link to that, currently there's no mention of the faq in any image documentation. I think the only link we have to it is in the official-images repo

[wglambert]

Relevant to docker-library/official-images#6282

[tianon]

We also do already have a blurb about these OS-specific variants, but we should probably improve it and move it up to be more prominent: (https://github.com/docker-library/docs/blob/b6419071dbd29a7cf1f693edc102fe0c8443e394/ruby/README.md#rubyversion)

ruby:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

This tag is based off of buildpack-deps. buildpack-deps is designed for the average user of Docker who has many images on their system. It, by design, has a large number of extremely common Debian packages. This reduces the number of packages that images that derive from it need to install, thus reducing the overall size of all images on your system.

Some of these tags may have names like buster or stretch in them. These are the suite code names for releases of Debian and indicate which release the image is based on.

[tianon]

I'm thinking we should swap the buildpack-deps section and the Debian section, and reword it to something like the following:

Some of these tags may have names like buster or stretch in them. These are the suite code names for releases of Debian and indicate which release the image is based on. If your image needs to install any additional packages beyond what comes with the image, you'll likely want to specify one of these explicitly to minimize breakage when there are new releases.

[tianon]

Here's the ruby example with the expanded text, to illustrate more precisely:

ruby:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

Some of these tags may have names like buster or stretch in them. These are the suite code names for releases of Debian and indicate which release the image is based on. If your image needs to install any additional packages beyond what comes with the image, you'll likely want to specify one of these explicitly to minimize breakage when there are new releases of Debian.

This tag is based off of buildpack-deps. buildpack-deps is designed for the average user of Docker who has many images on their system. It, by design, has a large number of extremely common Debian packages. This reduces the number of packages that images that derive from it need to install, thus reducing the overall size of all images on your system.

[tianon]

(I agree we should document "Shared Tags" better too, but I don't think this is the right place to do it since they're not technically related to this -- they're more related to tags that combine windows + linux under a single name, which these often do but not necessarily always.)