Versioning strategy in Dropwizard module projects

[Michael Zamani]

Hey folks,

Now that we've got all but one of our modules open sourced, one thing I'd like to get some feedback on is the versioning strategy. 

I see most of the io.dropwizard.module projects version by using the version of Dropwizard that they rely on, and appending and incrementing counter to that number (i.e., 1.3.12-1). 

Because there's not a great way to differentiate versions with breaking changes,  new features, or just bug fixes with this versioning, I'm curious if there would be any opposition to us following semantic versioning for our modules instead.

The main drawbacks with switching to this are:

1. We'd lose consistency with all of the other Dropwizard module projects, unless they also changed their versioning strategy.

2. We'd likely want to maintain a version compatibility matrix in each module's README.

Any opposition to doing this? Or alternate suggestions?

Thanks!

[Jochen Schalanda]

Hi Michael,

> The main drawbacks with switching to this are:
> 1. We'd lose consistency with all of the other Dropwizard module projects, unless they also changed their versioning strategy.
> 2. We'd likely want to maintain a version compatibility matrix in each module's README.

The idea with the current versioning strategy for (official) Dropwizard modules was to make it very easy for users to see, which version of Dropwizard they were targeting.

This of course comes at the cost of not being able to use semantic versioning with the modules themselves, but we thought it might be worth it, especially since we wanted to maintain modules for more than one major/minor version of Dropwizard.

The Spring ecosystem is doing it a little differently and is using semantic versioning (more or less) for all sub-projects on their own. This leads, in my humble opinion, to some confusion which versions of Spring Security and Spring Cloud work well with a specific version of Spring Boot. YMMV. ;-)


Cheers,
Jochen

[Michael Zamani]

Hey Jochen,

Thanks for the info. I get wanting to make it easy to determine which module versions are compatible with which versions of Dropwizard, but maybe there's a middle ground between the two approaches?

I don't really see a ton of value being added by matching all the way down to the patch version. Maybe instead, the module versions match the major and minor version of Dropwizard they're compatible with, and then beyond that we offer some sort of semantic versioning info for the rest of the version number.

For example, and maybe this is too complicated without additional docs, but something like: <DW Major Version>.<DW Minor Version>.<Module Major Version>.<Module Minor Version>.<Module Patch Version> or 1.3.1.2.5. 

Otherwise, yeah there are some downsides with the Spring approach you mention, but in theory, if a compatibility matrix were added to the README and updated alongside the module/Dropwizard versions, would that address those concerns sufficiently? 

[Peter Stackle]

I'll add my 2 cents.

> The idea with the current versioning strategy for (official) Dropwizard modules was to make it very easy for users to see, which version of Dropwizard they were targeting.

While I get the idea, there is also the case where by having the versions try to match so tightly to the major.minor.patch version of the main Dropwizard project, as soon as Dropwizard releases a new version, all of the non-main modules now look out of sync unless they release each time just to bump version numbers. 

> For example, and maybe this is too complicated without additional docs, but something like: <DW Major Version>.<DW Minor Version>.<Module Major Version>.<Module Minor Version>.<Module Patch Version> or 1.3.1.2.5. 

I'm also not a big fan of this idea for a couple reasons. One, since there shouldn't be breaking API changes in a minor version bump, then module version shouldn't need to specify Dropwizard's minor version. Two, for the most part, the APIs that bundles or modules typically use have been fairly stable for a while, so I can see the case where a module could be at 1.0.0 and support Dropwizard 0.9.x, 1.x.x, and 2.x.x. When a new major version of Dropwizard releases, should all modules be forced to bump major version numbers just to stay in sync? 

>  if a compatibility matrix were added to the README and updated alongside the module/Dropwizard versions

I like this suggestion the best. If each module maintains a compatibility matrix with which version of the module is compatible with which versions of Dropwizard, then it can be easy to see which version should be used. Additionally, it allows for the case that when a new version of Dropwizard is released, all that would be needed is to verify functionality of the module on the new version and to update the matrix by adding the new Dropwizard version supported. The dropwizard-swagger module is close to what I'm thinking (https://github.com/smoketurner/dropwizard-swagger#version-matrix). I think this can be improved on by updating the module builds to take advantage of Travis CI's support for matrix builds and to have the module actually build and test against each of the latest major (or major.minor) versions of Dropwizard.