diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bae528b..4176419a 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 3c6d29e4..f539eeb0 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,6 @@ [![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: @@ -19,31 +16,35 @@ 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 diff --git a/docs/Migrating to v2-0-0.md b/docs/Migrating to v2-0-0.md new file mode 100644 index 00000000..20d6f637 --- /dev/null +++ b/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.