Versioning scheme

[rossabaker]

The versioning scheme is clever, but it's not the semantic versioning seen in most Scala libraries. I'm wondering how it plays with things like eviction notices, Scala Steward labelling, etc. And more importantly, what happens if you ever want to make a breaking change outside http4s and finagle's own cycles?

This is the first satellite repo that ties together two major, independent dependencies. (rho is its own thing, and jdk-http-client integrates something in the JDK). It's a problem we'll be having a lot if we start to split up http4s/http4s. It would be good to have a consistent solution, so I'm interested to see how this scheme plays out in practice.

[jcouyang]

really good question, I'm not not sure this is the best
but this is most reasonable I guess semver can get for lib like this(which depends on combination of two libs)

I know it is kind of tricky but technically this is still semver based on the definition

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

for 0.21.4-20.4.1-0

• version core: 0.21.4
• pre-release: 20.4.1-0

since where pre-release can be arbitrary letters and number

what happens if you ever want to make a breaking change outside http4s

probably won't be problem for this lib though 😹
since it only provide 2 simple api mkClient and mkService
so the breaking change will always introduce from either http4s or finagle

[yaroot]

Hi, do you plan on releasing this for multiple finagle versions? What do you think http4s-finagle-20-4/0.21.4.

Another similar library finch doesn't do this, finagle-http doesn't break that often (and most of the breakage should not affect this library) https://twitter.github.io/finagle/guide/changelog.html

[rossabaker]

Hmm. You're right that it's semver compliant, but it's also perpetually in prerelease.

I didn't realize Finagle versioning is by date. That doesn't matter much, other than that we can't estimate the pace of breaking changes from the version number.

Finch is an interesting comparison, except it's not tying together two libraries.

We have some precedent with argonaut, where we kept up with the latest, and then published modules like http4s-argonaut61 for other argonauts as needed. That's pretty similar to @yaroot's proposal.

I think @jcouyang is correct that most maintenance here will be in response to http4s and finagle changes, though I can also imagine bugfixes, logging tweaks, changes for greater consistency with other backends, optimizations, perhaps websocket support. And then new Scala releases (particularly Dotty) always add a wrinkle.

I'd probably just use traditional semver, independent of the two base libraries. Then you've got room to bump when either dependency changes or you make changes yourself. The semantics of update plugins will be well understood. The obvious downside is that we'd have to document which versions of this lines up with which version of http4s and finagle, whereas the present scheme builds that information in.

[jcouyang]

I think it is finch is alright since it depends on finagle like how http4s depends on cats, there is no need to explicitly tag finagle version there

this lib is tricky since there is strongly rely on http4s api, all http4s version change will directly change the lib

yeah I don't think finagle will break anything here so I'm leaning towards to have

 "org.http4s" %% "http4s-finagle" % "0.21.4-<buildnumber>"

or

 "org.http4s"  %% "http4s-finagle" % "0.21.<buildnumber>"

as a user I'll always write

 "org.http4s" %% "http4s-finagle"  % s"$Http4sVersion+"

anyway, so I don't need to maintain version for each of http4s modules in my sbt

[jcouyang]

And then new Scala releases (particularly Dotty) always add a wrinkle

this code is so simply it already compiles to dotty 😄

also scala version will hide in %% so it is fine

as user i really like keep it consistent with other http4s modules like http4s-<dsl|client|server> should all have the same version so I don't need to check and maintain each one of them

[jcouyang]

Another option is all http4s modules can follow Finagle's version scheme after v1 become stable

it is like having a release train schedule every month, all modules can just either catch it or miss it.
https://martinfowler.com/articles/branching-patterns.html#release-train

I personally like twitter's version very much, it is very consistent for all modules, i.e.
if I bump finagle to 20.4.1, everything else can also bump to same version 20.4.1(twitter-server, twitter-util...)

it minimizes the maintains effort to look up for each lib and solve the version tangling