What does the version number mean?

[agluszak]

Currently the architecture of this repository resembles a monorepo, as it consists of many independent components:

• the BSP spec itself
• bsp4j library
• bsp4s library
• website generator

In January we "released" version v2.1.0-M4.
But that was a release of what? The protocol itself didn't change. Some dependencies were bumped. The biggest change was the new website generator.

I propose that we disentangle versioning/releasing schemes of each component.

I guess that it initially made sense to keep the protocol and the support library versions in lockstep. But now it's starting to become a burden - introducing a minor change to one of libraries shouldn't necessitate bumping the version of the protocol itself. And vice versa - rephrasing a sentence in the spec doesn't necessarily make the libraries incompatible with the new version of the protocol. This problem is going to grow bigger and bigger as more support libraries are added.

Changes to the website generator shouldn't affect the version number at all.

[lefou]

Version 2.1.0-M4 changed the protocol a bit, as it added some classes fields to the JvmEnvironmentItem, IIRC.

+1 for separating the version number from the support libraries. Also, I'd like to see separate changelogs for protocol and libraries.

If versions get split, it would be nice if the support libraries get some API which exposes the supported BSP protocol version.

[adpi2]

Changes to the website generator shouldn't affect the version number at all.

That I agree.

But for splitting the spec and the libraries I am not quite sure it is good idea:

• we don't want the libraries and the spec to diverge: when we change something in the spec, we want to see that change in the lib
• it is rare to change something in a lib without changing the spec: the libs are more or less just the code generated from the spec.
• having the same version is convenient for the user
• having three separate things to release is more cumbersome

[ckipp01]

I think traditionally this was also done because its... easier to maintain.

But now it's starting to become a burden

Could you expand a bit on what the burden is?

I also sort of agree with @adpi2 that every time the actual spec changes there needs to be those changes reflected as well in the implementations, so I'm not convinced that we gain a lot by doing this. The only benefit I can see would be having bug fixes in the implementations wouldn't bump that spec when it's not needed. That might be nice, but again, if there isn't an actual burden I'm not sure it's worth it.

[lefou]

From a technical POV, there is no reserved version range for the implementations to evolve. That means, implementations can not be improved and released without changing the protocol version. Even "just" bumping their dependencies without bumping the protocol version is currently not supported.

[jastice]

Isn't it sufficient to just bump the "fix" part of versions if we want to change something in the implementation?
Of course you could argue that there are changes in implementations that don't change anything in the spec, but are incompatible in terms of language API. Question is if this case is important enough to bother with separating spec and implementation versions.

[agluszak]

we don't want the libraries and the spec to diverge: when we change something in the spec, we want to see that change in the lib

But that's only a matter of time until there emerges a library which doesn't live in this repo and we don't control its versioning scheme

it is rare to change something in a lib without changing the spec: the libs are more or less just the code generated from the spec.

That's not true. There have been bugs in bsp4j which can be fixed without touching the spec. Also, the smithy migration will probably start a period of changes to the libraries. Also: libraries have dependencies and we want to bump them from time to time.

having the same version is convenient for the user

How? On the contrary, in the Rust ecosystem all libraries are required to follow semver. There are libraries that act as "plugins" for other libraries (it's a similar relationship to the one between the BSP spec and its support libraries). Plugin authors simply publish a compatibility table: https://github.com/harudagondi/bevy_fundsp/#compatibility

Also, that's the case in the LSP ecosystem: https://github.com/gluon-lang/lsp-types. Even lsp4j versioning scheme isn't tied to LSP version numbers: https://github.com/eclipse-lsp4j/lsp4j#supported-lsp-versions

Could you expand a bit on what the burden is?

For example, we want to replace the "old" testkit with the "new" one. That's a breaking change from the point of view from the testkit users POV, but an insignificant implementation detail from the point of view of every other component. What should we do with the version number?

Of course you could argue that there are changes in implementations that don't change anything in the spec, but are incompatible in terms of language API. Question is if this case is important enough to bother with separating spec and implementation versions.

IMO, yes.