Implicit release practices made explicit - when to cut a major release?

[consideRatio]

I don't think we have any documentation on how and when to make a major release (semver2 meaning) for projects, but I know I carry some ideas about it influencing me. I wanted to surface these and allow us to reflect and process thoughts about this topic as a first step towards possibly writing jupyterhub wide docs about the topic.

Thoughts

Major releases requires some toil and attention

Major releases comes with a need to communicate changes to users clearly, and users should show major releases some extra attention by for example reading the changelog. This makes major release come with some toil both for maintainers and users.

To accumulate changes a while

Since major releases require some toil from maintainers and attention from users, it can be reason to accumulate breaking changes to some degree before doing them instead of cutting them directly in any individual project.

To try to align major releases in time

We have distributions of software like z2jh and tljh that installs either exactly specified software versions (z2jh) or software pinned to its major version (tljh). Whenever a dependency makes a major release, it could be reason to mandate a major release in z2jh and tljh. Due to this, a sub-project that makes a major release can put some pressure on z2jh and tljh to make a major release as well, especially if an important bugfix or securityfix is included in the new major version of the dependency that isn't backported either.

To backport releases

Sometimes the jupyterhub project has backported releases with the help of a bot (@meeseeksmachine) and dedicated branches. Like that, a change can be merged into the main branch that demands a major release (like this https://github.com/jupyterhub/jupyterhub/pull/4495), while still making releases without it (like seen in https://github.com/jupyterhub/jupyterhub/pull/4535 from athe4.x branch).

I see backporting releases as a useful strategy that comes with some toil that can be worth it for both users and maintainers, but that doing it isn't always worth the extra toil. Currently we also lack documentation on how to make them, and that can also filter the people that ends up shouldering the responsibility of making them when needed.

Some of my implicit release practices now made explicit

• Cut patch and minor releases often
• Avoid breaking changes
• Phase in breaking changes if possible If something breaking can be made opt-in initially, where the actual breaking change in the end is just a change of the default value of some configuration - thats great. It helps in many ways, for example: a few users can help trial a change before its introduced to everyone, users gets time to prepare for a change, the need to backport releases with non-breaking changes isn't introduced when merging such change.

[manics]

What if we didn't align major releases across projects by default? Co-ordinating releases is a good thing if we have sufficient resources, but my impression from seeing comments on PRs and issues is that people put undue pressure on themselves to get multiple releases out.

An advantage of not aligning Z2JH and TLJH releases with the dependent projects should be increased stability for Z2JH and TLJH since the dependent projects will have had time to be tested by others.

[minrk]

Sorry, I wrote a response but closed the tab before sending. Trying to recall it from memory:

Thanks for writing this up! I especially love and agree with the summary bullet points at the end.

I would like to try to coordinate releases as little as possible. Certainly, there is some pressure when an upstream package has been released to propagate that downstream into releases in a reasonable amount of time, but I don't think it needs to (or even should) be immediate pressure. Taking more time to test before releasing allows distributions to represent a more stable view of things than individual packages themselves, which is appropriate_ I also think we shouldn't feel pressure to cut releases upstream when a downstream project is preparing a release. At least any more than "hey, just checking in, is there anything ready to be released already?"

The other angle I'd like to take to reduce some of this pressure is to make more small major releases, so it's not quite such a big event. The vast majority of major releases in packages I depend upon break nothing I actually use, so a major bump mostly means: check changelog for what broke; note that I don't use what it was; upgrade like any other release. I'd like give our users that experience as much as possible. That way, "missing" a major release isn't such a source of pressure because the next one doesn't need to be far off.