Skip to content

Commit 9f596a4

Browse files
author
Joe Marty
authored
Add a warning about breaking changes
This seems important after a recent breaking change (docker-library#658), resulted in many confused and frustrated developers (docker-library#681, docker-library/official-images#7474 (comment))
1 parent 4dc16e4 commit 9f596a4

File tree

1 file changed

+18
-0
lines changed

1 file changed

+18
-0
lines changed

README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,24 @@ This is the Git repo of the [Docker "Official Image"](https://github.com/docker-
66

77
The [full image description on Docker Hub](https://hub.docker.com/_/postgres/) is generated/maintained over in [the docker-library/docs repository](https://github.com/docker-library/docs), specifically in [the `postgres` directory](https://github.com/docker-library/docs/tree/master/postgres).
88

9+
## Versioning Warning:
10+
11+
### Pin a digest to avoid breaking changes
12+
Docker "Official Images" use tags that correspond to the version of the application they contain an image of (in our case, Porstgres), and therefore do not typically have any way of indicating changes (even breaking changes) to the image configuration. Therefore it is highly recommended that you "pin" a specific sha-digest of this image wherer it is used if you need to avoid breaking changes.
13+
14+
The digest for every tag is available on Docker Hub. For instance, if you visit the [tags page for Postgres](https://hub.docker.com/_/postgres?tab=tags), and click on "12.2" you will see the sha-digest for the most recent build of "12.2" at the top of the page. This can be used to pin your image reference to that specific build of the image so that nothing will ever change in your environment unless you explicitly update it. For instnace, in a Docker Compose configuration, you might use something like:
15+
16+
```yaml
17+
# docker-compose.yaml
18+
version: '3.3'
19+
services:
20+
db:
21+
image: postgres:12.2@sha256:b2f01d9d6928992adc1b96cc57ea350ecd131f9f580961c4a95fc8c58553e3b5
22+
...
23+
```
24+
25+
Note: This also precludes you from receiving important security and bug-fix updates, so you'll have to remember to update the digest yourself on a regular basis. Choose your poison wisely ;)
26+
927
## See a change merged here that doesn't show up on Docker Hub yet?
1028

1129
For more information about the full official images change lifecycle, see [the "An image's source changed in Git, now what?" FAQ entry](https://github.com/docker-library/faq#an-images-source-changed-in-git-now-what).

0 commit comments

Comments
 (0)