From 602f5b8a7470adcccb20e20d994da8a32069cf10 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Tue, 24 Mar 2020 19:44:01 +0000 Subject: [PATCH 1/5] Describe versioning policy --- .../versioning.textile | 17 +++++++++++++++++ content/realtime/versions/v0.8/usage.textile | 2 +- content/realtime/versions/v1.0/usage.textile | 2 +- content/rest/versions/v0.8/usage.textile | 2 +- content/rest/versions/v1.0/usage.textile | 2 +- 5 files changed, 21 insertions(+), 4 deletions(-) create mode 100644 content/client-lib-development-guide/versioning.textile diff --git a/content/client-lib-development-guide/versioning.textile b/content/client-lib-development-guide/versioning.textile new file mode 100644 index 0000000000..f8fd386800 --- /dev/null +++ b/content/client-lib-development-guide/versioning.textile @@ -0,0 +1,17 @@ +--- +title: Ably Versioning +section: client-lib-development-guide +index: 19 +--- + +Ably aims to follow the "semantic versioning scheme":http://semver.org/ for our "client library SDKs":https://www.ably.io/download, the "realtime protocol used by these SDKs":/client-lib-development-guide/protocol, our "REST API endpoints":/rest-api, and all other public endpoints, that support versioning, such as "Server-Sent Events":/sse. + +Whilst we recognise this approach has some limitations, primarily around the need to synchronize version updates across all of the above when a breaking change is introduced, we believe that having an independent series of version numbers for different protocols, endpoints and SDKs, would make managing that incredibly difficult for Ably, and most importantly, for our customers. This documentation itself operates on the basis that customer facing content shares a single version number so that customers can view the latest, or, for example, switch to 1.1 across the entire site (where content has been versioned). + +Further, given that the version numbers we use cover the raw HTTP API, the protocol and API spec, and the client library SDKs, features such as support for connection/request params, channel params, extras, token lengths, APIs (eg push HTTP API) vary by the API version. Stateless connections are subject to some of those constraints, even if they don't follow the full protocol spec or the library API. + +As such, in the case of SSE for example, we feel standardising on versioning means it's quite natural for a connection string for a stateless connection to include the spec version, and that will allow the system to know what features the client can be expected to understand, and might be required so that the system knows how to interpret param values that are supplied by the client. Whilst we always try to make it so that there are no incompatibilities, we have a version because we recognise that that's not always avoidable. + + + + diff --git a/content/realtime/versions/v0.8/usage.textile b/content/realtime/versions/v0.8/usage.textile index 8db5d046f3..92e5e484dd 100644 --- a/content/realtime/versions/v0.8/usage.textile +++ b/content/realtime/versions/v0.8/usage.textile @@ -48,7 +48,7 @@ blang[javascript]. var realtime = new Ably.Realtime({ key: apiKey }); ``` - When including the client library from our CDN, we recommend you lock into major version @0@ of the library. According to the "semantic versioning scheme":http://semver.org/ we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @0@ of the library by including "@https://cdn.ably.io/lib/ably.min-0.js@":https://cdn.ably.io/lib/ably.min-0.js, you will receive all minor updates and patch fixes automatically (i.e @0.*.*@). If you want to lock into minor version @0.8@ and receive all patch fixes automatically (i.e. @0.8.*@), then use "@https://cdn.ably.io/lib/ably.min-0.8.js@":https://cdn.ably.io/lib/ably.min-0.8.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. + When including the client library from our CDN, we recommend you lock into major version @0@ of the library. According to the "semantic versioning scheme we adopt":/client-lib-development-guide/versioning, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @0@ of the library by including "@https://cdn.ably.io/lib/ably.min-0.js@":https://cdn.ably.io/lib/ably.min-0.js, you will receive all minor updates and patch fixes automatically (i.e @0.*.*@). If you want to lock into minor version @0.8@ and receive all patch fixes automatically (i.e. @0.8.*@), then use "@https://cdn.ably.io/lib/ably.min-0.8.js@":https://cdn.ably.io/lib/ably.min-0.8.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. "View a complete list of the Javascript library releases":https://github.com/ably/ably-js/releases diff --git a/content/realtime/versions/v1.0/usage.textile b/content/realtime/versions/v1.0/usage.textile index 336bfc33b2..c7e56de859 100644 --- a/content/realtime/versions/v1.0/usage.textile +++ b/content/realtime/versions/v1.0/usage.textile @@ -53,7 +53,7 @@ blang[javascript]. var realtime = new Ably.Realtime({ key: apiKey }); ``` - When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme":http://semver.org/ we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.0@ and receive all patch fixes automatically (i.e. @1.0.*@), then use "@https://cdn.ably.io/lib/ably.min-1.0.js@":https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. + When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme we adopt":/client-lib-development-guide/versioning, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.0@ and receive all patch fixes automatically (i.e. @1.0.*@), then use "@https://cdn.ably.io/lib/ably.min-1.0.js@":https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. "View a complete list of the Javascript library releases":https://github.com/ably/ably-js/releases diff --git a/content/rest/versions/v0.8/usage.textile b/content/rest/versions/v0.8/usage.textile index fa8b6b3214..0cd2d03c6f 100644 --- a/content/rest/versions/v0.8/usage.textile +++ b/content/rest/versions/v0.8/usage.textile @@ -36,7 +36,7 @@ blang[javascript]. var rest = new Ably.Rest({ key: apiKey }); ``` - When including the client library from our CDN, we recommend you lock into major version @0@ of the library. According to the "semantic versioning scheme":http://semver.org/ we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @0@ of the library by including "@https://cdn.ably.io/lib/ably.min-0.js@":https://cdn.ably.io/lib/ably.min-0.js, you will receive all minor updates and patch fixes automatically (i.e @0.*.*@). If you want to lock into minor version @0.8@ and receive all patch fixes automatically (i.e. @0.8.*@), then use "@https://cdn.ably.io/lib/ably.min-0.8.js@":https://cdn.ably.io/lib/ably.min-0.8.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. + When including the client library from our CDN, we recommend you lock into major version @0@ of the library. According to the "semantic versioning scheme we adopt":/client-lib-development-guide/versioning, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @0@ of the library by including "@https://cdn.ably.io/lib/ably.min-0.js@":https://cdn.ably.io/lib/ably.min-0.js, you will receive all minor updates and patch fixes automatically (i.e @0.*.*@). If you want to lock into minor version @0.8@ and receive all patch fixes automatically (i.e. @0.8.*@), then use "@https://cdn.ably.io/lib/ably.min-0.8.js@":https://cdn.ably.io/lib/ably.min-0.8.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. "View a complete list of the Javascript library releases":https://github.com/ably/ably-js/releases diff --git a/content/rest/versions/v1.0/usage.textile b/content/rest/versions/v1.0/usage.textile index 75c67a2edf..0fc132b556 100644 --- a/content/rest/versions/v1.0/usage.textile +++ b/content/rest/versions/v1.0/usage.textile @@ -49,7 +49,7 @@ blang[javascript]. var rest = new Ably.Rest({ key: apiKey }); ``` - When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme":http://semver.org/ we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.0@ and receive all patch fixes automatically (i.e. @1.0.*@), then use "@https://cdn.ably.io/lib/ably.min-1.0.js@":https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. + When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme we adopt":/client-lib-development-guide/versioning, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.0@ and receive all patch fixes automatically (i.e. @1.0.*@), then use "@https://cdn.ably.io/lib/ably.min-1.0.js@":https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. "View a complete list of the Javascript library releases":https://github.com/ably/ably-js/releases From 255fc0f101d96b57fd66b441ff2ce9b7a5e757f1 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Tue, 24 Mar 2020 19:44:45 +0000 Subject: [PATCH 2/5] Update references to 1.1 from 1.0 This could be a helper, however some of these references refer to specific library versions. Something to revisit in due course. --- content/realtime/usage.textile | 6 +++--- content/rest-api/index.textile | 6 +++--- content/rest-api/versions/v1.0/index.textile | 6 +++--- content/rest/usage.textile | 6 +++--- content/root/quick-start-guide.textile | 8 ++++---- content/tutorials/history.textile | 4 ++-- content/tutorials/publish-subscribe.textile | 4 ++-- content/tutorials/queue-amqp-neutrino-profanity.textile | 6 +++--- content/tutorials/queue-amqp-wolfram-alpha.textile | 6 +++--- content/tutorials/queue-stomp-neutrino-profanity.textile | 6 +++--- content/tutorials/reactor-event-azure.textile | 2 +- content/tutorials/reactor-event-google.textile | 4 ++-- content/tutorials/token-authentication.textile | 4 ++-- content/tutorials/webhook-chuck-norris.textile | 2 +- docs.gemspec | 2 +- 15 files changed, 36 insertions(+), 36 deletions(-) diff --git a/content/realtime/usage.textile b/content/realtime/usage.textile index 2c61850c7e..80be091cc1 100644 --- a/content/realtime/usage.textile +++ b/content/realtime/usage.textile @@ -53,7 +53,7 @@ blang[javascript]. var realtime = new Ably.Realtime({ key: apiKey }); ``` - When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme":http://semver.org/ we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.0@ and receive all patch fixes automatically (i.e. @1.0.*@), then use "@https://cdn.ably.io/lib/ably.min-1.0.js@":https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. + When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme we adopt":/client-lib-development-guide/versioning, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.1@ and receive all patch fixes automatically (i.e. @1.1.*@), then use "@https://cdn.ably.io/lib/ably.min-1.1.js@":https://cdn.ably.io/lib/ably.min-1.1.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. "View a complete list of the Javascript library releases":https://github.com/ably/ably-js/releases @@ -100,13 +100,13 @@ blang[java]. For Java applications: ```[java] - compile 'io.ably:ably-java:1.0.0' + compile 'io.ably:ably-java:1.1.0' ``` For Android apps: ```[java] - compile 'io.ably:ably-android:1.0.0' + compile 'io.ably:ably-android:1.1.0' ``` In the above example a specific version of the library is referenced, however we recommend you check which is the latest stable version and always use that. Follow links to get the latest stable release for "Java":https://bintray.com/ably-io/ably/ably-java and "Android":https://bintray.com/ably-io/ably/ably-android. diff --git a/content/rest-api/index.textile b/content/rest-api/index.textile index cedf73e65c..eee2741efd 100644 --- a/content/rest-api/index.textile +++ b/content/rest-api/index.textile @@ -143,18 +143,18 @@ Wherever possible, success response bodies contain links, in "HATEOS":http://en. h3(#versioning). Versioning -By default, all requests receive the latest version of the API, which is currently @1.0@. +By default, all requests receive the latest version of the API, which is currently @1.1@. When we make backwards-incompatible API changes to the API, we release new versions. Therefore, we encourage you to explicitly request the version you are interfacing with in all requests using one of the following mechanisms: 1. Include a @X-Ably-Version@ header. Example: bc[sh]. curl https://rest.ably.io/time \ - -H "X-Ably-Version: 1.0" + -H "X-Ably-Version: 1.1" 2. Include the version query string param @v@. Example: -bc[sh]. curl https://rest.ably.io/time?v=1.0 +bc[sh]. curl https://rest.ably.io/time?v=1.1 h3(#pagination). Pagination diff --git a/content/rest-api/versions/v1.0/index.textile b/content/rest-api/versions/v1.0/index.textile index 9073ad7c8e..f58de89092 100644 --- a/content/rest-api/versions/v1.0/index.textile +++ b/content/rest-api/versions/v1.0/index.textile @@ -141,18 +141,18 @@ Wherever possible, success response bodies contain links, in "HATEOS":http://en. h3(#versioning). Versioning -By default, all requests receive the latest version of the API, which is currently @1.0@. +By default, all requests receive the latest version of the API, which is currently @1.1@. When we make backwards-incompatible API changes to the API, we release new versions. Therefore, we encourage you to explicitly request the version you are interfacing with in all requests using one of the following mechanisms: 1. Include a @X-Ably-Version@ header. Example: bc[sh]. curl https://rest.ably.io/time \ - -H "X-Ably-Version: 1.0" + -H "X-Ably-Version: 1.1" 2. Include the version query string param @v@. Example: -bc[sh]. curl https://rest.ably.io/time?v=1.0 +bc[sh]. curl https://rest.ably.io/time?v=1.1 h3(#pagination). Pagination diff --git a/content/rest/usage.textile b/content/rest/usage.textile index 9278b630e6..cfcfed98fd 100644 --- a/content/rest/usage.textile +++ b/content/rest/usage.textile @@ -50,7 +50,7 @@ blang[javascript]. var rest = new Ably.Rest({ key: apiKey }); ``` - When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme":http://semver.org/ we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.0@ and receive all patch fixes automatically (i.e. @1.0.*@), then use "@https://cdn.ably.io/lib/ably.min-1.0.js@":https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. + When including the client library from our CDN, we recommend you lock into major version @1@ of the library. According to the "semantic versioning scheme we adopt":/client-lib-development-guide/versioning, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version @1@ of the library by including "@https://cdn.ably.io/lib/ably.min-1.js@":https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e @1.*.*@). If you want to lock into minor version @1.1@ and receive all patch fixes automatically (i.e. @1.1.*@), then use "@https://cdn.ably.io/lib/ably.min-1.1.js@":https://cdn.ably.io/lib/ably.min-1.1.js. Additionally, the @.min@ suffix can be dropped if you want the non-minified version for debugging. "View a complete list of the Javascript library releases":https://github.com/ably/ably-js/releases @@ -126,13 +126,13 @@ blang[java]. For Java applications: ```[java] - compile 'io.ably:ably-java:1.0.0' + compile 'io.ably:ably-java:1.1.0' ``` For Android apps: ```[java] - compile 'io.ably:ably-android:1.0.0' + compile 'io.ably:ably-android:1.1.0' ``` In the above example a specific version of the library is referenced, however we recommend you check which is the latest stable version and always use that. Follow links to get the latest stable release for "Java":https://bintray.com/ably-io/ably/ably-java and "Android":https://bintray.com/ably-io/ably/ably-android. diff --git a/content/root/quick-start-guide.textile b/content/root/quick-start-guide.textile index fed7a14a53..83b633c079 100644 --- a/content/root/quick-start-guide.textile +++ b/content/root/quick-start-guide.textile @@ -62,13 +62,13 @@ blang[java]. For Java applications: ```[java] - compile 'io.ably:ably-java:1.0.0' + compile 'io.ably:ably-java:1.1.0' ``` For Android apps: ```[java] - compile 'io.ably:ably-android:1.0.0' + compile 'io.ably:ably-android:1.1.0' ``` In the above example a specific version of the library is referenced, however we recommend you check which is the latest stable version and always use that. Follow links to get the latest stable release for "Java":https://bintray.com/ably-io/ably/ably-java and "Android":https://bintray.com/ably-io/ably/ably-android. @@ -127,7 +127,7 @@ ably.connection.on('connected', function() { bc[java]. ClientOptions options = new ClientOptions("{{API_KEY}}"); AblyRealtime ably = new AblyRealtime(options); -ably.connection.on(ConnectionState.connected, new ConnectionStateListener() +ably.connection.on(ConnectionState.connected, new ConnectionStateListener() @Override public void onConnectionStateChanged(ConnectionStateChange state) { System.out.println("New state is " + change.current.name()); @@ -145,7 +145,7 @@ ably.connection.on(ConnectionState.connected, new ConnectionStateListener() } }); -bc[ruby]. +bc[ruby]. EventMachine.run do ably = Ably::Realtime.new(api_key) end diff --git a/content/tutorials/history.textile b/content/tutorials/history.textile index 45744179b2..336f7434cd 100644 --- a/content/tutorials/history.textile +++ b/content/tutorials/history.textile @@ -74,7 +74,7 @@ blang[java]. } dependencies { - compile 'io.ably:ably-java:1.0.0' + compile 'io.ably:ably-java:1.1.0' } ``` @@ -113,7 +113,7 @@ blang[android]. ... dependencies { ... - compile 'io.ably:ably-android:1.0.0' + compile 'io.ably:ably-android:1.1.0' } ``` diff --git a/content/tutorials/publish-subscribe.textile b/content/tutorials/publish-subscribe.textile index 49a07c0c7b..2b94e8498f 100644 --- a/content/tutorials/publish-subscribe.textile +++ b/content/tutorials/publish-subscribe.textile @@ -58,7 +58,7 @@ blang[java]. } dependencies { - compile 'io.ably:ably-java:1.0.0' + compile 'io.ably:ably-java:1.1.0' } ``` @@ -98,7 +98,7 @@ blang[android]. ... dependencies { ... - compile 'io.ably:ably-android:1.0.0' + compile 'io.ably:ably-android:1.1.0' } ``` diff --git a/content/tutorials/queue-amqp-neutrino-profanity.textile b/content/tutorials/queue-amqp-neutrino-profanity.textile index e87af3d123..c12829c38b 100644 --- a/content/tutorials/queue-amqp-neutrino-profanity.textile +++ b/content/tutorials/queue-amqp-neutrino-profanity.textile @@ -83,7 +83,7 @@ First we'll add the @express@ NPM module and create a @package.json@: "start": "node ./server.js" }, "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "express": "~4.0" } } @@ -246,7 +246,7 @@ We're now ready to start consuming messages from the queue. There are "plenty of ```[json] "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "amqplib": "^0.4", "express": ">=4.14.0" } @@ -351,7 +351,7 @@ Now that you have an API key you can use to communicate with the Neutrino API, y ```[json] "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "amqplib": "^0.4", "express": ">=4.14.0", "request": ">=2.79.0" diff --git a/content/tutorials/queue-amqp-wolfram-alpha.textile b/content/tutorials/queue-amqp-wolfram-alpha.textile index 820871a7a9..f0a34b6dff 100644 --- a/content/tutorials/queue-amqp-wolfram-alpha.textile +++ b/content/tutorials/queue-amqp-wolfram-alpha.textile @@ -83,7 +83,7 @@ First we'll add the @express@ NPM module and create a @package.json@: "start": "node ./server.js" }, "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "express": "~4.0" } } @@ -247,7 +247,7 @@ We're now ready to start consuming messages from the queue. There are "plenty of ```[json] "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "amqplib": "^0.4", "express": ">=4.14.0" } @@ -353,7 +353,7 @@ Now that you have an AppID you can use to communicate with the Wolfram Alpha API ```[json] "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "amqplib": "^0.4", "express": ">=4.14.0", "request": ">=2.79.0" diff --git a/content/tutorials/queue-stomp-neutrino-profanity.textile b/content/tutorials/queue-stomp-neutrino-profanity.textile index f8bcdf92c6..89f56e73dd 100644 --- a/content/tutorials/queue-stomp-neutrino-profanity.textile +++ b/content/tutorials/queue-stomp-neutrino-profanity.textile @@ -83,7 +83,7 @@ First we'll add the @express@ NPM module and create a @package.json@: "start": "node ./server.js" }, "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "express": "~4.0" } } @@ -246,7 +246,7 @@ We're now ready to start consuming messages from the queue. There are "plenty of ```[json] "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "amqplib": "^0.4", "express": ">=4.14.0" } @@ -367,7 +367,7 @@ Now that you have an API key you can use to communicate with the Neutrino API, y ```[json] "dependencies": { - "ably": "~1.0", + "ably": "~1.1", "express": ">=4.14.0", "request": ">=2.79.0", "stompit": "^0.24" diff --git a/content/tutorials/reactor-event-azure.textile b/content/tutorials/reactor-event-azure.textile index f3bc56a98a..65c336293b 100644 --- a/content/tutorials/reactor-event-azure.textile +++ b/content/tutorials/reactor-event-azure.textile @@ -174,7 +174,7 @@ Create a folder on your local machine, then navigate to that folder from your co "version": "1.0.0", "description": "Ably Reactor Function Tutorial", "dependencies": { - "ably": "^1.0.11", + "ably": "^1.1.24", "compromise": "^11.2.1", "fuzzyset": "0.0.4" } diff --git a/content/tutorials/reactor-event-google.textile b/content/tutorials/reactor-event-google.textile index 2f9b636161..dbe20cb84f 100644 --- a/content/tutorials/reactor-event-google.textile +++ b/content/tutorials/reactor-event-google.textile @@ -79,10 +79,10 @@ Create a folder on your local machine, then navigate to that folder from your co ```[json] { "name": "ably-pizza-tutorial", - "version": "1.0.0", + "version": "1.1.0", "description": "Ably Reactor Function Tutorial", "dependencies": { - "ably": "^1.0.11", + "ably": "^1.1.24", "compromise": "^11.2.1", "fuzzyset": "0.0.4" } diff --git a/content/tutorials/token-authentication.textile b/content/tutorials/token-authentication.textile index 0b8c1915f6..7635baf195 100644 --- a/content/tutorials/token-authentication.textile +++ b/content/tutorials/token-authentication.textile @@ -51,7 +51,7 @@ blang[java]. } dependencies { - compile 'io.ably:ably-java:1.0.0' + compile 'io.ably:ably-java:1.1.0' } ``` @@ -633,7 +633,7 @@ blang[android]. ... dependencies { ... - compile 'io.ably:ably-android:1.0.0' + compile 'io.ably:ably-android:1.1.0' } ``` diff --git a/content/tutorials/webhook-chuck-norris.textile b/content/tutorials/webhook-chuck-norris.textile index b6583c9375..0727de7208 100644 --- a/content/tutorials/webhook-chuck-norris.textile +++ b/content/tutorials/webhook-chuck-norris.textile @@ -122,7 +122,7 @@ To start using Ably within your Rails server, you first need to install the Ably Add the following to your "@Gemfile@":https://github.com/ably/tutorials/blob/2197a076f89a0103f85df9393c46192964c5772b/Gemfile ```[ruby] - gem 'ably-rest', '~>1.0' + gem 'ably-rest', '~>1.1' ``` Then run the following command to install the required gems: diff --git a/docs.gemspec b/docs.gemspec index dd1e8bee6f..334202921d 100644 --- a/docs.gemspec +++ b/docs.gemspec @@ -1,6 +1,6 @@ Gem::Specification.new do |spec| spec.name = 'ably-docs' - spec.version = '1.0.0' + spec.version = '1.1.0' spec.authors = ["Matthew O'Riordan"] spec.email = ['support@ably.io'] spec.description = %q{Documentation repository Gem for Ably} From dbc0c0bbf75ebae147b0a039ff9dca1d766ab8e1 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Sat, 28 Mar 2020 18:59:59 +0000 Subject: [PATCH 3/5] Realtime protocol is internal and thus doesn't follow the same strict versioning. --- content/client-lib-development-guide/versioning.textile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/client-lib-development-guide/versioning.textile b/content/client-lib-development-guide/versioning.textile index f8fd386800..7342d64710 100644 --- a/content/client-lib-development-guide/versioning.textile +++ b/content/client-lib-development-guide/versioning.textile @@ -4,7 +4,7 @@ section: client-lib-development-guide index: 19 --- -Ably aims to follow the "semantic versioning scheme":http://semver.org/ for our "client library SDKs":https://www.ably.io/download, the "realtime protocol used by these SDKs":/client-lib-development-guide/protocol, our "REST API endpoints":/rest-api, and all other public endpoints, that support versioning, such as "Server-Sent Events":/sse. +Ably aims to follow the "semantic versioning scheme":http://semver.org/ for our "client library SDKs":https://www.ably.io/download, our "REST API endpoints":/rest-api, and all other public endpoints, that support versioning, such as "Server-Sent Events":/sse. Whilst we recognise this approach has some limitations, primarily around the need to synchronize version updates across all of the above when a breaking change is introduced, we believe that having an independent series of version numbers for different protocols, endpoints and SDKs, would make managing that incredibly difficult for Ably, and most importantly, for our customers. This documentation itself operates on the basis that customer facing content shares a single version number so that customers can view the latest, or, for example, switch to 1.1 across the entire site (where content has been versioned). @@ -12,6 +12,8 @@ Further, given that the version numbers we use cover the raw HTTP API, the proto As such, in the case of SSE for example, we feel standardising on versioning means it's quite natural for a connection string for a stateless connection to include the spec version, and that will allow the system to know what features the client can be expected to understand, and might be required so that the system knows how to interpret param values that are supplied by the client. Whilst we always try to make it so that there are no incompatibilities, we have a version because we recognise that that's not always avoidable. +Please note that the "realtime protocol used by our SDKs":/client-lib-development-guide/protocol is an internal protocol, and thus breaking changes do not necessitate a major version change. A major version bump is preferred for breaking changes to public APIs. + From d815d8c600131ee6ec8f0e14380e67cc2ee7e964 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Sun, 10 May 2020 18:47:54 +0100 Subject: [PATCH 4/5] fixup! Update references to 1.1 from 1.0 --- content/rest-api/versions/v1.0/index.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/rest-api/versions/v1.0/index.textile b/content/rest-api/versions/v1.0/index.textile index f58de89092..9073ad7c8e 100644 --- a/content/rest-api/versions/v1.0/index.textile +++ b/content/rest-api/versions/v1.0/index.textile @@ -141,18 +141,18 @@ Wherever possible, success response bodies contain links, in "HATEOS":http://en. h3(#versioning). Versioning -By default, all requests receive the latest version of the API, which is currently @1.1@. +By default, all requests receive the latest version of the API, which is currently @1.0@. When we make backwards-incompatible API changes to the API, we release new versions. Therefore, we encourage you to explicitly request the version you are interfacing with in all requests using one of the following mechanisms: 1. Include a @X-Ably-Version@ header. Example: bc[sh]. curl https://rest.ably.io/time \ - -H "X-Ably-Version: 1.1" + -H "X-Ably-Version: 1.0" 2. Include the version query string param @v@. Example: -bc[sh]. curl https://rest.ably.io/time?v=1.1 +bc[sh]. curl https://rest.ably.io/time?v=1.0 h3(#pagination). Pagination From 11013bb3c66cd999dfb4bd8b314fc1d3b2c2b00b Mon Sep 17 00:00:00 2001 From: Paddy Byers Date: Mon, 11 May 2020 10:49:32 +0100 Subject: [PATCH 5/5] Versioning: minor clarifications --- .../client-lib-development-guide/versioning.textile | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/content/client-lib-development-guide/versioning.textile b/content/client-lib-development-guide/versioning.textile index 7342d64710..8d0582e0e4 100644 --- a/content/client-lib-development-guide/versioning.textile +++ b/content/client-lib-development-guide/versioning.textile @@ -4,16 +4,14 @@ section: client-lib-development-guide index: 19 --- -Ably aims to follow the "semantic versioning scheme":http://semver.org/ for our "client library SDKs":https://www.ably.io/download, our "REST API endpoints":/rest-api, and all other public endpoints, that support versioning, such as "Server-Sent Events":/sse. +Ably aims to follow the "semantic versioning scheme":http://semver.org/ for our "client library SDKs":https://www.ably.io/download, our "REST API endpoints":/rest-api, and all other public endpoints that support versioning such as "Server-Sent Events":/sse. -Whilst we recognise this approach has some limitations, primarily around the need to synchronize version updates across all of the above when a breaking change is introduced, we believe that having an independent series of version numbers for different protocols, endpoints and SDKs, would make managing that incredibly difficult for Ably, and most importantly, for our customers. This documentation itself operates on the basis that customer facing content shares a single version number so that customers can view the latest, or, for example, switch to 1.1 across the entire site (where content has been versioned). +Our policy is that a @major.minor@ version number applies to the API specification and across all versioned services and protocols. Each library implementing a given version of the API specification adopts the same major and minor versions and has patch version numbering indicating the actual library revision. + +Whilst we recognise this approach has some limitations - primarily around the need to synchronize version updates across multiple libraries and specifications when a breaking change is introduced into any one of them - we believe that having an independent series of version numbers for different protocols, endpoints and SDKs would make managing that very difficult for Ably and, most importantly, would be confusing for our customers. This documentation itself operates on the basis that customer-facing content shares a single version number so that customers can view the latest or, for example, switch to 1.1 across the entire site (for content that has been versioned). Further, given that the version numbers we use cover the raw HTTP API, the protocol and API spec, and the client library SDKs, features such as support for connection/request params, channel params, extras, token lengths, APIs (eg push HTTP API) vary by the API version. Stateless connections are subject to some of those constraints, even if they don't follow the full protocol spec or the library API. -As such, in the case of SSE for example, we feel standardising on versioning means it's quite natural for a connection string for a stateless connection to include the spec version, and that will allow the system to know what features the client can be expected to understand, and might be required so that the system knows how to interpret param values that are supplied by the client. Whilst we always try to make it so that there are no incompatibilities, we have a version because we recognise that that's not always avoidable. +As such, in the case of SSE for example, we believe that standardising on versioning means it is quite natural for a connection string for a stateless connection to include the spec version, and that will allow the system to know what features the client can be expected to understand, and might be required so that the system knows how to interpret param values that are supplied by the client. Whilst we always try to make it so that there are no incompatibilities, we have a version because we recognise that that is not always avoidable. Please note that the "realtime protocol used by our SDKs":/client-lib-development-guide/protocol is an internal protocol, and thus breaking changes do not necessitate a major version change. A major version bump is preferred for breaking changes to public APIs. - - - -