migration guides

docs/abra/upgrade.md

@@ -2,14 +2,27 @@
 title: Upgrade
 ---
 
-## Stable release
+## Release channels
+
+### Stable
 
 ```
 abra upgrade
 ```
 
-## Release candidate
+### Release candidate
 
 ```
 abra upgrade --rc
 ```
+
+## Migration guides
+
+### `v0.3.x` -> `v0.4.x`
+
+Make sure to back up your `~/.abra/servers` configurations first for safety.
+
+- `mv ~/.abra/apps ~/.abra/recipes`
+- `find ~/.abra/servers/ -type f -exec sed -i "s/^TYPE=/RECIPE=/g" {} \;`
+- "app name" as a concept went away, `abra` now uses the domain name of an app as the identifier. However, we don't expect to see breaking behaviour if you have `.env` files like `~/.abra/servers/foo.com/mycoolapp.env` and you still want to run `abra app ps mycoolapp`. `abra` still reads the filename to figure out the identifier. When running `abra app new <recipe>`, `abra` will now take the domain name as the name of the `.env` file.
+- `abra` has a new SSH implementation which enforces SSH host key checking. You may run into connection issues as a result of this code churn, please see [this entry](/abra/trouble/#ssh-connection-issues) for help navigating a fix.