From 9f596a4883d2c18fc23bab1b088677ec6edeb639 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Thu, 20 Feb 2020 14:01:28 -0600 Subject: [PATCH 1/4] Add a warning about breaking changes This seems important after a recent breaking change (https://github.com/docker-library/postgres/pull/658), resulted in many confused and frustrated developers (https://github.com/docker-library/postgres/issues/681, https://github.com/docker-library/official-images/pull/7474#commitcomment-37304519) --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index 4e09d99d33..fb8462d44a 100644 --- a/README.md +++ b/README.md @@ -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 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. + +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: + +```yaml +# docker-compose.yaml +version: '3.3' +services: + db: + image: postgres:12.2@sha256:b2f01d9d6928992adc1b96cc57ea350ecd131f9f580961c4a95fc8c58553e3b5 + ... +``` + +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 ;) + ## 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). From becc30a2b3a9b3756e492b50487a881487c41269 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Thu, 20 Feb 2020 14:07:01 -0600 Subject: [PATCH 2/4] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fb8462d44a..5334bc724f 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ The [full image description on Docker Hub](https://hub.docker.com/_/postgres/) i ## Versioning Warning: ### Pin a digest to avoid breaking changes -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. +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 wherer 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 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: From 970999021d03e327bf7eb9a6cd89fb7c05c125c2 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Thu, 20 Feb 2020 14:09:08 -0600 Subject: [PATCH 3/4] More typos and corrections --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5334bc724f..4e97f8b41c 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ The [full image description on Docker Hub](https://hub.docker.com/_/postgres/) i ## 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 wherer it is used if you need 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 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: +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 instnace, in a Docker Compose configuration, you might use something like: ```yaml # docker-compose.yaml @@ -22,7 +22,7 @@ services: ... ``` -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 ;) +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? From 84f03dc950e9679315b48a7cdd0cb6abcdd84600 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Fri, 21 Feb 2020 12:41:46 -0600 Subject: [PATCH 4/4] One more typo! --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e97f8b41c..278f3aa383 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ The [full image description on Docker Hub](https://hub.docker.com/_/postgres/) i ### 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 instnace, in a Docker Compose configuration, you might use something like: +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