add migration guide (#299)

docs/api/v0_3_0.md

@@ -0,0 +1,47 @@
+# v0.3.0 migration guide
+
+Version 0.3.0 of magicgui introduced some changes to the events and callbacks API.
+See https://github.com/napari/magicgui/pull/253 for details
+
+## Callbacks now receive the value directly, instead of an `Event` object
+
+magicgui 0.3.0 is now using [psygnal](https://github.com/tlambert03/psygnal)
+as its event/callback handler.
+
+Callbacks connected to `widget.changed` (and other event emitters) now receive the
+value(s) directly, instead of an event object:
+
+```python
+# before:
+@widget.changed.connect
+def my_callback(event):
+    new_value = event.value
+
+# now becomes
+@widget.changed.connect
+def my_callback(value):
+    new_value = value
+
+# note also that psygnal lets you accept _less_
+# arguments than the emitter provides
+# so this also works fine
+@widget.changed.connect
+def my_callback():
+    # something that didn't need the value
+    ...
+```
+
+## Event emitters take no keyword arguments
+
+For the few packages who were manually emitting change events,
+you should no longer provide the `value=` keyword when emitting.
+
+```python
+# before:
+widget.changed(value='whatever')
+
+# now becomes
+widget.changed.emit('whatever')
+# OR (if you prefer the direct __call__ syntax)
+widget.changed('whatever')
+```