README.md in pg_ha_migrations-0.2.0 vs README.md in pg_ha_migrations-1.0.0

@@ -1,9 +1,15 @@
 # PgHaMigrations
 
-PgHaMigrations is a gem that applies learned best practices to ActiveRecord Migrations.
+[![Build Status](https://travis-ci.org/braintree/pg_ha_migrations.svg?branch=master)](https://travis-ci.org/braintree/pg_ha_migrations/)
 
+We've documented our learned best practices for applying schema changes without downtime in the post [PostgreSQL at Scale: Database Schema Changes Without Downtime](https://medium.com/braintree-product-technology/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680) on the [Braintree Product and Technology Blog](https://medium.com/braintree-product-technology). Many of the approaches we take and choices we've made are explained in much greater depth there than in this README.
+
+Internally we apply those best practices to our Rails applications through this gem which updates ActiveRecord migrations to clearly delineate safe and unsafe DDL as well as provide safe alternatives where possible.
+
+Some projects attempt to hide complexity by having code determine the intent and magically do the right series of operations. But we (and by extension this gem) take the approach that it's better to understand exactly what the database is doing so that (particularly long running) operations are not a surprise during your deploy cycle.
+
 Provided functionality:
 - [Migrations](#migrations)
 - [Utilities](#utilities)
 - [Rake Tasks](#rake-tasks)
 
@@ -24,18 +30,34 @@
 
     $ gem install pg_ha_migrations
 
 ## Usage
 
+### Rollback
+
+Because we require that ["Rollback strategies do not involve reverting the database schema to its previous version"](https://medium.com/braintree-product-technology/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680#360a), PgHaMigrations does not support ActiveRecord's automatic migration rollback capability.
+
+Instead we write all of our migrations with only an `def up` method like:
+
+```
+def up
+  safe_add_column :table, :column
+end
+```
+
+and never use `def change`. We believe that this is the only safe approach in production environments. For development environments we iterate by recreating the database from scratch every time we make a change.
+
 ### Migrations
 
 In general, existing migrations are prefixed with `unsafe_` and safer alternatives are provided prefixed with `safe_`. 
 
 Migrations prefixed with `unsafe_` will warn when invoked. The API is designed to be explicit yet remain flexible. There may be situations where invoking the unsafe migration is preferred.
 
 Migrations prefixed with `safe_` prefer concurrent operations where available, set low lock timeouts where appropriate, and decompose operations into multiple safe steps.
 
+[Running multiple DDL statements inside a transaction acquires exclusive locks on all of the modified objects](https://medium.com/braintree-product-technology/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680#cc22). For that reason, this gem [disables DDL transactions](./lib/pg_ha_migrations.rb:8) by default. You can change this by resetting `ActiveRecord::Migration.disable_ddl_transaction` in your application.
+
 The following functionality is currently unsupported:
 
 - Rollbacks
 - Generators
 - schema.rb
@@ -110,10 +132,10 @@
 unsafe_make_column_not_nullable :table, :column
 ```
 
 #### safe\_add\_concurrent\_index
 
-Add an index concurrently. Migrations that contain this statement must also include `disable_ddl_transaction!`.
+Add an index concurrently.
 
 ```ruby
 safe_add_concurrent_index :table, :column
 ```