Is it time to start releasing major updates?

[milosmns]

I hope this is the right place to discuss; please redirect me if needed.

I'm a huge fan of the library and have been using AssertK for years (I remember when isEqualToIgnoringGivenProperties was added!). Looking at the latest releases of AssertK, particularly version v0.27.0, I've noticed that there are at least two intentional breaking changes included. As an end user, these minor version updates pose challenges because they require me to make additional code adjustments in my projects. For instance, now I am not able to seamlessly upgrade my projects without encountering runtime errors. If I had been using the v0.+ notation in my dependencies, a new AssertK release would definitely break my CI pipeline. I'd like to bring this up because I assume others face similar challenges.

With that in mind, I'd like to pose the question stated in the title:

:: Is it time to consider semantic versioning and increment major versions for breaking changes?

Some immediate follow-ups:

• Did you have any thoughts about this already?
• Is the versioning guide written somewhere?

And of course, a big thank you for building this library as well as your attention to this discussion. ❤️

[JakeWharton]

Note that semantic versioning says the following:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Usually a minor release in the 0.x major version indicates a breaking release or significant feature addition, and patch versions are for compatible changes (although not strictly required by semantic versioning)

If I had been using the v0.+ notation in my dependencies, a new AssertK release would definitely break my CI pipeline.

If you use a wildcard or dependency-range syntax you should really be using a lockfile to ensure reproducibility. That file gets updated explicitly to pull new versions.

Otherwise yes this will always result in a broken build. Even with a stable API from the perspective of semantic versioning only the binary API surface is covered. A new overload could change function resolution, deprecation as error or hidden can remove symbols. You are not safe from changes that require human intervention even with a 1.x version.

[milosmns]

Thanks for the quick response!

If you use a wildcard or dependency-range syntax you should really be using a lockfile to ensure reproducibility. That file gets updated explicitly to pull new versions.

I do understand the rationale behind the behavior of wildcard or dependency-range syntax, and you're right that using a lockfile would ensure reproducibility in such cases. I consider this an edge-case, and wouldn't like to focus on it too much. It was added only as an additional example to illustrate what could happen when project updates are fully automated.

Even with a stable API from the perspective of semantic versioning only the binary API surface is covered. A new overload could change function resolution, deprecation as error or hidden can remove symbols. You are not safe from changes that require human intervention even with a 1.x version.

Fair point, agreed as well. I think that what you mentioned is clear – there's nothing that can really stop us from breaking downstream builds. I'd also like to not focus on unintentional changes, acknowledging that many of the breaking changes are completely unintentional and hard to prevent.

---

My main point of concern was related more to the intentional/planned breaking changes – authors deciding to deprecate something, making an intentional migration to a new language version, etc. Downstream project changes coming from planned library changes are (hopefully) preventable by clearly communicating about it.

Releasing only minor updates may not always communicate the full scope of intentional changes to end users. In such cases, I feel like a major version increment could serve as a clear signal that significant changes are included in the release. This would help users anticipate and prepare for any necessary adjustments in their projects.

We could expect the end user to visit the release pages of each dependency and manually inspect for breaking changes. However, that doesn't seem necessary, especially when it requires minimal effort to simply increase the major version number as a clear indicator.

Do you feel like that's not the best approach? As an alternative to that versioning strategy, what would be a good reason to increment a major version instead?

[evant]

This is how I think about pre 1.0 versions with semantic versioning if that helps:

1. As a rule you expect more breaking changes than you'd have with a something 1.0, starting with a 0 serves as that warning
2. The second number ends up playing double-duty both denoting potential breaking changes and feature adds
3. The patch version remains as bug fixes

That being said, it may be worth moving assertk to 1.0, it's been at 0.x for a long time now and breaking changes have certainly slowed down.

I also want to note that kotlin version bumps are normally not treated as major breaking changes in the kotlin ecosystem so that's something you should keep in mind.

[milosmns]

Yeah, that makes sense as well. Thanks for writing it down for me. 💚

I'd personally upvote going to 1.0.
Saying this as a long-time user, I believe that it's "stable" and safe to use. We've been using AssertK to test apps and services with millions of active users, there would definitely be feedback from the field if there was an issue.

Either way, you've answered my question. Feel free to close the discussion or mark it as answered.

Thanks!

[evant]

The next version will be 1.0.0

[milosmns]

Good to know, ty!