From 9da3fbb43656efb06671b9b6ba6295d01c365696 Mon Sep 17 00:00:00 2001 From: Olblak Date: Sun, 26 Jul 2026 10:58:17 +0200 Subject: [PATCH 1/3] docs: deprecate dasel v1/v2 syntax for v3 Signed-off-by: Olblak --- 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= -# export UPDATECLI_GITHUB_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: - archived:false - branch: "^main$|^master$" # branch accepts regular expressions - email: - limit: 0 # zero means no repository limit + + + + + + + + + + + + + +
BeforeAfter
+ 
+          actions:
+sources:
+  local:
+    name: Get value from json
+    kind: json
+    spec:
+      file: data.json
+      key: firstName
+          
+
+ 		+ 
+          actions:
+sources:
+  local:
+    name: Get value from json
+    kind: json
+    spec:
+      file: data.json
+      key: firstName
+      engine: dasel/v3
+          
+
+
-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 + +## 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= +# export UPDATECLI_GITHUB_USERNAME= +# updatecli compose diff --file updatecli-compose.yaml +# updatecli compose apply --file updatecli-compose.yaml + +valuesinline: + scm: + enabled: true + kind: githubsearch + search: | + org: + archived:false + branch: "^main$|^master$" # branch accepts regular expressions + email: + 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 Date: Tue, 28 Jul 2026 18:43:10 +0200 Subject: [PATCH 2/3] chore: also mention v1/v2 dasel version Signed-off-by: Olblak --- 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. From d209e67efae5ec4864c969305cc759db7fe32c0e Mon Sep 17 00:00:00 2001 From: Olblak Date: Wed, 5 Aug 2026 09:18:53 +0200 Subject: [PATCH 3/3] doc: add dasel deprecation notice Signed-off-by: Olblak --- content/en/docs/help/deprecations.adoc | 76 ++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 6 deletions(-) diff --git a/content/en/docs/help/deprecations.adoc b/content/en/docs/help/deprecations.adoc index 4fddd1d69..88ea59835 100644 --- a/content/en/docs/help/deprecations.adoc +++ b/content/en/docs/help/deprecations.adoc @@ -3,7 +3,7 @@ title: "Deprecations" description: "Every deprecated Updatecli command, manifest key, transformer, and plugin parameter, with the release it was deprecated in and how to migrate." lead: "What changed, since when, and what to write instead" date: 2026-04-11T13:37:00+00:00 -lastmod: 2026-07-30T10:00:00+02:00 +lastmod: 2026-08-05T10:00:00+02:00 draft: false images: [] menu: @@ -34,7 +34,8 @@ where the deprecation warnings come from. Two cases on this page are *not* simple renames, and both are easy to miss: * `commitmessage.title` is **ignored**, not translated - see <<_commit_messages>>. -* Moving a `json`, `toml`, or `csv` resource to `dasel/v3` turns `query` into a **hard error** - see <<_dasel_engines>>. +* Moving a `json`, `toml`, or `csv` resource to `dasel/v3` turns `query` into a **hard error** and +changes the selector syntax - see <<_dasel_engines>>. == Commands @@ -249,13 +250,35 @@ link:/docs/plugins/actions/github/["GitHub Pull Request" page]. === Dasel engines `json`, `toml`, and `csv` read and write through Dasel, selected by the `engine` parameter. -`dasel/v1` and `dasel/v2` are deprecated in favour of `dasel/v3` (since v0.105.0): +`dasel/v3` arrives in v0.120.0 and, from that release, both `dasel/v1` and `dasel/v2` are deprecated +in favour of it: [source,text] ---- Engine "dasel/v1" is deprecated and will be removed in a future updatecli version. Please use "dasel/v3" instead. ---- +The history differs per plugin. `json` has warned about `dasel/v1` since v0.105.0, where the warning +pointed at `dasel/v2` instead. `toml` and `csv` had no `engine` parameter at all before v0.120.0, so +that release is where their first warning appears. + +[cols="1,1,1", options="header"] +|=== +| Plugin | Deprecated engines | Since + +| `json` +| `dasel/v1` +| v0.105.0 (retargeted at `dasel/v3` in v0.120.0) + +| `json` +| `dasel/v2` +| v0.120.0 + +| `toml`, `csv` +| `dasel/v1`, `dasel/v2` +| v0.120.0 +|=== + [WARNING] ==== `dasel/v1` is still the **default**. A `json`, `toml`, or `csv` resource that never mentions `engine` @@ -270,7 +293,7 @@ sources: spec: engine: dasel/v3 file: package.json - key: .version + key: version ---- `engine: dasel` is an alias that always resolves to the newest engine, currently `dasel/v3`. It is @@ -287,18 +310,59 @@ engine "dasel/v3" requires the parameter "key" over "query" So rename `query` to `key` in the same edit. +Setting `engine: dasel/v3` is not a flag flip either. The Dasel v3 selector syntax is richer than the +v1 and v2 one, and it is not backward compatible with it, so the keys themselves have to be rewritten. +The leading dot is the usual casualty, `.version` is a parse error under `dasel/v3`: + +[cols="1,1", options="header"] +|=== +| Before | After + +a| +[source,yaml] +---- +sources: + default: + kind: json + spec: + file: package.json + key: .version +---- + +a| +[source,yaml] +---- +sources: + default: + kind: json + spec: + engine: dasel/v3 + file: package.json + key: version +---- +|=== + +The link:/docs/plugins/resource/json/["JSON" page] compares the selectors engine by engine, and the +link:https://daseldocs.tomwright.me/[Dasel documentation] covers the v3 syntax in full. + === Deprecated parameters [cols="1,1,1,2,1", options="header"] |=== | Plugin | Deprecated | Use instead | Notes | Since -| `json`, `toml`, `csv` +| `json` | `query` | `key` -| Warning under `dasel/v1`, hard error under `dasel/v2` and `dasel/v3` +| Accepted under `dasel/v1`, hard error under `dasel/v2` and `dasel/v3` | v0.105.0 +| `toml`, `csv` +| `query` +| `key` +| Same rule, these plugins only gained `engine` in v0.120.0 +| v0.120.0 + | `json`, `toml`, `csv` | `multiple` | `query`