From 262d7147513392b2d3046798ab15e6ebfdb6e910 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sun, 9 Jul 2023 11:31:13 +0200 Subject: [PATCH] Add ADR for latest docker image publishing change --- ...t-docker-image-only-for-actual-releases.md | 52 +++++++++++++++++++ docs/adr/README.md | 1 + 2 files changed, 53 insertions(+) create mode 100644 docs/adr/2023-07-09-build-latest-docker-image-only-for-actual-releases.md diff --git a/docs/adr/2023-07-09-build-latest-docker-image-only-for-actual-releases.md b/docs/adr/2023-07-09-build-latest-docker-image-only-for-actual-releases.md new file mode 100644 index 00000000..aad742f9 --- /dev/null +++ b/docs/adr/2023-07-09-build-latest-docker-image-only-for-actual-releases.md @@ -0,0 +1,52 @@ +# Build `latest` docker image only for actual releases + +* Status: Accepted +* Date: 2023-07-09 + +## Context and problem statement + +Historically, this project has re-tagged the `latest´ docker image every time a PR was merged into default branch. + +The reason was to be able to: + +* Periodically test the docker building and publishing process. +* Provide "partial" images for quick testing of new "un-released" features. + +However, this was considered non-stable, and not recommended to use in production. Instead, a convenient `stable` tag was provided, which was re-tagged for every new non-beta/non-alpha release. + +The approach described above for `latest` has some problems, though: + +* Many people ignore the recommendation of not using it in production. There have even been reports of bugs on things which were, technically speaking, not yet released. +* Since it is not always built for an actual new project version, the project itself cannot inform about anything other than `latest`, which can quickly become a lie if you don't update your local version. + +## Considered options + +* Try to provide a pseudo-version when `latest` is built. Something like `-. +* Change how `latest` is published, and start tagging it only for actual new version releases. +* Same as the above, but exclude alpha/beta versions, deprecating `stable` tag. + +## Decision outcome + +Since testing un-released features has never been needed, it is probably a not-very useful thing to have. + +Periodically testing the build and publish process can also be moved somewhere else, like a testing "hidden" account. + +Also, having `stable` with non-alpha/non-beta releases seems sensible, so the decision is to "Change how `latest` is published, and start tagging it only for actual new version releases". + +## Pros and Cons of the Options + +### Try to provide a pseudo-version when `latest` is built. + +* Good: because we keep publishing process intact, from a user point of view. +* Bad: because it requires adding some non-trivial logic to the image building, which needs to find out what was the latest stable release. + +### Make `latest` hold latest published version, including unstable releases. + +* Good: because it provides a way for users to test bleeding-edge features, with less risk than relying on the very last content from default branch. +* Good: because it allows for `stable` to be used together with `latest`. +* Bad: because partial features cannot be tested without publishing an alpha or beta version. + +### Make `latest` hold latest published version, excluding unstable releases. + +* Bad: because there's no longer a way to test bleeding-edge features, other than installing that specific version. +* Bad: because it drives `stable` useless, which means it needs to be deprecated, documented, and eventually removed. diff --git a/docs/adr/README.md b/docs/adr/README.md index 9d87a0fb..bafb80b5 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -2,6 +2,7 @@ Here listed you will find the different architectural decisions taken in the project, including all the reasoning behind it, options considered, and final outcome. +* [2023-07-09Build `latest` docker image only for actual releases](2023-07-09-build-latest-docker-image-only-for-actual-releases.md) * [2023-01-06 Support any HTTP method in short URLs](2023-01-06-support-any-http-method-in-short-urls.md) * [2022-08-05 Support multi-segment custom slugs](2022-08-05-support-multi-segment-custom-slugs.md) * [2022-01-15 Update env vars behavior to have precedence over installer options](2022-01-15-update-env-vars-behavior-to-have-precedence-over-installer-options.md)