Before the era of Dockers, we would include a ReleaseNotes.txt file with each package we delivered. Admittedly the user had to install the package first, but having installed it, the ReleaseNotes.txt file would be sitting there on their server where they could easily read it, without having to start up the application. Now, when we deliver a Docker image, the ReleaseNotes.txt file is included, but it’s inside the Docker container, which makes it considerably less convenient for users to access. Moreover, there isn’t a straightforward way to get at them that doesn’t imply starting the application.
Has anyone come up with a better mechanism or is there some industry norm on how to deal with this, i.e. make the release notes conveniently available to users, in particular before they run the container?
Yes, the user could create the container without starting it, and do something like “docker cp” to copy the release notes file out, and read it. But I think that’s asking too much of them.
I would suggest to make them part of your update notifications to your customers. If you are sending an email: either attach it or embed a link to your online documentation.
Though, there is a potential risk that the operations team will never receive the attachement or the link to your online documentation.
If you provide some sort of refernce configuration (compose/swarm/kubernets), you could embed your release notes into that package.
For most situations I would agree with sending notifications. Unfortunately our situation is unusual. We “deliver” a large system as many separate components, each on its own schedule. We have only three “customers”, who mostly pull directly from our image registry, each on their own schedule. It can be months or even years between us making a component available and a customer taking it.
It may be that this arrangement is strange enough that I’ll never find anyone else with similar circumstances.
The idea of making it part of the reference configuration is interesting; I’ll give that some thought.