From 73e73b39aa21393507149cf86e3c348151444bb7 Mon Sep 17 00:00:00 2001
From: "feliks.pobiedzinski@swmansion.com" <feliks.pobiedzinski@swmansion.com>
Date: Tue, 17 Oct 2023 13:56:07 +0200
Subject: [PATCH] Add upgrading guide for v0.12

---
 guides/upgrading/v0.12.md | 65 +++++++++++++++++++++++++++++++++++++++
 mix.exs                   |  1 +
 2 files changed, 66 insertions(+)
 create mode 100644 guides/upgrading/v0.12.md

diff --git a/guides/upgrading/v0.12.md b/guides/upgrading/v0.12.md
new file mode 100644
index 000000000..d1bda611f
--- /dev/null
+++ b/guides/upgrading/v0.12.md
@@ -0,0 +1,65 @@
+# Upgrading to v0.12
+
+Between v0.11 and v0.12 some breaking changes have occurred, so here comes the guide that will help you adjust your code to the new API. See the [release notes](https://github.com/membraneframework/membrane_core/releases/tag/v0.12.1) for details.
+
+## Deps upgrade
+
+Upgrade `membrane_core` to `v0.12.1`.
+
+```elixir 
+defp deps do
+   [
+     {:membrane_core, "~> 0.12.1"},
+     ...
+   ]
+end
+```
+
+## Implement `handle_child_pad_removed/4` callback in bins and pipelines, if it is needed
+
+Now, if bin removes its pad (e.g. by removing an element linked to the bin's inner pad), bin's parent has to have implemented proper `handle_child_pad_removed/4` callback, to handle it. If there is no such a callback, default behaviour is to raise an error. 
+
+```elixir
+@impl true
+def handle_child_pad_removed(:rtp, Pad.ref(:rtp_input, _ssrc), _ctx, state) do
+  # ...
+end
+```
+
+## Remove `:playback` action
+
+Now, membrane pipelines enter the playing playback by default and they don't have to return a `:playback` action to do it. 
+
+```diff
+- @impl true 
+- def handle_setup(_ctx, state) do
+- {[playback: :playing], state}
+- end
+```
+Instead of it, there is a new action introduced in `membrane_core` v0.12, `setup: :incomplete | :complete`. If you want to defer a moment when a component enters the playing playback, you can return `{:setup, :incomplete}` action from `handle_setup` callback. If you do that, a component will enter the playing playback only when you return `{:setup, :complete}` action from another callback, e.g. `handle_info`.
+
+```diff 
+- @impl true 
+- def handle_setup(_ctx, state) do
+-   Process.send_after(self(), :play, 1000)
+-   {[], state}
+- end
+-
+- @impl true 
+- def handle_info(:play, _ctx, state) do
+-   {[playback: :playing], state} 
+- end
+
++ @impl true 
++ def handle_setup(_ctx, state) do
++   Process.send_after(self(), :play, 1000)
++   {[setup: :incomplete], state}
++ end
++
++ @impl true
++ def handle_info(:play, _ctx, state) do
++   {[setup: :complete], state}
++ end
+```
+
+`:setup` action is available not only in pipelines but in bins and elements as well.
diff --git a/mix.exs b/mix.exs
index e437091d9..28b96748b 100644
--- a/mix.exs
+++ b/mix.exs
@@ -64,6 +64,7 @@ defmodule Membrane.Mixfile do
         "CHANGELOG.md",
         "CONTRIBUTING.md",
         "guides/upgrading/v0.11.md",
+        "guides/upgrading/v0.12.md",
         "guides/upgrading/v1.0.0-rc0.md",
         "guides/upgrading/v1.0.0-rc1.md",
         LICENSE: [title: "License"]