From 2f7d23b208061c42736aa0bd7e4202c35ea30584 Mon Sep 17 00:00:00 2001 From: decentral1se Date: Thu, 2 Jan 2025 16:12:14 +0100 Subject: [PATCH] docs: tuning version handling docs --- docs/operators/handbook.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md index 14480e4..1ad3807 100644 --- a/docs/operators/handbook.md +++ b/docs/operators/handbook.md @@ -522,9 +522,9 @@ 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 ``` -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`. +This `.env` version is then used as the recipe checkout version for **all** +`abra` operations afterwards unless you specify otherwise on the command-line +with `[version]` `--chaos/-C` or `--ignore-env-version/-i`. ## How is the new deployment version determined? @@ -536,9 +536,9 @@ 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`. +This `.env` version is then used as the recipe checkout version for **all** +`abra` operations afterwards unless you specify otherwise on the command-line +with `[version]` `--chaos/-C` or `--ignore-env-version/-i`. ### `abra app deploy` @@ -551,10 +551,12 @@ to deploy the following kinds of versions with `abra app deploy`: 4. latest commit with unstaged changes (`--chaos/-C`) 5. recipe version or Git hash (`abra app deploy 1.7.1+1.27.2`) +The app `.env` version is used as the recipe checkout version. + For 2), if the app **is undeployed** and there is an app `.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). +present, then it will be used. This is the *only time* the app `.env` version +is used using `abra app deploy`. 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** as a version candidate. @@ -567,9 +569,9 @@ The app must be deployed already to proceed. * a specific upgrade (`abra app upgrade 1.7.1+1.27.2`) * force re-upgrade (same version, `abra app upgrade --force`) -In all cases, the app `.env` version is **ignored** as a version candidate -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. +The app `.env` version is used as the recipe checkout version. However, it is +otherwise **ignored** for the version candidate. The "source of truth" for the +version candidate is the live deployment of the app. ### `abra app rollback` @@ -579,6 +581,6 @@ The app must be deployed already to proceed. * a specific downgrade (`abra app rollback 1.7.1+1.27.2`) * force re-downgrade (same version, `abra app rollback --force`) -In all cases, the app `.env` version is **ignored** as a version candidate -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. +The app `.env` version is used as the recipe checkout version. However, it is +otherwise **ignored** for the version candidate. The "source of truth" for the +version candidate is the live deployment of the app.