Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a warning about breaking changes #689

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add a warning about breaking changes #689

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9f596a4
Add a warning about breaking changes
Feb 20, 2020
becc30a
Fix typo
Feb 20, 2020
9709990
More typos and corrections
Feb 20, 2020
84f03dc
One more typo!
Feb 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,24 @@ This is the Git repo of the [Docker "Official Image"](https://github.com/docker-

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).

## Versioning Warning:

### Pin a digest to avoid breaking changes
Docker "Official Images" use tags that correspond to the version of the application they run (in our case, Postgres) and therefore do not typically have any way of indicating changes (even breaking changes) to the image configuration in their tags or "version numbers". Because of this, it is highly recommended that you "pin" a specific SHA digest of this image wherever it is used if you need to avoid breaking changes.

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 sha256-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 instance, in a Docker Compose configuration, you might use something like:

```yaml
# docker-compose.yaml
version: '3.3'
services:
db:
image: postgres:12.2@sha256:b2f01d9d6928992adc1b96cc57ea350ecd131f9f580961c4a95fc8c58553e3b5
...
```

Note: This also prevents 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 ;)

## See a change merged here that doesn't show up on Docker Hub yet?

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).
Expand Down