Add UPGRADING.md

Author: binarylogic

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [3.0.0] - 2019-03-28
+
 ### Changed
 
   - Timber's Rails integration has been moved to the optional `timber_rails` gem: https://github.com/timberio/timber-ruby-rails
@@ -134,7 +136,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
     instead of applying back pressure.
 
 
-[Unreleased]: https://github.com/timberio/timber-ruby/compare/v2.6.1...HEAD
+[Unreleased]: https://github.com/timberio/timber-ruby/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/timberio/timber-ruby/compare/v2.6.1...v3.0.0
 [2.6.1]: https://github.com/timberio/timber-ruby/compare/v2.6.0...v2.6.1
 [2.6.0]: https://github.com/timberio/timber-ruby/compare/v2.5.1...v2.6.0
 [2.5.1]: https://github.com/timberio/timber-ruby/compare/v2.5.0...v2.5.1

UPGRADING.md

@@ -0,0 +1,48 @@
+# Upgrading
+
+## 2.x to 3.x
+
+### Overview
+
+We're excited to announce the 3.X line of Timber for Ruby! We've been making big
+strides with Timber as a whole and 3.X represents a lot of big improvements:
+
+- A lighter code base
+- Better performance
+- A simpler, better install process and strategy
+- New docs: https://docs.timber.io/setup/languages/ruby
+- New integration libraries focused on the specific library they're integrating with
+
+  - https://github.com/timberio/timber-ruby-rack
+  - https://github.com/timberio/timber-ruby-rails
+
+Outside of that, 3.0 does not introduce any API changes, and is forward compatbile
+in that regard. This means actions like setting context and logging structured data
+will continue to work as expected.
+
+### Rails
+
+If you're on Rails, the upgrade process is simple. Simply add the `timber-rails`
+gem to your `Gemfile`:
+
+```
+gem 'timber-rails', '~> 1.0'
+```
+
+That's it! Everything is taken care of you via a Rails initializer.
+
+More info: https://docs.timber.io/setup/languages/ruby/integrations/rack
+
+### Non-rails
+
+If you're not on rails, and you're using `Rack`, you'll want to install the
+`timber-rack` gem by adding it to your `Gemfile`:
+
+```
+gem 'timber-rack', '~> 1.0'
+```
+
+That's it! The middleware class names are still the same and should not
+require any altering.
+
+More info: https://docs.timber.io/setup/languages/ruby/integrations/rack