Skip to content

Commit e962389

Browse files
authored
Adds upgrade guide to Bamboo 2.0 (#582)
What changed? ============ This adds an upgrade guide for migrating to Bamboo 2.0. At its core, there are only two breaking changes: `bamboo_phoenix` being extracted and the new usage of `Mailer.deliver_now` & `Mailer.deliver_later` functions.
1 parent e43a28a commit e962389

File tree

2 files changed

+116
-1
lines changed

2 files changed

+116
-1
lines changed

guides/upgrade_to_2_0.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
Upgrading to Bamboo 2.0
2+
=======================
3+
4+
Bamboo 2.0 ships with some breaking changes (hence the major version bump). But
5+
don't worry, if you love Bamboo just as it is, there's an easy upgrade path.
6+
7+
There are two breaking changes:
8+
9+
- `Bamboo.Phoenix` extracted to [bamboo_phoenix]
10+
- `Bamboo.Mailer.deliver_now/2` and `deliver_later/2` don't raise on errors
11+
12+
Let's cover each in turn.
13+
14+
## Breaking change: `Bamboo.Phoenix` extracted to `bamboo_phoenix`
15+
16+
`Bamboo.Phoenix` has been extracted to the [bamboo_phoenix] library. If you use
17+
`Bamboo.Phoenix` to render your email templates, add `bamboo_phoenix` to your
18+
dependencies:
19+
20+
```elixir
21+
defp deps do
22+
[
23+
...
24+
{:bamboo, "~> 2.0"},
25+
{:bamboo_phoenix, "~> 1.0"}
26+
...
27+
]
28+
end
29+
```
30+
31+
## Breaking change: `deliver_now/2`/`deliver_later/2` return `:ok` & `:error` tuples
32+
33+
`Bamboo.Mailer`'s `deliver_now/2` and `deliver_later/2` no longer raise errors.
34+
Instead, they now return an `{:ok, email}` and `{:error, error}`, where the
35+
`error` is an exception struct or an error message. If you pass `response:
36+
true` as an argument, the return value will be `{:ok, email, response}`.
37+
38+
If you prefer seeing code, this is the change in `@spec` signature for
39+
`deliver_now/2`:
40+
41+
```diff
42+
- @spec deliver_now(Bamboo.Email.t(), Enum.t()) :: Bamboo.Email.t() | {Bamboo.Email.t(), any}
43+
+ @spec deliver_now(Bamboo.Email.t(), Enum.t()) ::
44+
+ {:ok, Bamboo.Email.t()}
45+
+ | {:ok, Bamboo.Email.t(), any}
46+
+ | {:error, Exception.t() | String.t()}
47+
```
48+
49+
Note that `deliver_later/2` will only return errors that happen _prior_ to
50+
scheduling the delivery of the email. What happens once the delivery is
51+
scheduled depends on what [delivery strategy] you are using.
52+
53+
Those who want to handle errors on their own can now pattern match on the `:ok`
54+
and `:error` tuple responses. If you don't want to handle the errors and like
55+
how Bamboo behaves prior to 2.0, there's a simple upgrade path. 👇
56+
57+
### Simple upgrade path
58+
59+
`Bamboo.Mailer` comes with `deliver_now!/2` and `deliver_later!/2`. Those two
60+
functions mirror the behavior that `deliver_now/2` and `deliver_later/2` had
61+
before 2.0.
62+
63+
Hopefully, that makes for a simple upgrade path for those who don't want to
64+
handle the `{:ok, email}` and `{:error, error}` tuples. You only need to
65+
change:
66+
67+
- `deliver_now/2` to `deliver_now!/2`, and
68+
- `deliver_later/2` to `deliver_later!/2`
69+
70+
Note that `deliver_later!/2` will only raise email validation errors _before_
71+
scheduling the email delivery. What happens after the delivery is scheduled
72+
depends on the [delivery strategy] you are using (e.g.
73+
`TaskSupervisorStrategy`).
74+
75+
### `TaskSupervisorStrategy`
76+
77+
Regardless of whether you use `deliver_later/2` or `deliver_later!/2`, if you
78+
use the `TaskSupervisorStrategy` for delivering emails, it will continue to
79+
raise errors when emails fail to be delivered.
80+
81+
If you want control of those errors, you can implement a custom [delivery
82+
strategy], to handle errors coming from `adapter.deliver`.
83+
84+
For now, `TaskSupervisorStrategy` continues to work as it did prior to `2.0`,
85+
so no change is needed here to upgrade to Bamboo 2.0.
86+
87+
### Check with your adapter
88+
89+
Each adapter needs to upgrade to satisfy the new [adapter.deliver callback].
90+
Check with your adapter to see if it supports the new `ok` and `error` tuple
91+
API before upgrading to Bamboo 2.0.
92+
93+
If you use SendGrid, Mailgun, or Mandrill, your adapter is already updated with
94+
Bamboo 2.0.
95+
96+
That's it! For a full list of changes, please refer to the [changelog].
97+
98+
And if you find any issues with this upgrade guide, please let us know by
99+
[opening an issue] or submitting a pull-request.
100+
101+
[adapter.deliver callback]: https://hexdocs.pm/bamboo/2.0.0/Bamboo.Adapter.html#c:deliver/2
102+
[delivery strategy]: https://hexdocs.pm/bamboo/2.0.0/Bamboo.DeliverLaterStrategy.html
103+
[opening an issue]: https://github.com/thoughtbot/bamboo/issues
104+
[bamboo_phoenix]: https://hexdocs.pm/bamboo_phoenix
105+
[changelog]: https://github.com/thoughtbot/bamboo/blob/master/CHANGELOG.md

mix.exs

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ defmodule Bamboo.Mixfile do
1919
build_embedded: Mix.env() == :prod,
2020
start_permanent: Mix.env() == :prod,
2121
package: package(),
22-
docs: [main: "readme", extras: ["README.md"]],
22+
docs: docs(),
2323
deps: deps(),
2424
xref: [exclude: [IEx]]
2525
]
@@ -47,6 +47,16 @@ defmodule Bamboo.Mixfile do
4747
defp elixirc_paths(_), do: elixirc_paths()
4848
defp elixirc_paths, do: ["lib"]
4949

50+
defp docs do
51+
[
52+
main: "readme",
53+
extras: [
54+
"README.md",
55+
"guides/upgrade_to_2_0.md"
56+
]
57+
]
58+
end
59+
5060
defp deps do
5161
[
5262
{:plug, "~> 1.0"},

0 commit comments

Comments
 (0)