Versioning policy

[mattheworiordan]

Given we have no formal policy on how we version, I thought we should get something down based on what we do practically now.

This is not meant to be a discussion about what we should do. That's for another day. This PR is about providing some guidance on what we do now.

@QuintinWillison notice the 1.0 to 1.1 update commit. You may need to do the same for the 1.2 release.

[mattheworiordan]

@tomczoink mind looking at why this deployment failed?

[SimonWoolf]

We (aim to) follow semver for public-facing APIs (which includes the REST api), but we don't really for the realtime protocol. E.g. connectionTimeserials will be a breaking protocol change, but we're doing that change in 1.3 rather than 2.0 because there's no change to the customer-facing client lib API. The policy we're effectively currently following for the realtime protocol is that breaking changes require a new spec version, which can be either a major or minor version.

[SimonWoolf]

TBH I'm not sure I'm 100% convinced - the main api version is essentially 100% driven by client library protocol requirements, so this policy leaves other transports wanting to make changes that don't affect client libs in the position of just waiting until the next new client lib spec version happens, which might be a month or > a year away. (And technically per semver if it's a breaking change, waiting until the next new major client lib spec version happens, which is once in a blue moon).

But I don't feel particularly strongly about it, and if you (Matt) and Paddy both think this is the right policy, I'm happy to accept the consensus.

[mattheworiordan]

I agree it's not ideal, but equally maintaining different versions across different protocols, SDKs, endpoints feels like a far bigger issue. If we had to introduce a breaking change that only affected SSE for example, and we bumped from 1.3 to 1.4 but communicate it in the changelogs, it would be less than ideal, but possible. Equally, I think we can deal with that issue if it ever arises.

[QuintinWillison]

@paddybyers if you're happy then I think we get this merged.

[mattheworiordan]

@paddybyers@SimonWoolf@QuintinWillison updated with a small change. You OK to proceed?

[QuintinWillison]

Did you mean to modify this file as it's in a versions folder?

[mattheworiordan]

Good spot, no.

[paddybyers]

LGTM, after some clarifications and minor edits (11013bb)

[MarkWoulfeAbly]

@mattheworiordan if this is still something we want to merge can you please address the conflicts and also update the base version from 1.1 1.2 now we have that released?

[QuintinWillison]

@mattheworiordan are you able to work on this or do you need somebody else to take over?

Also, @paddybyers and @SimonWoolf, I'm here today because I've been briefly diverted to looking at (potentially rogue) 1.x version numbers in client libraries. Most of our libraries released as 1.2.x still have 1.x version numbers for (what I believe) are protocol version numbers:

• java: ABLY_VERSION_NUMBER = 1.0f
• cocoa: ARTDefault_version = @"1.1"
• js: apiVersion = '1.1'

And then there's the exception (!?) as recently updated by @marto83:

• dotnet: ProtocolVersionNumber = 1.2F

This feels like it needs refinement for clarity (and I've not even looked at the other libraries). In fact, in the case of Java, I think this line is a bug (i.e. idempotent publishing cannot possibly be enabled!). I've created ably/ably-java#590 to track that.

All I can find in the client library features specification is G4 which refers to "API Version" which, clearly, seems to be about public facing programmable APIs - as distinct from information announced to the server at wire level.

I'm not sure that the Realtime Protocol Definition page makes things any clearer either.

What should I be looking at to ascertain what each library should be using? (that is assuming these values are even sent by each library as I've not yet dug deep enough to look at that yet)

[SimonWoolf]

@QuintinWillison You've correctly identified G4 as the relevant spec item. When it says "A client library must identify to Ably the version..." that is talking about the v= or x-ably-version param that's set by eg Defaults.apiVersion in ably-js. (RTN2f also mentions that "API version param v should be the API version per G4").

So, yeah, all those libraries should have been updated to change that api version with the release of 1.2, and Martin was the only person who remembered :/. (Not your fault obviously, mine as I should have caught it in the 1.2 release PR review)

(Luckily doesn't matter that much, since I don't think there are any non-backwards-compatible wire protocol changes in 1.2. For 1.3 it'll matter a lot more, since the api version will trigger the server to use connectionTimeserials)

[QuintinWillison]

@MarkWoulfeAbly I'm going to get this ready to land, FYI.

[kavalerov]

Quick notes from a call between me, @niksilver , @paddybyers and @QuintinWillison

• We agreed that we need to land this PR now - @tbedford should take over (great task for day 1 😅), and with our help land it.
• We will have another conversation with key stakeholders and in more appropriate forum regarding versioning policy moving forward. Discussion is referenced here: https://ably.atlassian.net/l/c/Z6g9KCN1
• Not directly related to this PR, but we are going to update Flutter plugin version to 1.2.* - @QuintinWillison will create a PR in https://github.com/ably/ably-flutter

[kavalerov]

@jamienewcomb for some reason this issue was not synced to Jira - can you please take a look?

[jamienewcomb]

We don’t sync PRs :)

[tbedford]

I've reviewed locally and looks good, but I'd like to review the deployed review app: it's showing as "1 inactive (outdated) deployment". Is there a way to "reboot" the review app so I can see the latest changes? Unfortunately local review is not enough because I want to check menus are OK.

[tbedford]

Reviewed locally and here: https://ably-docs-versioning-ca8dyfe7y.herokuapp.com/client-lib-development-guide/versioning/ LGTM