From 27510d713ecff709381d6a64ae14685e39a73b9b Mon Sep 17 00:00:00 2001
From: "feliks.pobiedzinski@swmansion.com" <feliks.pobiedzinski@swmansion.com>
Date: Tue, 3 Oct 2023 12:28:20 +0200
Subject: [PATCH] Write upgrading guide for v1.0.0-rc1

---
 guides/upgrading/v1.0.0-rc1.md | 48 ++++++++++++++++++++++++++++++++++
 mix.exs                        |  1 +
 2 files changed, 49 insertions(+)
 create mode 100644 guides/upgrading/v1.0.0-rc1.md

diff --git a/guides/upgrading/v1.0.0-rc1.md b/guides/upgrading/v1.0.0-rc1.md
new file mode 100644
index 000000000..d96637b5f
--- /dev/null
+++ b/guides/upgrading/v1.0.0-rc1.md
@@ -0,0 +1,48 @@
+# Upgrading to v1.0.0-rc1
+
+### Remove `handle_buffers_batch/4`/`handle_process_list/4`/`handle_write_list/4` callback
+
+In `v1.0.0-rc1` we removed `handle_buffers_batch/4` callback. Instead of handling list of buffer in this callback, you have to handle every single buffer separately in `hanlde_buffer/4` callback.
+
+```diff
+@impl true
+- def handle_buffers_batch(pad_ref, buffers_list, ctx, state) do
++ def handle_buffer(pad_ref, buffer, ctx, state) do
+  ...
+end
+```
+
+Notice, if you are upgrading your code from `v0.12.*` directly to `v1.0.0-rc1`, omitting `v1.0.0-rc0`, there is a chance, that your elements still have callback named `handle_process_list/4` or `handle_write_list/4`, instead of `handle_buffers_batch/4`.
+
+```diff
+@impl true
+- def handle_process_list(pad_ref, buffers_list, ctx, state) do
++ def handle_buffer(pad_ref, buffer, ctx, state) do
+  ...
+end
+```
+
+```diff
+@impl true
+- def handle_write_list(pad_ref, buffers_list, ctx, state) do
++ def handle_buffer(pad_ref, buffer, ctx, state) do
+  ...
+end
+```
+
+### Implement you own `start/*`, `start_link/*` or `terminate/1` function (if you want to)
+
+Until `v1.0.0-rc0`, Membrane has generated `start/2`, `start_link/2`, and `terminate/1` functions in modules using `Membrane.Pipeline`, if code developer hadn't done it explicitly. Since `v1.0.0-rc1`, if you want to have these functions implemented in your pipeline module, you have to implement them on your own. Alternatively, you can always call `Membrane.Pipeline.start(YourPipelineModule, init_arg, opts)`, `Membrane.Pipeline.start_link(YourPipelineModule, init_arg, opts)`, and `Membrane.Pipeline.terminate(pipeline_pid)` from beyond `YourPipelineModule` without wrapping it into public functions.
+
+### Rename `:structure` option passed to the `Membrane.Testing.Pipeline` into `:spec`
+
+```diff
+import Membrane.ChildrenSpec
+
+spec = 
+  child(:source, %Membrane.Testing.Source{some_field: some_arg})
+  |> child(:sink), %Membrane.Testing.Sink{another_filed: another_arg}
+
+- pipeline = Membrane.Testing.Pipeline.start_link_supervised(structure: spec)
++ pipeline = Membrane.Testing.Pipeline.start_link_supervised(spec: spec)
+```
\ No newline at end of file
diff --git a/mix.exs b/mix.exs
index 27689f59a..ee97449af 100644
--- a/mix.exs
+++ b/mix.exs
@@ -65,6 +65,7 @@ defmodule Membrane.Mixfile do
         "CONTRIBUTING.md",
         "guides/upgrading/v0.11.md",
         "guides/upgrading/v1.0.0-rc0.md",
+        "guides/upgrading/v1.0.0-rc1.md",
         LICENSE: [title: "License"]
       ],
       formatters: ["html"],