Skip to content

fix: reconcile documentation with actual behavior#381

Open
josegonzalez wants to merge 2 commits into
mainfrom
374-tracking-documentation-mismatches
Open

fix: reconcile documentation with actual behavior#381
josegonzalez wants to merge 2 commits into
mainfrom
374-tracking-documentation-mismatches

Conversation

@josegonzalez

@josegonzalez josegonzalez commented Jul 14, 2026

Copy link
Copy Markdown
Member

The review tracked in #374 surfaced six documented behaviors the code did not implement. Where the documentation was the intended spec, the code now matches it: apply and plan fetch a recipe from an http(s) --tasks URL (fetched once per command and reused across flag parsing and execution), and docket init writes a play-level name so --play resolves after scaffolding. The apply marker table, the play-skipped summary, the vars-file bool coercion forms, and the WSL install destination were corrected in the docs to match the code.

The review tracked in #374 surfaced six documented behaviors the code did not implement. Where the documentation was the intended spec, the code now matches it: `apply` and `plan` fetch a recipe from an `http(s)` `--tasks` URL, and `docket init` writes a play-level name so `--play` resolves after scaffolding. The apply marker table, the play-skipped summary, the vars-file bool coercion forms, and the WSL install destination were corrected in the docs to match the code.
@dokku-bot

Copy link
Copy Markdown

sh-checker report

To get the full details, please check in the job output.

shellcheck errors
shellcheck checking is disabled.
shfmt errors

'shfmt -l -d -i 2' returned error 1 finding the following formatting issues:

----------
tests/bats/task_file_url.bats
diff tests/bats/task_file_url.bats.orig tests/bats/task_file_url.bats
--- tests/bats/task_file_url.bats.orig
+++ tests/bats/task_file_url.bats
@@ -46,7 +46,10 @@
     [ -s "$BATS_TEST_TMPDIR/port" ] && break
     sleep 0.1
   done
-  [ -s "$BATS_TEST_TMPDIR/port" ] || { echo "http server did not start"; return 1; }
+  [ -s "$BATS_TEST_TMPDIR/port" ] || {
+    echo "http server did not start"
+    return 1
+  }
   port="$(cat "$BATS_TEST_TMPDIR/port")"
 
   run "$(docket_bin)" plan --tasks "http://127.0.0.1:${port}/tasks.yml" --list-tasks
@@ -75,7 +78,10 @@
     [ -s "$BATS_TEST_TMPDIR/port" ] && break
     sleep 0.1
   done
-  [ -s "$BATS_TEST_TMPDIR/port" ] || { echo "http server did not start"; return 1; }
+  [ -s "$BATS_TEST_TMPDIR/port" ] || {
+    echo "http server did not start"
+    return 1
+  }
   port="$(cat "$BATS_TEST_TMPDIR/port")"
 
   run "$(docket_bin)" plan --tasks "http://127.0.0.1:${port}/missing.yml" --list-tasks
----------

You can reformat the above files to meet shfmt's requirements by typing:

  shfmt -l -d -i 2 -w filename


A remote `--tasks` URL was requested twice per command, once while parsing flags and once while running; the recipe bytes read during flag parsing are now reused when the same source is resolved, so `apply` and `plan` make a single request. Also reformats the new bats test to satisfy shfmt.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants