From 9da3fbb43656efb06671b9b6ba6295d01c365696 Mon Sep 17 00:00:00 2001
From: Olblak <me@olblak.com>
Date: Sun, 26 Jul 2026 10:58:17 +0200
Subject: [PATCH 1/2] docs: deprecate dasel v1/v2 syntax for v3

Signed-off-by: Olblak <me@olblak.com>
---
 content/en/docs/help/deprecations.md | 113 +++++++++++++++++++--------
 1 file changed, 82 insertions(+), 31 deletions(-)

diff --git a/content/en/docs/help/deprecations.md b/content/en/docs/help/deprecations.md
index 15d72a579..c919f6bec 100644
--- a/content/en/docs/help/deprecations.md
+++ b/content/en/docs/help/deprecations.md
@@ -15,44 +15,58 @@ toc: true
 This page tracks deprecation notices for Updatecli and related projects, with
 migration guidance when relevant.
 
-## updatecli-action
-
-### Deprecated branches `v1` and `v2`
-
-The `v1` and `v2` branches of `updatecli/updatecli-action` are deprecated and
-will be removed soon.
+## Updatecli
 
-Use a released GitHub Action version instead, or track the `main` branch if you
-explicitly want the branch tip.
 
-You can migrate repositories to the latest GitHub Action version with the
-following Updatecli policy:
+### v0.120.0
 
-#### `.updatecli-compose.yaml`
+#### `json` - `csv` - `toml`: Dasel v3
 
-```yaml
-# export UPDATECLI_GITHUB_TOKEN=<insert PAT>
-# export UPDATECLI_GITHUB_USERNAME=<insert username>
-# updatecli compose diff --file updatecli-compose.yaml
-# updatecli compose apply --file updatecli-compose.yaml
+The three plugins `json`, `csv`, and `toml` deprecate the dasel v2 syntax in favor of the dasel v3 syntax.
+To ensure backward compatibility, the dasel v2 syntax will continue to work for now but it's recommended to migrate to the dasel v3 as soon as possible.
 
-valuesinline:
-  scm:
-    enabled: true
-    kind: githubsearch
-    search: |
-      org:<replace with your GitHub organization>
-      archived:false
-    branch: "^main$|^master$" # branch accepts regular expressions
-    email: <email associated with the git commits>
-    limit: 0 # zero means no repository limit
+<table class="table">
+  <thead>
+    <tr>
+      <th>Before</th>
+      <th>After</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <pre>
+          <code class="language-yaml">actions:
+sources:
+  local:
+    name: Get value from json
+    kind: json
+    spec:
+      file: data.json
+      key: firstName
+          </code>
+        </pre>
+      </td>
+      <td>
+        <pre>
+          <code class="language-yaml">actions:
+sources:
+  local:
+    name: Get value from json
+    kind: json
+    spec:
+      file: data.json
+      key: firstName
+      engine: dasel/v3
+          </code>
+        </pre>
+      </td>
+    </tr>
+  </tbody>
+</table>
 
-policies:
-  - name: Update Updatecli GitHub action version
-    policy: ghcr.io/updatecli/policies/updatecli/githubaction:0.8.1
-```
+Please be aware the the Dasel v3 syntax is a very rich syntax and not backward compatibility with the Dasel v2 syntax. For more information, please refer to the [Dasel v3 documentation](https://daseldocs.tomwright.me/).
 
-## Updatecli
 
 ### v0.116.0
 
@@ -88,3 +102,40 @@ In Updatecli `v0.116.0`, the parameter `spec.automerge` for the action kind
     </tr>
   </tbody>
 </table>
+
+## updatecli-action
+
+### Deprecated branches `v1` and `v2`
+
+The `v1` and `v2` branches of `updatecli/updatecli-action` are deprecated and
+will be removed soon.
+
+Use a released GitHub Action version instead, or track the `main` branch if you
+explicitly want the branch tip.
+
+You can migrate repositories to the latest GitHub Action version with the
+following Updatecli policy:
+
+#### `.updatecli-compose.yaml`
+
+```yaml
+# export UPDATECLI_GITHUB_TOKEN=<insert PAT>
+# export UPDATECLI_GITHUB_USERNAME=<insert username>
+# updatecli compose diff --file updatecli-compose.yaml
+# updatecli compose apply --file updatecli-compose.yaml
+
+valuesinline:
+  scm:
+    enabled: true
+    kind: githubsearch
+    search: |
+      org:<replace with your GitHub organization>
+      archived:false
+    branch: "^main$|^master$" # branch accepts regular expressions
+    email: <email associated with the git commits>
+    limit: 0 # zero means no repository limit
+
+policies:
+  - name: Update Updatecli GitHub action version
+    policy: ghcr.io/updatecli/policies/updatecli/githubaction:0.8.1
+```

From b002001ca8222f288ff32126a78d8d7cf9be2d82 Mon Sep 17 00:00:00 2001
From: Olblak <me@olblak.com>
Date: Tue, 28 Jul 2026 18:43:10 +0200
Subject: [PATCH 2/2] chore: also mention v1/v2 dasel version

Signed-off-by: Olblak <me@olblak.com>
---
 content/en/docs/help/deprecations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/en/docs/help/deprecations.md b/content/en/docs/help/deprecations.md
index c919f6bec..d536d7ad5 100644
--- a/content/en/docs/help/deprecations.md
+++ b/content/en/docs/help/deprecations.md
@@ -22,7 +22,7 @@ migration guidance when relevant.
 
 #### `json` - `csv` - `toml`: Dasel v3
 
-The three plugins `json`, `csv`, and `toml` deprecate the dasel v2 syntax in favor of the dasel v3 syntax.
+In version `v0.120.0`, the three plugins `json`, `csv`, and `toml` deprecate the dasel v1 and v2 syntax in favor of the dasel v3 syntax.
 To ensure backward compatibility, the dasel v2 syntax will continue to work for now but it's recommended to migrate to the dasel v3 as soon as possible.
 
 <table class="table">