[cmake-developers] cmake-server protocol versioning

[Tobias Hunger]

Hi Justin,

On Thu, Sep 14, 2017 at 6:52 PM, Justin Goshi via cmake-developers
<cmake-developers at cmake.org> wrote:
> I work at Microsoft on the version of CMake shipping with Visual Studio, and
> we use the cmake-server to talk to CMake.

Cool!

> At some point between cmake version 3.9.0 and 3.9.1 the cmake-server
> protocol changed. Looking through the source code, I see that
> cmServerProtocol1::ProtocolVersion now returns 1,1 when it used to return
> 1,0. Has there been discussion about backwards compatibility? In particular
> we were thinking something along these lines would be nice.

Please ask the server for version 1, not 1.0 (leave the minor part
unspecified). That way server-mode will always return the latest minor
version that is available.

> Every change to the information returned from CMake increments the protocol
> number

It does. As new functionality gets added, the version number
increases, as you noted.

> CMake –server supports all protocol numbers by letting you specify which one
> you are requesting. Extra data that is ignored is okay with older protocols,
> but it can’t change the expected data.

That is what minor increments do: They add extra stuff that older
clients should simply ignore. This means new fields might get added to
the JSON output, or new commands may become available. Nothing that
should throw a client off balance:-) Minor version bumps are mostly
there to make clients aware that new features are available.

Major version bumps break compatibility with clients that expect
earlier major versions. We will keep the old version of the protocol
supported when that happens -- as far as that is possible.

> CMake –server has tests to verify it supports older protocol numbers.

Tests are available for a lot of the things that server-mode does.
They did not detect a regression compared to protocol 1.0 when we
changed to 1.1.

I would welcome if you could find the time to help improve our test
coverage with use-cases critical to you.

> What are your thoughts?

I basically agree with what you said. But please be aware that
server-mode is still experimental, so we do currently have a bit of
slack as we figure out things.

We should discuss removing the experimental tag though.

Best Regards,
Tobias