Clarify backwards compatibility policy

[alexkiro]

As of #954 setuptools was completely removed from the python3.12+ base images, which is not the kinda of change I would have expected from this version.

It would be helpful to have some clarifications on what kinda of changes to expect from the images, and if there are versions of the image that are locked or will be locked so we can update them without risk of breaking everything and still get security updates.

[alexkiro]

I image that freezing/locking the current python latest version would be far too limiting for the docker image, and not provide the flexibility to adapt to newer changes. (which I can definitely understand if that was the case)

My suggestion would be to simply freeze the version before the latest. E.g. right now 3.11 would be locked and when python 3.13 releases later this year images of 3.12.* would be stop receiving any backwards incompatible change, and just continue with patch version updates and security patches/fixes.

I think there is a significant group of users (myself included) that would rather stay one or two version behind if that gives more stability and lower maintenance. (akin to the practice of having LTS version of software)

[edmorley]

Hi! Thank you for starting this discussion, I think it's useful to have.

(I'm not a maintainer of this repo - so these are just some thoughts of a random person...)

In general I think breaking changes aren't made in this repo unless it's when introducing a new major python version.

IMO the aspects that made it worth making an exception for #954 were:

• That it effectively was a bug fix to the original python 3.12 release of these images (a breaking bug fix, but still a fix, given the intent always was to not include setuptools in these images).
• The only packages that are broken are those that are already broken in most other python 3.12 environments/tooling.
• That if this change had been instead deferred to python 3.13, then the python 3.12 images in this repo would have forever been out of alignment with the python stdlib and rest of ecosystem (which stopped installing setuptools for 3.12+).
• That unlike the images for python 3.11 and earlier, for the python 3.12 images, the version of setuptools was no longer pinned (a side effect of the original attempt at excluding it from those images when 3.12 support was first added), which means that any update of the 3.12 images (even those just to pick up Debian image security updates) would pull in new major versions of setuptools. And setuptools has been making lots of breaking changes recently, so the python 3.12 images were already shipping regular breaking changes. (At least now they won't)

The only thing I can think of that could have been done to reduce the chance of impact, is if it had landed with the next 3.12.x release (ie 3.12.6), rather than a regeneration of the existing 3.12.5 release. That said, there have been less than half a dozen people leave either comments or reactions on the relevant issues, so I think the impact was still actually quite small. (At the scale of these images, if the impact was widespread it would have resulted in hundreds of comments etc.) Not that that's any consolation for the people who were affected of course!

So overall I think this most recent change was a hopefully rare edge case (where none of the options are great), that won't need be repeated again any time soon.

[alexkiro]

@edmorley Makes a lot of sense; the unpinned setuptools is definetly something great to get rid of, and could have potentially cause more damage in the future. If these case are just very rare and low impact, it's probably better to keep the release system simpler rather than complicated them with a freeze/lock timetable.

But if more allowance is needed for the maintainers of this repo, to have the ability to make more breaking changes after python releases, I definetly think that it would be more than reasonable to have a grace period. Maybe something to consider if it ever get to that point 😄

Thanks for taking your time to write such a detailed reply!

[tianon]

Yeah, we generally try to avoid breaking changes, but in many cases we have to choose between "bad and bad" and oftentimes one ends up being worse for one reason or another, and this was one of those cases (as Ed put much more eloquently than I have 😅 ❤️).

I know "best effort" isn't exactly what you want to hear, but the fact that it was a surprising event hopefully lends some credence to us generally doing an OK job of avoiding it. 😄