Semantic Versioning Sucks! Long Live Semantic Versioning

With Spring Boot we actually decided to intentionally not use semantic versioning. We found it too rigid for our needs because we’d need to bump the major version too frequently. Instead, we try to take a more pragmatic approach where we’ll try to ensure back-compatibility, but will occasionally choose to break things if we feel like that’s ultimately the best option.

Instead of true semantic versioning, we instead use the version number to indicate the amount of pain users might expect with an upgrade. The general rule is:

With that in mind, your questions are still valid if you remove the word "semantic" so here are the answers:

How do you do semantic versioning for Spring Boot? Is it manual or automated?

It’s a manual process. We’ve got quite a bit of experience evolving APIs so we tend to know when a change will cause problems.

If automated, what tools do you use to validate a patch or minor release doesn’t break anything?

We don’t have any automated tools. We do however review each others commits to try and spot issues early. We also have a great user community that lets us know when we break things. :)

If manual, how do you guarantee you aren’t breaking backward compatibility?

We don’t make strong guarantees. We mainly rely on our own experience to ensure we don’t do anything foolish. We only add new features in minor versions so most patch releases are bug fix only and hence API changes are rare.

Our semantic versioning in Spring is not strictly about backward compatibility, it’s rather a form of pragmatic impact guidance along the lines of generation / feature release / maintenance release (e.g. 5.2.3). This is an entirely manual part of our design process where "generation" means a fundamental revision of the codebase (mostly JDK baselining but also e.g. nullable annotations and Kotlin extensions in 5.0) including some pruning and module rearrangements, "feature release" means a rich set of new features (including refactorings and re-implementations of existing features) but all within the existing framework architecture and its structural arrangements, and "maintenance release" means bug fixes and minor enhancements.

We compare API diff reports between releases and run Animal Sniffer for JDK baseline enforcement, but otherwise, there are no tools involved. Backward compatibility (in particular binary compatibility between maintenance releases) is mostly covered through integration tests, no guarantees attached…​ Sometimes we have to fix regressions after the fact, doesn’t happen all that often though, in particular not for maintenance releases where we strongly enforce selective and well-reviewed backporting, to begin with. And in very rare cases, we have to intentionally break strict backward compatibility even within a maintenance line, e.g. in case of tightened rules for vulnerabilities or to fix accidents or recent regressions.

All in all, our versioning is pragmatically semantic with a focus on developer impact. Near-100% backward compatibility is a key goal, mostly covered by backport reviews and integration testing.

We have semantic commit messages prefixed with "fix", "refactor", "test", "ci", "feat", etc. If we’re about to release a patch version, we cannot include a feature (feat) PR. Based on these semantic commit messages we can automatically generate the changelog.

Additionally, to make sure we’re not introducing breaking changes we have two (maybe more that I’m not aware of), processes:

We’ve reached a state in which we can detect (almost?) any breaking change in Angular thanks to the tens of hundreds of projects internally and the hundreds of thousands of tests.

In general, I agree semantic versioning is not ideal. I don’t see a way it could be completely automated. Programming languages are too complicated to verify statically, as part of the build process, which should be the next version a certain project should be released under.

The Okta Spring Boot Starter has VERY few public classes to avoid this exact problem. It mostly proves implementations of existing Spring Security interfaces.

The Okta Java SDK is a different story. I heavily rely on the japicmp Maven plugin.

If automated, what tools do you use to validate a patch or minor release doesn’t break anything?

I don’t think I’d be able to follow semver without it. We run the cmp goal during CI and releases which will fail if there is a breaking change (or if a minor version needs to be bumped instead of a patch). Updating the actual version is still a manual process (I use the Maven versions plugin mvn versions:set -DnewVersion={new-version-here}).

Semver and Java don’t 100% line up, the OSGi alliance has a nice guide. Java has a notion of "source" and "binary" compatibility. Japicmp can handle both, but it’s really only binary compatibility that matters.

Adding new "default" methods to a Java interface is technically a breaking change too, japicmp allows for post-processing of the results, so you can allow these changes depending on your use cases.

If manual, how do you guarantee you aren’t breaking backward compatibility?

The Okta Spring Boot Starter public methods (I think there are three total) are easy to manage right now because of the small team size and the public API size. That said it’s very easy to change an API in what you think is a backward compatible way (this recently happened in the Spring Security 5.2 release). Scanning this project to ensure semver is on the TODO list.

IMO semantic versioning itself doesn’t suck, I mean the idea of having major.minor.patch releases do work when done correctly.

The problem is actually when using non fixed version ranges. For example, the same problem is present in the Golang community as well even though they don’t necessarily use semver, but the module system supports using ranges or GIT branches for versions, which breaks stuff when you accidentally upgrade transitive dependencies. To an extent, this could also happen in Java IMO. I have experienced it but surely not as much as NodeJS. That is also due to the amount of modularization there.

I was doing the releases for ng-jhipster, react-jhipster, and few other libs, and even wrote the release scripts on the NPM files, I never had issues with semver per se. The issue is obviously when a bad actor doesn’t respect the semver versioning and do breaking changes in a minor version or something like that. If the range support is removed in NPM package resolution, most of the issues will be gone

For your question 2 and 3, I don’t see how it is a server-specific problem, it could be applied to any versioning scheme right.

Concerning the automatic Semver, there is just no way to do this for JHipster…​ so we do it manually.

Basically, the release manager "knows" when there is something breaking, and usually, we never break anything outside of major releases. Of course, we can be wrong sometimes!

The only exception would be for a security patch: then it’s good for us to break the user code, if necessary, as they also needs to fix their own code. But that’s very specific because we are a code generator, and I hope we can remove this as much as possible (I’d like to generate less code, and give more responsibilities to the JHipster libraries, typically because they solve this kind of issue).

How do you do semantic versioning for the Okta JS SDKs (Auth SDK, Angular, React, Vue, etc.)? Is it manual or automated?

Manual at the moment, as it provides the most about of flexibility. As you know, semver is opinionated about feature vs. patch/bugfix, so we have to take that into account. The interesting thing about semver is that, because of that constraint, it forces you to break up multiple changes, which I don’t think is a bad thing. There seems to be a lot of FUD around releasing too many versions, but I don’t worry about that. We invented numbers to be used.

If automated, what tools do you use to validate a patch or minor release doesn’t break anything?

We have looked at automation, and if we go down this route it would likely rely on well-formatted commit messages, such as conventional commits (which would have to be human vetted during code review). There is some trickiness around how to enforce those messages though, and where we would want to put those assertions (e.g. a GitHub PR hook?)

If manual, how do you guarantee you aren’t breaking backwards compatibility?

That’s done during code review, IMO you’re always going to need to rely on code review to make sure you aren’t breaking. We’ve caught quite a few just through basic code review. Some languages (Java) do have tools for checking method signatures and other things that are statically obvious as breaking a contract/interface, those tools can give you some early warnings. Perhaps there is something for JavaScript but I haven’t looked.

I think the idea that 0.x version ranges can have breaking changes within the 0.x range is silly. Just roll it over to 1.0 if you need to break. What major version is Angular on now anyways?