How to use previousStableVersion in build.sbt?

[Mvpanswer7]

I am confued how to use this useful key in my build.sbt

[dwijnand]

Ping @jatcwang, would you like to work with @Mvpanswer7 on this?

Perhaps we could find a way to modify the README so this is well understood.

[Mvpanswer7]

Thanks for reply, the problem is it seems I cannot just simply use previousStableVersion like this: assemblyJarName in assembly := s"project-${previousStableVersion}.jar" and maybe I should use git checkout to previous tag version?

[dwijnand]

It's probably best, for starters, to be using previousStableVersion in ThisBuild.

But you also have to deal with previousStableVersion not being always defined (which is why it's an option).

[Mvpanswer7]

A lot thanks from a starter~ I do tried previousStableVersion in ThisBuild, too, but sbt returned with error: not found: value previousStableVersion, and I do have a previous tag v0.0.2 ...maybe I should just stick to the default version controll...

[dwijnand]

Make sure you're using a release of sbt-dynver that includes previousStableVersion! 😉

You can use the version published since the merge: 3.0.0+4-1be64920.

[julienrf]

It is not clear to me how we can use previousStableVersion with MiMa. Consider the following history:

master
|
| 2.x
| | 
|/
+ v2.0.0
|
| 1.x
| |
| + v1.0.1
| |
|/
+ v1.0.0
|

If I’m on the 1.x branh, previousStableVersion is set to Some("1.0.0"), which is perfect. However, when I’m on the v2.0.0 tag, it is also set to Some("1.0.0"), which means that the recommended value for mimaPreviousArtifacts doesn’t do what I want:

mimaPreviousArtifacts := previousStableVersion.value.map(organization.value %% name.value % _).toSet

Indeed, when I’m not on the 1.x branch (ie, if I’m on master or on 2.x), I’m working on the next major release and I don’t care if my code is not binary compatible with previous stable release, so I would like the mimaPreviousArtifacts to be empty in that case.

[jatcwang]

I think we can add support for this, but it will require detecting whether two versions has breaking semantics. I think SBT itself has some semantic version detection which we can reuse (it uses it for eviction warnings?) but I can't seem to find it. @dwijnand Do you have any ideas?

[dwijnand]

Sorry, I don't use previousStableVersion so I'm not sure (and short on time).

We have a spec on the behaviour, PreviousVersionSpec, so feel free to experiment with changes and propose them. We'll have to them make a decision on whether the new semantics would be acceptable to existing users of previousStableVersion or not, and debate if it's a fix or a breaking change (my eternal dilemma).

Apropos of "breaking semantics" I don't think sbt-dynver should get into the business of trying to guess if something is breaking or not. sbt's eviction warnings are a great example: they false positive so much they're ignored (someone has proposed the Scala Center fixes that.) It should define a useful value for previousStableVersion from git alone.

[jatcwang]

That's how I feel as well - we really shouldn't be dictating what's breaking and not. There's probably a library out there you can use to parse and compare versions, with your own definition of what's breaking or not.

However, if everyone is doing this in their project, perhaps it'll be helpful to have this process consolidated somewhere. Whether that's within sbt-dynver's scope is up for debate. I am happy to implement this if you're ok with having that here. (In a way I think it makes sense for sbt-dynver to provide this functionality, as it has its own versioning scheme. Some other libraries may not handle some of our version strings)

[dwijnand]

The problem (or at least the one I'm referring to) is that we don't have a shared definition of breaking. For starters, we have both a source API and a binary API. But even without that (assume source API == binary API, like Java) reasonable people will disagree on whether a change is a bug fix or a breaking change.

The funny exaggeration is https://xkcd.com/1172/.

[jatcwang]

I am thinking that we can make it customizable, with some common rules they can apply? So it's always an explicit choice of what they want to use.
Also actual usage seems bit more complex than I originally thought. Imagine the scenario that I want to create a new backward-incompatible 2.x branch, it'll initially be based off the 1.x branch but until we have a 2.0 tag, previousStableVersion will still resolve to v1.0.0, whether we implement breaking-version detection or not.

Basing off @julienrf's example:

master
|
| 2.x   <- lots of  breaking changes, but not ready for 2.0 release yet. But previousStableVersion still resolves to v1.0.0
| | 
|/
+
|
| 1.x
| |
| + v1.0.1
| |
|/
+ v1.0.0
|

Perhaps the right way to solve the problem is to disable MiMa checking in 2.x branch until the first v2.0.0 release is done?

master
|
| 2.x  
| |
| |  <- reenable MiMa checking, from this point on previousStableVersion will do the right thing.
| |  v2.0.0
| |  <- disable MiMa checking + lots of breaking changes
|/
+
|
| 1.x
| |
| + v1.0.1
| |
|/
+ v1.0.0
|

[jatcwang]

Can this be closed @dwijnand?

[dwijnand]

I don't mind closing it, but do you think maybe it would be useful to add your tips to the README where previousStableVersion is discussed?

[jatcwang]

On branching off major version branches? Sure.