cloudposse / geodesic

🚀 Geodesic is a DevOps Linux Toolbox in Docker
https://cloudposse.com/accelerate
Apache License 2.0
929 stars 117 forks source link

Update `README.md #customizing-your-docker-image` to use `debian-latest` instead of `2.0.0` #927

Closed OffensiveBias-08-145 closed 2 months ago

OffensiveBias-08-145 commented 4 months ago

Found a bug? Maybe our Slack Community can help.

Slack Community

Describe the Bug

Currently the code example for #customizing-your-docker-image sets the version to be 2.0.0 which was last built Mar 16, 2023 at 4:13 pm

ARG VERSION=2.0.0
ARG OS=debian
FROM cloudposse/geodesic:$VERSION-$OS

# Add configuration options such as setting a custom BANNER,
# setting the initial AWS_PROFILE and AWS_DEFAULT_REGION, etc. here

ENV BANNER="my-custom-geodesic"

Lets update this code example to use latest-debian to simplify the developer experience and promote up-to-date images.

Steps to Reproduce

Steps to reproduce the behavior:

  1. Go to https://github.com/cloudposse/geodesic#customizing-your-docker-image
  2. Copy and paste provided code snippet
  3. Build outdated image
  4. Encounter fun problems.

Expected Behavior

Example should be using latest-debian image instead of an image from 03/16/2023

Environment (please complete the following information):

ALL ENVS

Nuru commented 4 months ago

As a policy, Cloud Posse recommends always pinning modules to a specific version, to avoid surprises. In particular, we want to promote repeatable builds to the extent practical, and this is done by using explicit version pinning.

Using the latest tag is particularly problematic, because if your local cache has cloudposse/geodesic:latest-debian, it will not go and fetch the newer latest when one is released. On the other end of the spectrum, when we release Geodesic 3.0, it will have major breaking changes which will be sprung on people using latest without any kind of warning. That is a sad and disruptive state of affairs, but one we will not have a lot of sympathy towards because we have been warning people to use explicit version pinning for years, and the we consider the Semantic Versioning major version bump to be sufficient notice.

I will leave this issue open as a reminder to enhance the specific references with comments about where to find the latest version and when to update it.

OffensiveBias-08-145 commented 4 months ago

@Nuru Then simply update the documentation when major versions are released.

Providing documentation that is out of date (2.0.0) also causes headaches for developers.

Or just remove the templated version entirely and substitute a var. <VERSION>

Then everyone's happy.

Nuru commented 4 months ago

@Nuru Then simply update the documentation when major versions are released.

Well, we did update the documentation when the last major version was released. We are still on 2.x. The README is generated before the version is released, so it is impractical for us to keep it updated with the current version.

Or just remove the templated version entirely and substitute a var. <VERSION>

The document shows us setting a default for a command-line argument. I don't see the big difference.

I am keeping this issue open to remind me to update the document with more information about finding the latest version and how to set it.