improve documentation

[yosifkit]

Creating a catch-all issue so we can list areas for improvement.

• SharedTags: explain what they are and when they are used
• reword in readme: "While official images are in the process of completing image indexes to make this work naturally"
• drop opensuse example: https://github.com/docker-library/official-images/blob/92a97a0d25fc3fd25cae28428f8be9849e4a02d4/README.md#instruction-format
• explicit time-since-last-update limit?
• image name guidelines?
• tightly-coupled software suites made of many images vs loosely-coupled
  • each image must fit the "generally useful" category on their own if they are to warrant their own library file
• limit build context (generally no Dockerfiles in upstream repo)
  • I.E. changes to files in the build context should be kept minimal to help keep our build context diffs easy to read so that we can continue to review quickly. If it becomes a large file that changes every release, it may make sense to include it in the upstream release (or released as a fully maintained project/example that can be downloaded by the image)
  • Add API-Firewall official image #11100 (comment)
• inclusion criteria (improve documentation #6282 (comment))
• embed/extend old best practices documentation
  • no alpine-pkg-glibc or mixing of Alpine releases with Edge or other releases packages (Explicitly disallow the use of "alpine-pkg-glibc" #10794)
• better detail on GPG/verification (perhaps a dedicated guide); Clarify gpg verification #11063
• [RFC] Let the community play a bigger role in the approval process #4615 (comment)
• document rc alias in image tags (generic pre-release marker): docker-library/docs #2349
• image tag best practice/definition. rough idea: [software-version]-[variant]-[related-package-versions]-[os-version]
• consider https://diataxis.fr/ (perhaps we choose one quadrant that we aim all our image documentation towards?)
• document jq-template somewhere/better (what is meaning of def in this template? golang#540)

"Since every change of every image is reviewed by humans, one of the criteria is that new images are "reasonably popular" to be able to get the most out of the available time we have."

[tianon]

SharedTags: explain what they are and when they are used

https://github.com/docker-library/faq#whats-the-difference-between-shared-and-simple-tags !! 😄

explicit time-since-last-update limit?

I'm not sure this is something we can add a generic limit for -- for example, cirros doesn't get many upstream updates, hello-world only updates for Windows, etc.

[james-crowley]

@yosifkit While updates to the documentation are happening, can we update the https://github.com/docker-library/official-images#architectures-other-than-amd64 section?

I wanted to fix the lines stating the unsupported architectures, as they have changed since the last time the README has been updated.

I know s390x and ppc64le is official supported now. I also think some of the arm architectures are now supported as well, but I am not as familiar with arm to say 100%.

[tianon]

Unfortunately, 18.06 was the last release where they were officially supported (see https://download.docker.com/linux/static/stable/ and compare x86_64 to s390x). 😔

[james-crowley]

@tianon Interesting! Do you have any insights as to why? I've been using 18.03 internal and have no moved to 19.X, so I must of missed the drop of support.

Well, at least you can update the arm information. It looks like the have builds for 19.X.

[tianon]

Great point, updated to include arm32v6 in df360fb 👍

(See also 10a69a5 for the commit which moved s390x and ppc64le out of the supported list 😞)

[james-crowley]

@tianon Thanks for the commit reference. Do you have a link to Docker stating the they are dropping support for s390x and ppc64le on CE?

I want to go investigate this, but the only thing I can find is the the downloads folder, which doesn't give me any context.

[tianon]

Unfortunately, docker/docker-ce-packaging#288 is the best I can find -- I don't think it was broadly announced anywhere, but could be wrong and just looking in the wrong places.

[james-crowley]

@tianon Thanks for the help in getting me that link. It is a good starting point to see what is going on.

Once s390x and ppc64le get back up and running, I'll make sure to post back here!

[samuelkarp]

Per offline conversation with @tianon: Another good thing to clarify in the documentation would be inclusion criteria (i.e., "Is $project a good fit to be included in the library?").