Semver when adding values to enums

Question

We're introducing semantic versioning (http://semver.org/) to our Java libraries.

How should we handle adding new enum values? The situation we have is the following:

• annotations.jar contains an annotation with has a property of type MyEnum
• util.jar has objects annotated using the annotated from annotations.jar
• wsprovider.jar uses a jaxb like technology to serialise the annotated objects from util.jar into a web api
• wsconsumer.jar consumes the web api provided by wsprovider.jar, and does a switch based on the value of MyEnum to change it's behaviour.

If we add a new value to MyEnum, which parts (major/minor/patch) of the various jars should we bump?

It seems to me like util.jar needs to bump the major version, because the API changed in a way that can break existing code.

By the same logic this would ripple through to a major bump in wsprovider.jar and wsconsumer.jar.

Does annotations.jar need a major version bump?

I would say yes because enums are a closed set of values, so code (such as wsconsumer.jar) make an assumption that by covering all values in the enum it covers all possible behaviours. Adding a new value to the enum then breaks that.

However, instinctually it all seems a bit much for the addition of a single value to an enum, and has quite a knock-on effect.

I guess this is just something we need to get used to with semver?

Answer 1

Adding new functionality like adding a new enum constant, in your case, rarely breaks backward compatibility of the public API. I believe the most harm it might cause to the public API is making some other enum constant deprecated, which will only result in a minor version bump as specified in the SemVer (FAQ: How should I handle deprecating functionality?). So you might want to reconsider if adding the new enum constant really does break the existing code, because I don't see how it could.

Regarding your dependencies, there's another FAQ question which might be of interest to you: What should I do if I update my own dependencies without changing the public API?.

One thing to remember is that incrementing the major version is mostly about breaking the backward compatibility of the public API, which usually is followed by changing the existing code as opposed to adding a new piece of code. The other thing to remember is that every dependency has its own public API.