Versioning policy

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.

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
 

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
 

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
 

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:
 

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
 

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
 

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
 

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",

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: