qdup 0.11 migration guide

Author: diegolovison

docs/migration/qdup-0.11-migration-guide.md

@@ -0,0 +1,148 @@
+# qDup 0.11 Migration Guide
+
+## Breaking Changes in qDup 0.11
+
+qDup 0.11 introduces a breaking change in how commands handle their output and pass it to subsequent actions. This document explains the change and provides examples to help you migrate your scripts.
+
+## The Key Change: Input Flow in `then` Blocks
+
+In qDup 0.11, **actions nested under a command's `then` block receive their input from that command**, not from previous sibling commands.
+
+### Rule Summary
+
+✅ **Works in both 0.10 and 0.11:**
+```yaml
+- sh: command
+  then:
+  - set-state: RESULT
+```
+The `set-state` gets its input from the `sh` command because it's nested under the `sh`'s `then` block.
+
+❌ **Does NOT work in 0.11 (but worked in 0.10):**
+```yaml
+- regex: something
+  then:
+  - sh: command
+  - set-state: RESULT
+```
+The `set-state` will get its input from the `regex`, NOT from the `sh` command, because they are siblings under the same `then` block.
+
+## Migration Examples
+
+### Example 1: Sequential Commands Under a `then` Block
+
+**Old Pattern (qDup < 0.11):**
+```yaml
+- sh: scp ./file.war ${{SCP_PATH}}/file.war
+- regex: No such file or directory
+  then:
+  - abort: failed to build file.war
+```
+
+**New Pattern (qDup 0.11+):**
+```yaml
+- sh: scp ./file.war ${{SCP_PATH}}/file.war
+  then:
+  - regex: No such file or directory
+    then:
+    - abort: failed to build file.war
+```
+
+**Why?** In 0.11, the `regex` must be nested under the `sh`'s `then` block to receive the `sh` command's output.
+
+### Example 2: Multiple Sequential Commands
+
+**Old Pattern (qDup < 0.11):**
+```yaml
+- read-state: ${{SCP_PATH}}
+  then:
+  - sh: scp ./file1.war ${{SCP_PATH}}/file1.war
+  - regex: No such file or directory
+    then:
+    - abort: failed to build file1.war
+  - sh: scp ./file2.war ${{SCP_PATH}}/file2.war
+  - regex: No such file or directory
+    then:
+    - abort: failed to build file2.war
+```
+
+**New Pattern (qDup 0.11+):**
+```yaml
+- read-state: ${{SCP_PATH}}
+  then:
+  - sh: scp ./file1.war ${{SCP_PATH}}/file1.war
+    then:
+    - regex: No such file or directory
+      then:
+      - abort: failed to build file1.war
+  - sh: scp ./file2.war ${{SCP_PATH}}/file2.war
+    then:
+    - regex: No such file or directory
+      then:
+      - abort: failed to build file2.war
+```
+
+**Why?** Each `regex` must be nested under its corresponding `sh` command's `then` block to receive that command's output.
+
+### Example 3: Command with State Setting
+
+**Works in both 0.10 and 0.11:**
+```yaml
+- sh: echo $(($(date "+%s%N" -d "$(head -1 /tmp/first_response.txt)")/1000000))
+  then:
+  - set-state: RUN.LOOP_SERVICE_FIRST_RESP_TIMESTAMP
+```
+
+**Why?** The `set-state` is nested under the `sh`'s `then` block, so it receives the `sh` command's output in both versions.
+
+### Example 4: Conditional Execution
+
+**Old Pattern (qDup < 0.11):**
+```yaml
+- sh: "[[ -f ${{RAPL_PATH}}/rapl-plot ]] || echo GETRAPL;"
+- regex: GET
+  then:
+  - sh: rm -Rf ${{RAPL_PATH}}
+  - sh: mkdir -p ${{RAPL_PATH}}
+  - sh: cd ${{RAPL_PATH}}
+  - sh: git clone https://github.com/example/repo.git
+```
+
+**New Pattern (qDup 0.11+):**
+```yaml
+- sh: "[[ -f ${{RAPL_PATH}}/rapl-plot ]] || echo GETRAPL;"
+  then:
+  - regex: GET
+    then:
+    - sh: rm -Rf ${{RAPL_PATH}}
+    - sh: mkdir -p ${{RAPL_PATH}}
+    - sh: cd ${{RAPL_PATH}}
+    - sh: git clone https://github.com/example/repo.git
+```
+
+**Why?** The `regex` must be nested under the first `sh`'s `then` block to check its output. The subsequent `sh` commands are sequential and don't need further nesting.
+
+## Key Principles
+
+1. **Nesting determines input flow**: An action receives input from its parent command, not from sibling commands.
+
+2. **Sequential commands at the same level**: Commands at the same indentation level are executed sequentially but don't pass output to each other.
+
+3. **Use `then` blocks for dependencies**: If an action needs to process a command's output, nest it under that command's `then` block.
+
+## Migration Checklist
+
+When migrating to qDup 0.11:
+
+- [ ] Identify all `- sh:` commands followed by `- regex:` at the same indentation level
+- [ ] Nest the `- regex:` under the `- sh:`'s `then:` block
+- [ ] Ensure any actions that depend on the `regex` are nested under the `regex`'s `then:` block
+- [ ] Test your scripts with qDup 0.11 to verify correct behavior
+
+## Finding Files to Update
+
+Use this command to find YAML files containing `- sh` commands:
+
+```bash
+find . -name "*.yaml" -type f -exec grep -l -- "- sh" {} \;
+```