README.md in phobos-1.8.2.pre.beta1 vs README.md in phobos-1.8.2.pre.beta2

@@ -19,10 +19,11 @@
 With Phobos by your side, all this becomes smooth sailing.
 
 ## Table of Contents
 
 1. [Installation](#installation)
+  1. [Upgrade Notes](#upgrade-notes)
 1. [Usage](#usage)
   1. [Standalone apps](#usage-standalone-apps)
   1. [Consuming messages from Kafka](#usage-consuming-messages-from-kafka)
   1. [Producing messages to Kafka](#usage-producing-messages-to-kafka)
   1. [As library in another app](#usage-as-library)
@@ -50,10 +51,14 @@
 
 ```sh
 $ gem install phobos
 ```
 
+### <a name="upgrade-notes"></a> Upgrade Notes
+
+Version 1.8.2 introduced a new `persistent_connections` setting for regular producers. This reduces the number of connections used to produce messages and you should consider setting it to true. This does require a manual shutdown call -  please see [Producers with persistent connections](#persistent-connection).
+
 ## <a name="usage"></a> Usage
 
 Phobos can be used in two ways: as a standalone application or to support Kafka features in your existing project - including Rails apps. It provides a CLI tool to run it.
 
 ### <a name="usage-standalone-apps"></a> Standalone apps
@@ -289,11 +294,11 @@
   ])
 ```
 
 There are two flavors of producers: __regular__ producers and __async__ producers.
 
-Regular producers will deliver the messages synchronously and disconnect, it doesn't matter if you use `publish` or `publish_list` after the messages get delivered the producer will disconnect.
+Regular producers will deliver the messages synchronously and disconnect, it doesn't matter if you use `publish` or `publish_list`; by default, after the messages get delivered the producer will disconnect.
 
 Async producers will accept your messages without blocking, use the methods `async_publish` and `async_publish_list` to use async producers.
 
 An example of using handlers to publish messages:
 
@@ -308,11 +313,11 @@
     producer.async_publish(PUBLISH_TO, {key: 'value'}.to_json)
   end
 end
 ```
 
-#### Note about configuring producers
+#### <a name="producer-config"></a> Note about configuring producers
 
 Since the handler life cycle is managed by the Listener, it will make sure the producer is properly closed before it stops. When calling the producer outside a handler remember, you need to shutdown them manually before you close the application. Use the class method `async_producer_shutdown` to safely shutdown the producer.
 
 Without configuring the Kafka client, the producers will create a new one when needed (once per thread). To disconnect from kafka call `kafka_client.close`.
 
@@ -324,9 +329,21 @@
 
 MyProducer
   .producer
   .kafka_client
   .close
+```
+
+### <a name="persistent-connection"></a> Note about producers with persistent connections
+
+By default, regular producers will automatically disconnect after every `publish` call. You can change this behavior (which reduces connection overhead, TLS etc - which increases speed significantly) by setting the `persistent_connections` config in `phobos.yml`. When set, regular producers behave identically to async producers and will also need to be shutdown manually using the `sync_producer_shutdown` method.
+
+Since regular producers with persistent connections have open connections, you need to manually disconnect from Kafka when ending your producers' life cycle:
+
+```ruby
+MyProducer
+  .producer
+  .sync_producer_shutdown
 ```
 
 ### <a name="usage-as-library"></a> Phobos as a library in an existing project
 
 When running as a standalone service, Phobos sets up a `Listener` and `Executor` for you. When you use Phobos as a library in your own project, you need to set these components up yourself.