README.md in platform-api-2.2.0 vs README.md in platform-api-2.3.0.pre.1

@@ -49,11 +49,11 @@
 
 For example, to get information about the `web` formation on the `sushi` app
 you'd invoke `heroku.formation.info('sushi', 'web')` and it would return a
 Ruby object that matches the one given in the [response example](https://devcenter.heroku.com/articles/platform-api-reference#formation-info).
 
-The [API documentation](http://heroku.github.io/platform-api/_index.html) contains a 
+The [API documentation](http://heroku.github.io/platform-api/_index.html) contains a
 description of all available resources and methods.
 
 ### Handling errors
 
 The client uses [Excon](https://github.com/excon/excon) under the hood and
@@ -306,10 +306,47 @@
 
 ```ruby
 client = PlatformAPI.connect('my-api-key', url: 'https://api.example.com')
 ```
 
+### Rate throttling
+
+Rate throttling capability is inclued in PlatformAPI v2.3.0, but is disabled by default. The following section describes the behavior of the PlatformAPI gem v3.0.0+. To enable rate throttling logic, upgrade to the latest released version.
+
+By default client requests from this library will respect Heroku's rate-limiting. The client can make as many requests as possible until Heroku's server says that it has gone over. Once a request has been rate-limited the client will sleep and then retry the request again. This process will repeat until the request is successful.
+
+Once a single request has been rate-limited, the client will auto-tune a sleep value so that future requests are less likely to be rate-limited by the server.
+
+Rate throttle strategies are provided by [the Rate Throttle Client gem](https://github.com/zombocom/rate_throttle_client). By default the `RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease` strategy is used.
+
+To disable this retry-and-sleep behavior you can change the rate throttling strategy to any object that responds to `call` and yields to a block:
+
+```ruby
+PlatformAPI.rate_throttle = ->(&block) { block.call }
+
+# or
+
+PlatformAPI.rate_throttle = RateThrottleClient::Null.new
+```
+
+By default rate throttling will log to STDOUT when the sleep/retry behavior is triggered:
+
+```
+RateThrottleClient: sleep_for=0.8
+```
+
+To add your own custom logging, for example to Librato or Honeycomb, you can configure logging by providing an object that responds to `call` and takes one argument:
+
+```ruby
+PlatformAPI.rate_throttle.log = ->(info) {
+  # Your logic here
+
+  puts info.sleep_for
+  puts info.request
+}
+```
+
 ## Building and releasing
 
 ### Generate a new client
 
 Generate a new client from the Heroku Platform API JSON schema:
@@ -343,11 +380,11 @@
 
 And then visit `doc/index.html` to read it. Alternately, build and publish
 it to Github Pages in one step with:
 
 ```
-rake publish
+rake publish_docs
 ```
 
 You can see it live on [Github Pages](http://heroku.github.io/platform-api/).
 
 ## Contributing
@@ -355,5 +392,25 @@
 1. [Fork the repository](https://github.com/heroku/platform-api/fork).
 2. Create your feature branch: `git checkout -b my-new-feature`
 3. Commit your changes: `git commit -am 'Add some feature'`
 4. Push to the branch: `git push origin my-new-feature`
 5. Create new pull request.
+
+## Testing
+
+The tests make live network calls so you'll need to ensure that you're logged into your Heroku account. You'll also need an application that uses a set of Heroku's features, if you don't have one you can create one. E.g.
+
+```
+$ git clone https://github.com/heroku/ruby-getting-started.git
+$ cd ruby-getting-started/
+$ heroku create <memorable-name-here>
+$ heroku webhooks:add -i api:dyno -l notify -u https://example.com/hooks
+$ git push heroku master
+```
+
+Now you can specify your app name while you run tests:
+
+```
+$ TEST_APP_NAME="<memorable-name-here>" rspec ./spec
+```
+
+If you run tests without specifying a `TEST_APP_NAME` then an app will be created and deployed under your user account.