diff --git a/content/client-lib-development-guide/versioning.textile b/content/client-lib-development-guide/versioning.textile new file mode 100644 index 0000000000..8d0582e0e4 --- /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, our "REST API endpoints":/rest-api, and all other public endpoints that support versioning such as "Server-Sent Events":/sse. + +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 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. diff --git a/content/realtime/usage.textile b/content/realtime/usage.textile index fb6614a2af..c33f2aa3f7 100644 --- a/content/realtime/usage.textile +++ b/content/realtime/usage.textile @@ -54,7 +54,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 diff --git a/content/realtime/versions/v0.8/usage.textile b/content/realtime/versions/v0.8/usage.textile index d3e6a691e0..d070130695 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 88248dbe27..caee325ce4 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-api/index.textile b/content/rest-api/index.textile index 7bd7d72b76..799afe7f90 100644 --- a/content/rest-api/index.textile +++ b/content/rest-api/index.textile @@ -143,7 +143,7 @@ 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: diff --git a/content/rest/usage.textile b/content/rest/usage.textile index 06708de1a5..9703041ab9 100644 --- a/content/rest/usage.textile +++ b/content/rest/usage.textile @@ -51,7 +51,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 diff --git a/content/rest/versions/v0.8/usage.textile b/content/rest/versions/v0.8/usage.textile index 21d157a6ad..032abaa9da 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 c80421e589..f8e9aee43d 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 diff --git a/content/tutorials/reactor-event-google.textile b/content/tutorials/reactor-event-google.textile index bac7c3d47d..ac65011dd5 100644 --- a/content/tutorials/reactor-event-google.textile +++ b/content/tutorials/reactor-event-google.textile @@ -87,7 +87,7 @@ 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.2", diff --git a/content/tutorials/webhook-chuck-norris.textile b/content/tutorials/webhook-chuck-norris.textile index 4685849ba5..b01e672837 100644 --- a/content/tutorials/webhook-chuck-norris.textile +++ b/content/tutorials/webhook-chuck-norris.textile @@ -125,7 +125,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: