docs: new version handling

docs/operators/handbook.md

@@ -500,3 +500,81 @@ will fetch the remote recipe and create a directory for it under `$ABRA_DIR`
 ```
 $ABRA_DIR/recipes/mygit_org_myorg_cool-recipe
 ```
+
+## Saving the version to the app `.env` file
+
+!!! warning "This is only available in the currently unreleased version of `abra`"
+
+If you `abra app new`/`abra app deploy`/`abra app upgrade`/`abra app rollback`,
+the version that is deployed will be written to your app `.env` file. You can
+see this in the `TYPE=/RECIPE=` line of the `.env` where the recipe name is
+shown.
+
+For example, before a deployment of the `custom-html` recipe:
+
+```
+TYPE=custom-html
+```
+
+And after a deployment of version `1.7.1+1.27.2` of the `custom-html` recipe.
+
+```
+TYPE=custom-html:1.7.1+1.27.2
+```
+
+## How is the new deployment version determined?
+
+!!! warning "This is only available in the currently unreleased version of `abra`"
+
+### `.env` version
+
+If you `abra app deploy`/`abra app upgrade`/`abra app rollback`, the version
+that is deployed will be written to your app `.env` file. This is shown in the
+deployment overview.
+
+This `.env` version is then used as the recipe checkout version for all `abra`
+ops afterwards unless you specify a version on the command-line (`[version]`),
+use `--chaos/-C` or `--ignore-env-version/-i`.
+
+### `abra app deploy`
+
+This is the most flexible command so it can be hard to follow. It is possible
+to deploy the following kinds of versions with `abra app deploy`:
+
+1. latest release version (standard `abra app deploy`)
+2. version retrieved from the app `.env` (`TYPE=custom-html:1.7.1+1.27.2`)
+3. latest commit (`--chaos/-C` / no released recipe versions)
+4. latest commit with unstaged changes (`--chaos/-C`)
+5. recipe version or Git hash (`abra app deploy 1.7.1+1.27.2`)
+
+For 2), if the app **is undeployed** and there is a `.env` version present,
+then it will be selected. This is the *only time* the app `.env` version is
+selected. This is done to reduce unwanted upgrades (we do not automatically
+choose the latest release).
+
+Use `--ignore-env-version/-i` to deploy the latest release version or commit.
+In all cases 3-5, the app `.env` version is **ignored**.
+
+### `abra app upgrade`
+
+The app must be deployed already to proceed.
+
+* a new upgrade (standard `abra app upgrade`)
+* a specific upgrade (`abra app upgrade 1.7.1+1.27.2`)
+* force re-upgrade (same version, `abra app upgrade --force`)
+
+In both cases, the app `.env` version is **ignored** because the "source of
+truth" for the app deployment is the live deployment of the app. The app `.env`
+will be shown however in the deployment overview.
+
+### `abra app rollback`
+
+The app must be deployed already to proceed.
+
+* a new downgrade (standard `abra app rollback`)
+* a specific downgrade (`abra app rollback 1.7.1+1.27.2`)
+* force re-downgrade (same version, `abra app rollback --force`)
+
+In both cases, the app `.env` version is **ignored** because the "source of
+truth" for the app deployment is the live deployment of the app. The app `.env`
+will be shown however in the deployment overview.