Developer experience: recommending a default container image

[rnorth]

Background

With #2839 and #3021 we are deliberately deprecating the practice of providing a default container image. One reason we have done this is to decouple Testcontainers from (a) a specific docker image, and (b) a specific version of an image.

We want to discourage and eventually block the usage pattern of new AbcContainer() and require all users to specify both the image and the tag for the container they wish to use.

Without doing this, we have no way of ever upgrading the default images safely. The problem is (was) worsened by the fact that new versions of an image involve not just changes to the tag, but changes to the image name or hosting registry, etc.

#3021 focused on letting module authors control the images that the module code is expected to be compatible with, while allowing users to still override that if they have an internal image that they're able to keep compliant with the module's expectations.

Principles we want to stand by

• A version bump to Testcontainers should not change docker images silently.
• If module code becomes incompatible with older versions of a docker image, we need to have a way to flag this loudly (e.g. fail fast with a noticeable error) rather than silently. The image compatibility checks should be the way to accomplish this in future.

Remaining challenge

We want to have a way for module authors to recommend the image that should be used with their module class.

One easy approach would be to expose this as a public constant, but this has an inherent problem: we would never be able to update the content of this constant without breaking the above principles. If we had a constant for a default image, it's not really any different to providing a no-args constructor all over again.

We need another way; something that is easy for users but does not re-create the version stickiness trap that we're just escaping from.

Ideas

@bsideup and I have discussed the first two of these, and I'd propose using a combination of one or more:

• make sure the docs recommend an image in usage examples
• recommend an image to use in the Javadocs
• do allow a public constant to be exposed, but never allow its value to be changed. We could have a version expressed in the constant name, e.g. ABC_DEFAULT_IMAGE_v5_3 = DockerImageName.parse("abc:5.3") or something like this.
• ... something else

All of these basically revolve around requiring the user to hardcode the image they want to use at development time.

[dadoonet]

I agree that the version should be defined by the user.
But we can simplify user's life by providing a default name (without the version).

Not a big deal though but found it convenient to have in #3350 .

I wished we could just use a CTOR(String version) but this CTOR is already used to parse an image name. 😏

[dadoonet]

What's the status on this one? Asking as this is "preventing" #3350 to be merged.

[rnorth]

Sorry, we will get to this, but have many constraints on our time at the moment.