fix(docs,bisect,checkout): Improve debug output on failures

Sometimes when we issue invalid command during bisect, we need
to be less obscure why did it happen and how to reproduce.
Also use a bit more correct job-filter/platform-filter commands,
even underscore works too.

Signed-off-by: Denys Fedoryshchenko <denys.f@collabora.com>

Author: nuclearcat

docs/checkout.md

@@ -167,6 +167,7 @@ Together with --watch option, you can use --test option to wait for particular t
 - `pass` - return code 0 (test passed)
 - `fail` - return code 1 (test failed)
 - `error` - return code 2 (prior steps failed, such as compilation, test setup, etc, or infrastructure error)
+- `critical error` - return code 64 (kci-dev failed to execute command, crashed, etc)
 
 For example:
 ```sh

kcidev/subcommands/bisect.py

@@ -168,10 +168,10 @@ def bisection_loop(state):
     ]
     # job_filter is array, so we need to add each element as a separate argument
     for job in state["job_filter"]:
-        cmd.append("--job_filter")
+        cmd.append("--job-filter")
         cmd.append(job)
     for platform in state["platform_filter"]:
-        cmd.append("--platform_filter")
+        cmd.append("--platform-filter")
         cmd.append(platform)
     result = kcidev_exec(cmd)
     try:
@@ -187,10 +187,16 @@ def bisection_loop(state):
     elif testret == 2:
         # TBD: Retry failed test to make sure it is not a flaky test
         bisect_result = "skip"
-    else:
-        kci_err("Maestro failed to execute the test")
+    elif testret == 3:
+        kci_err(f"Maestro failed to execute the test.")
         # Internal maestro error, retry procesure
         return None
+    else:
+        kci_err(
+            f"Unknown or critical return code from kci-dev: {testret}. Try to run last command manually and inspect the output:"
+        )
+        kci_err(f"{' '.join(cmd)}")
+        sys.exit(1)
     cmd = ["git", "bisect", bisect_result]
     commitid = git_exec_getcommit(cmd)
     if not commitid:

kcidev/subcommands/checkout.py

@@ -36,7 +36,7 @@ def send_checkout_full(baseurl, token, **kwargs):
         response = requests.post(url, headers=headers, data=jdata, timeout=30)
     except requests.exceptions.RequestException as e:
         kci_err(f"API connection error: {e}")
-        return
+        return None
 
     if response.status_code != 200:
         maestro_api_error(response)
@@ -267,6 +267,10 @@ def checkout(
         platform_filter=platform_filter,
         watch=watch,
     )
+    if not resp:
+        kci_err("Failed to trigger checkout")
+        sys.exit(64)
+
     if resp and "message" in resp:
         click.secho(resp["message"], fg="green")