docs: v0.10 migration notes

docs/abra/upgrade.md

@@ -20,6 +20,65 @@ abra upgrade --rc
 
 > General release notes are [here](https://git.coopcloud.tech/coop-cloud/abra/releases/)
 
+### `0.9.x-beta` -> `0.10.x-beta`
+
+> 🎺🎺🎺 This version is currently unreleased 🎺🎺🎺
+
+* We have finally migrated from [`urfave/cli`](https://github.com/urfave/cli)
+  to [`spf13/cobra`](https://cobra.dev) as our command-line handling library.
+  This means we should (hopefully!) not have to deal with so many command-line
+  breaking changes in the future, e.g. how `--` is handled, how flags/args are
+  parsed and so on. We expect to maintain compatibility across this migration,
+  however you might run into something we didn't expect. Please do let us know.
+
+* `spf13/cobra` does not support "shorthand" flags with multiple characters.
+  So, the shorthard flags for `--git-name` / `--git-email` on `abra recipe new`
+  are now `-N` / `-e` respectively.
+
+* Auto-completion for `abra` is handled differently now. See `abra autocomplete
+  --help` for more. The full help output is available for each specific shell,
+  e.g. `abra autocomplete zsh --help`. It is now generated on the fly.
+
+* Several commands now make use of the `--chaos/-C` commands, such as `abra app
+  ps` and `abra app cp`. See `--help` for more.
+
+* `abra` will no longer attempt to parse your `~/.ssh/config`. This means that
+  whatever you configure in your `~/.ssh/config` is the source of truth and
+  `abra` does not try to guess connection details. `abra` now *only* invokes
+  `/usr/bin/ssh`. This also means that `--problems/-p` goes away on `abra
+  server list`.
+
+* `abra app backup` / `abra app restore` now officially use
+  [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)! We
+  are still discussing how to handle this transition wrt. the original
+  `backup-bot`. Please see [this
+  ticket](https://git.coopcloud.tech/coop-cloud/backup-bot/issues/5) for more.
+
+* `--no-domain-checks` has been removed from `abra server add`. See
+  [`#631`](https://git.coopcloud.tech/toolshed/organising/issues/631) for more.
+
+* The output of `abra app ps` is less redundant in order to 1) reduce how much
+  horizontal width is required to render the table and 2) simplify the amount
+  of information shown. The `-w` option was also retired, you can use the
+  standard `watch` command, e.g. `watch abra app ps ...` to get the same
+  functionality.
+
+* Several overview screens have changed their layout. E.g. `abra app deploy`
+  now shows more (hopefully!) useful information. These changes have been made
+  to accomodate the work done around operator collaboration and stable
+  versioning.
+
+* `abra app errors` went away. It never really worked and was retired. You can
+  rely on `abra app logs` for the time being.
+
+* It's not possible to `--chaos/-C` on `upgrade` / `rollback`. See
+  [`#559`](https://git.coopcloud.tech/coop-cloud/organising/issues/559) for
+  more.
+
+* `main` will be chosen for new repositories created by `abra`.
+
+* `abra recipe fetch` now accepts an `--all` flag to fetch all repositories.
+
 ### `0.8.x-beta` -> `0.9.x-beta`
 
 None at this time.