diff --git a/doc/migration-bird3.md b/doc/migration-bird3.md
new file mode 100644
index 00000000..3dcbc71a
--- /dev/null
+++ b/doc/migration-bird3.md
@@ -0,0 +1,83 @@
+# Migrating from BIRD 2 to BIRD 3
+
+With proper multithreading, we had to change not only the internal architecture,
+but also some user-visible behavior, mostly because these changes were needed
+either for development, or the original features stopped making sense at all
+with the new internal architecture.
+
+We tried to keep these changes as small as possible but as this major upgrade is
+a good opportunity to do backwards-incompatible changes, we obviously had to do
+that to fix some historically inaccurate concepts.
+
+## Threads
+
+Number of working threads is now configured by `threads <num>;` on toplevel.
+By default, this is 1, which actually means 2 running threads. The main one and
+the worker one. When BFD is configured, you get another one for BFD.
+
+Every instance of BGP, BFD, Pipe and RPKI gets its own *loop* which is a packed
+unit transferrable between the working threads.
+
+## Logging
+
+Log files have a slightly different format, indicating by `[abcd]` the actual
+thread logging the message. This enables the user to better comprehend what's
+actually going on between interleaved messages from different threads,
+especially when detailed route tracing is on.
+
+There is also a new logging option, a fixed-size circular logfile. This is handy
+if you need to switch on detailed tracing but you don't want to overfill your disk.
+Also this option is by far the fastest one.
+
+## Tables
+
+It's now possible to set the `debug` option to trace events happening directly
+inside the table.
+
+Also settle timers were changed; there is a configurable idle-state timeout
+before any route export is announced after import is done. This helps to
+coalesce the routes on export and improves BIRD's overall performance.
+
+There is also an explicit back-pressure feature, called cork, to avoid memory
+bloating with route flaps. This feature basically forces the readers to flush
+the table journal before more imports are added. Parameters of the cork are
+configurable.
+
+ROA settle timers were moved into channels.
+
+## Channels
+
+ROA settle timers are set separately per-channel now. Also by default, only
+the possibly affected routes get autoreloaded, contrary to BIRD 2.
+
+Export is now done by blocks which are by default quite large. This may hamper
+responsiveness of single protocols and therefore cause other issues. With
+complex export filters, you may want to drop this value from 16K down. But you
+shouldn't have complex export filters anyway.
+
+Export supports also `export in` form, allowing to export only subprefixes of
+the given prefix. Experimental.
+
+## Route attributes
+
+All protocol attributes have been renamed in CLI to align with the filter language tokens.
+
+Output of `show route all` also shows more information, including some internal
+data for easier debugging and route tracing.
+
+The `onlink` route attribute has been temporarily disabled until we find out
+how to implement it properly.
+
+The `scope` route attribute has been removed. Use custom route attributes instead.
+
+## Pipe
+
+It's now impossible to check immediately whether the route has entered a pipe
+loop. Instead of that, every Pipe pass increases the route's `generation`
+internal attribute, and when it is too high, the route is discarded.
+
+## BGP
+
+The export table now shows the state immediately before sending on the wire,
+thus without custom attributes and after all updates done by BGP. This should
+help with performance a little, while also being more accurate.