Developer experience: recommending a default container image

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.

Start by reviewing issues #2839 and #3021 to understand the existing image-deprecation and compatibility work. No files or tests are named; evaluate the proposed documentation, Javadoc, versioned constant, or other approach against the stated principles. Done requires a decided design for recommending images without silently changing them.