docs: v2 migration guide

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v2.0.0
+
+No additional changes since v2.0.0-rc.3.
+
 ## v2.0.0-rc.3
 
 ### Breaking Changes

README.md

@@ -9,41 +9,42 @@
 [![Last Updated](https://img.shields.io/github/last-commit/codedge-llc/pigeon.svg)](https://github.com/codedge-llc/pigeon/commits/master)
 [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/pigeon/)
 
-_Pigeon v2.0 is in release candidate status. See [the latest stable 1.6 on Hex](https://hex.pm/packages/pigeon)
-or [the 1.6 branch on GitHub](https://github.com/codedge-llc/pigeon/tree/v1.6) for installation._
-
 ## Installation
 
 Add `:pigeon` and as a `mix.exs` dependency:
 
 ```elixir
 def deps do
   [
-    {:pigeon, "~> 2.0.0-rc.3"}
+    {:pigeon, "~> 2.0"}
   ]
 end
 ```
 
+## Upgrading from v1.6
+
+See the [migration guide](./docs/Migrating to v2-0-0.md) for instructions.
+
 ## Getting Started
 
 Check the module documentation for your push notification service.
 
-- [Pigeon.ADM](https://hexdocs.pm/pigeon/2.0.0-rc.2/Pigeon.ADM.html) - Amazon Android.
-- [Pigeon.APNS](https://hexdocs.pm/pigeon/2.0.0-rc.2/Pigeon.APNS.html) - Apple iOS.
-- [Pigeon.FCM](https://hexdocs.pm/pigeon/2.0.0-rc.2/Pigeon.FCM.html) - Firebase Cloud Messaging v1 API.
+- [Pigeon.ADM](https://hexdocs.pm/pigeon/2.0.0/Pigeon.ADM.html) - Amazon Android.
+- [Pigeon.APNS](https://hexdocs.pm/pigeon/2.0.0/Pigeon.APNS.html) - Apple iOS.
+- [Pigeon.FCM](https://hexdocs.pm/pigeon/2.0.0/Pigeon.FCM.html) - Firebase Cloud Messaging v1 API.
 
 ### Creating Dynamic Runtime Dispatchers
 
 Pigeon can spin up dynamic dispatchers for a variety of advanced use-cases, such as
 supporting dozens of dispatcher configurations or custom connection pools.
 
-See [Pigeon.Dispatcher](https://hexdocs.pm/pigeon/2.0.0-rc.1/Pigeon.Dispatcher.html) for instructions.
+See [Pigeon.Dispatcher](https://hexdocs.pm/pigeon/2.0.0/Pigeon.Dispatcher.html) for instructions.
 
 ### Writing a Custom Dispatcher Adapter
 
 Want to write a Pigeon adapter for an unsupported push notification service?
 
-See [Pigeon.Adapter](https://hexdocs.pm/pigeon/2.0.0-rc.1/Pigeon.Adapter.html) for instructions.
+See [Pigeon.Adapter](https://hexdocs.pm/pigeon/2.0.0/Pigeon.Adapter.html) for instructions.
 
 ## Contributing
 

docs/Migrating to v2-0-0.md

@@ -0,0 +1,134 @@
+# Migrating to v2.0
+
+## Migrating from v2.0 RCs
+
+See the CHANGELOG for specific breaking changes from each RC. If upgrading from RC3,
+no additional changes are required.
+
+## Migrating from v1.6
+
+1. Update your mix.exs dependencies.
+
+```diff
+[
+  + {:pigeon, "~> 2.0"} # Change this
+  - {:kadadbra, ~> 0.6.0} # Remove this
+]
+```
+
+2. Update configuration of your push workers.
+
+Pigeon push workers are now started under your application supervision tree instead of
+Pigeon.
+
+Using APNS as an example, if you have a default push worker configured like this:
+
+```
+config :pigeon, :apns,
+  apns_default: %{
+    cert: "cert.pem",
+    key: "key_unencrypted.pem",
+    mode: :dev
+  }
+```
+
+Remove the config and instead define a push worker like this:
+
+```
+# lib/your_app/apns.ex
+
+defmodule YourApp.APNS do
+  use Pigeon.Dispatcher, otp_app: :your_app
+end
+```
+
+```
+# config.exs
+
+config :your_app, YourApp.APNS,
+  adapter: Pigeon.APNS,
+  cert: File.read!("cert.pem"),
+  key: File.read!("key_unencrypted.pem"),
+  mode: :dev
+```
+
+And add it to your supervision tree.
+
+```
+defmodule YourApp.Application do
+  @moduledoc false
+
+  use Application
+
+  @doc false
+  def start(_type, _args) do
+    children = [
+      YourApp.APNS
+    ]
+    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+end
+```
+
+Configuration of the worker can now be passed directly if desired.
+
+```
+defmodule YourApp.Application do
+  @moduledoc false
+
+  use Application
+
+  @doc false
+  def start(_type, _args) do
+    children = [
+      {YourApp.APNS, apns_opts()}
+    ]
+    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+
+  defp apns_opts do
+    [
+      adapter: Pigeon.APNS,
+      cert: File.read!("cert.pem"),
+      key: File.read!("key_unencrypted.pem"),
+      mode: :dev
+    ]
+  end
+end
+```
+
+And that's it! See the rest of this guide for other breaking changes specific to your
+push type.
+
+### Breaking Changes for ADM
+
+No addtional changes required apart from the configuration above.
+
+### Breaking Changes for APNS
+
+- `:certfile` and `:keyfile` are no longer valid options for APNS configurations.
+  Instead, read the file before loading (e.g. `cert: File.read!("cert.pem")`)
+  ([#183](https://github.com/codedge-llc/pigeon/pull/183))
+
+### Breaking Changes for FCM
+
+1. FCM's legacy API, used by Pigeon v1.6, has been decommissioned. To upgrade, add the legacy
+   adapter to your mix.exs.
+
+```elixir
+def deps do
+  [
+    {:pigeon_legacy_fcm, "~> 0.1.0"}
+  ]
+end
+```
+
+2. Rename all instances of `Pigeon.FCM` in your project to `Pigeon.LegacyFCM`. For example,
+   `Pigeon.FCM.Notification` becomes `Pigeon.LegacyFCM.Notification`.
+
+Once renamed, your project should now compile again.
+
+3. Upgrade to the new FCM v1 API. Follow the instructions in `Pigeon.FCM` to set up a new
+   push worker and update your Pigeon FCM notifications accordingly.