Concepts of readme files - accetto/ubuntu-vnc-xfce-g3 GitHub Wiki

Concepts of README files

Version: G3v2

Updated: 2022-11-04

Introduction

Publishing of README files is probably the most problematic part of building images for the Docker Hub.

Some of the Docker Hub disadvantages are:

  • Automatic re-publishing of README files is possible only as part of re-building the images
  • The auto-builder is looking only for the files that follow some pretty rigid naming rules
  • There is by default only one common README file for the GitHub and the Docker Hub
  • The length of the README file on the Docker Hub (actually the length of the long repository description) is limited to 25000 bytes

This pages describes the concepts that should mitigate the Docker Hub disadvantages.

It can help to read about the Concepts of Dockerfiles and Concepts of building first.

Concept of separated README files

By separating the README file intended for the Docker Hub from the README file intended for the GitHub it's possible to solve the problem of the length limit and also to mitigate some other problems described above.

For each Docker image there will be two README files:

  • README-dockerhub.md is intended for the Docker Hub
  • README.md is intended for the GitHub

Only the final length (see also below) of the README-dockerhub.md is limited to 25000 bytes.

The README file for the Docker Hub is prepared off-line by a provided utility and then transferred to the Docker Hub.

Concept of dynamic README files

This concept is about updating the README file before publishing it. This allows including some up-to-date dynamic data, for example the version stickers.

Concept of templated README files

This concept is about including variables into the README file templates and replacing them by the up-to-date data during the preparation for publishing.

Concept of README file composition

This concept is about composing README files from several separated parts. Some of them can be templated.

In the current implementation there is a composition of the main README-dockerhub.md file and the readme-append.template appendix file. The latter one contains the hyperlinks of the version sticker badges that contain some replacement variables.