docs: updating docker tags and defining them#664
Conversation
Deploying localstack-docs with
|
| Latest commit: |
d89c0ce
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0a2c5522.localstack-docs.pages.dev |
| Branch Preview URL: | https://doc-238-docker-img-tags-upda.localstack-docs.pages.dev |
remotesynth
left a comment
remotesynth
left a comment
There was a problem hiding this comment.
I am approving because the content seems fine, however I noted that a couple of the images appear to be missing the nightly images. I am not sure if this is something we should remove on our end or if there is a mistake on the deployments (maybe there will be one made tonight and it's just missing at the moment 🤷 ). Let's confirm before merging.
| |---|---|---| | ||
| | `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds | | ||
| | `dev` | Every merged commit on `main` | Users who need the latest unreleased changes | | ||
| | `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence | |
There was a problem hiding this comment.
Can we reconfirm that this image should exist? We've said that it should but I am not seeing a nightly on either AWS or Snowflake, only on Azure.
There was a problem hiding this comment.
These should exist for AWS and Azure - Snowflake doesn't support this but can support this with a small change, it's just not something that has been set up yet. I can update this tomorrow so there's consistency if that's something we want for consistency!
In terms of why AWS hasn't got the nightly tag yet, it's because the PR to add these was added yesterday, but todays scheduled run didn't complete successfully (see here). Once there is a successful run it will exist 👍🏼
|
hey @aidehn would you be ok to give this a engineer review? i want to make sure i understood the changes for each product line |
| - This tag can be used if you really want to avoid any changes to the image (not even minimal bug fixes). | ||
| We publish a set of image tags with different semantics, updated on different occasions: | ||
|
|
||
| - **`latest`**: Updated only on official tagged releases (e.g. `2026.05.0`). Equivalent to `stable`. Recommended for most users who want a stable, release-quality image. As of May 2026, this tag no longer tracks untagged commits on `main`, use `dev` for that behavior. |
There was a problem hiding this comment.
Left a similar comment on the release notes, it could be beneficial to give an example of a patch too (for that monthly version) to show this also includes patches for that monthly release!
... only on official tagged releases (e.g. `2026.05.0`, `2026.05.1`)
| - **`stable`**: Same as `latest`. Updated with every official release. | ||
| - **`dev`**: Contains all merged, untagged commits from the `main` branch. Use this if you want the latest unreleased changes. | ||
| - **`nightly`**: Pushed from scheduled nightly builds. Useful for CI pipelines that benefit from a fresh build on a predictable cadence. | ||
| - **`YYYY.MM`** (e.g. `2026.05`): Updated with each patch release within that month. Use this to avoid feature changes while still receiving bugfixes. |
There was a problem hiding this comment.
nit: I would potentially avoid the term "bugfixes" here when talking about patch versions as the patch releases main purpose is to provide security fixes and dependency updates! (not something to mention here, but we generally avoid making any functionality changes in these patch releases unless essential 👍🏼 )
| | `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds | | ||
| | `dev` | Every merged commit on `main` | Users who need the latest unreleased changes | | ||
| | `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence | | ||
| | `YYYY.MM.patch` (e.g. `2026.05.0`) | Never (pinned) | Fully reproducible environments where no changes are acceptable | |
There was a problem hiding this comment.
Azure is an odd one since they don't have a tagged release process their definitions for each are different!
- For Azure,
latest==dev- it is the latest commit frommain - There are no
stabletags since they don't support a tagged release process (stable is only updated in these scenarios) - There are also no
YYYY.MM.patch,YYYY.MMandYYYYtags for the same reason as the above
So, overall we just need latest, nightly and dev and dev == latest!
| ``` | ||
| | Tag | Updated when | Recommended for | | ||
| |---|---|---| | ||
| | `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds | |
There was a problem hiding this comment.
Snowflake has the same definitions as AWS so all good here, but nightly isn't supported just because the repo doesn't currently run the workflows every night - this can be updated for customers without the need for a release though if we wish for this to be the case 👍🏼 /cc @remotesynth
aidehn
left a comment
aidehn
left a comment
There was a problem hiding this comment.
Thank you for the documentation updates!! I left a few comments about the wording of relating bug fixes with patch releases + the Azure tag definitions (as they are quite different than AWS and Snowflake!) Once done I think we should be good to go 🎉
|
You rock 🤘🏽, thanks for the feedback @aidehn |
|
good catch @remotesynth, tyvm |
|
Update: PR to add |
3 participants
Fixes https://linear.app/localstack/issue/DOC-238/document-docker-image-tags-and-their-meanings