# Deprecations<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

== Description

Deprecated settings still work. Updatecli accepts the old form, logs a warning, and translates it to
the new one, so a manifest written years ago keeps running. The warning is the notice: nothing on
this page breaks a pipeline today, and everything on it may break one eventually.

Entries are grouped by area, newest deprecation first within each group. The `Since` column is the
first release that emitted the warning, established from the Git history rather than from the
release notes (see the link:/changelogs/updatecli[changelogs] for what shipped in each release).

TIP: To find out whether your own manifests are affected, run `updatecli pipeline diff` and read the
warnings. Nothing needs to be applied, a `diff` parses and validates the whole manifest, which is
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>>.

== Commands

The four original top-level commands moved under `pipeline` and `manifest`. All four still run and
log `Deprecated command, please instead use ...`.

[cols="1,1,1", options="header"]
|===
| Deprecated | Use instead | Since

| `updatecli apply`
| `updatecli pipeline apply`
| v0.114.0

| `updatecli diff`
| `updatecli pipeline diff`
| v0.114.0

| `updatecli prepare`
| `updatecli pipeline prepare`
| v0.114.0

| `updatecli show`
| `updatecli manifest show`
| v0.31.0
|===

See the link:/docs/commands/[Commands] reference for the current command tree.

== Manifest keys

=== Stage identifiers

Mixed-case and snake_case keys were normalised to lowercase. The old spelling is copied onto the new
key and cleared.

[cols="1,1,2,1", options="header"]
|===
| Deprecated | Use instead | Applies to | Since

| `scmID`
| `scmid`
| sources, conditions, targets, actions
| v0.23.0

| `sourceID`
| `sourceid`
| conditions, targets
| v0.23.0

| `depends_on`
| `dependson`
| sources, conditions, targets
| v0.34.0

| `conditionids`
| `dependson`, with each entry prefixed `condition#`
| targets
| v0.86.0
|===

`conditionids` is the one that changes shape rather than spelling. A target listing
`conditionids: [check]` becomes:

[source,yaml]
----
targets:
  default:
    dependson:
      - condition#check
----

Updatecli performs that translation itself and, in doing so, also sets `disableconditions: true` on
the target (the conditions named in `dependson` are the only ones that gate it).

IMPORTANT: Setting the old key *and* the new key together is not a warning. `conditionids` combined
with `dependson` makes Updatecli ignore `conditionids`; `conditionids` combined with
`disableconditions: true` is an outright error, because disabling conditions while naming conditions
is contradictory. The same applies to `scmID` alongside `scmid` on an action.

Resource `kind` values must also be lowercase. A capitalised kind is accepted and lowercased with
`kind value "..." must be lowercase`.

=== Top-level keys

[cols="1,1,2,1", options="header"]
|===
| Deprecated | Use instead | Notes | Since

| `pullrequests`
| `actions`
| Mutually exclusive - using both is an error, not a warning
| v0.40.0

| `title`
| `name`
| Names the manifest
| v0.64.1

| `autodiscovery.pullrequestid`
| `autodiscovery.actionid`
| Mutually exclusive - using both is an error
| v0.40.0
|===

=== Action kinds

Both were renamed when actions grew beyond pull requests. Deprecated since v0.40.0.

[cols="1,1", options="header"]
|===
| Deprecated | Use instead

| `kind: github`
| `kind: github/pullrequest`

| `kind: gitea`
| `kind: gitea/pullrequest`
|===

== Transformers

Every camelCase transformer was renamed to lowercase in v0.25.0. The behaviour is unchanged.

[cols="1,1", options="header"]
|===
| Deprecated | Use instead

| `addPrefix`
| `addprefix`

| `addSuffix`
| `addsuffix`

| `trimPrefix`
| `trimprefix`

| `trimSuffix`
| `trimsuffix`

| `semverInc`
| `semverinc`

| `findSubMatch`
| `findsubmatch`

| `findSubMatch.captureIndex`
| `findsubmatch.captureindex`
|===

The deprecated spellings are hidden from the JSON schema, so an editor completing from the schema
will only ever offer the lowercase form. See the
link:/docs/core/transformer/["Transformer" page].

== Actions

=== `github/pullrequest`: `automerge`

Deprecated in v0.116.0 in favour of `merge.strategy`, which offers three behaviours where
`automerge` had two.

[cols="1,1", options="header"]
|===
| Before | After

a|
[source,yaml]
----
actions:
  default:
    kind: github/pullrequest
    spec:
      automerge: true
----

a|
[source,yaml]
----
actions:
  default:
    kind: github/pullrequest
    spec:
      merge:
        strategy: auto
----
|===

`automerge: false` is not a no-op, it translates to `merge.strategy: manual`:

[cols="1,1,3", options="header"]
|===
| Old value | Translates to | Meaning

| `automerge: true`
| `merge.strategy: auto`
| Hand the pull request to GitHub's auto-merge, which merges it once the required checks pass.

| `automerge: false`
| `merge.strategy: manual`
| Leave the pull request open for a human. This is also the default when `merge` is unset.

| - (no equivalent)
| `merge.strategy: client`
| Updatecli merges the pull request itself, after `merge.after` has elapsed (`24h` by default).
|===

`client` has no `automerge` equivalent, so it is only reachable after migrating. See the
link:/docs/plugins/actions/github/["GitHub Pull Request" page].

== Resource plugins

=== 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):

[source,text]
----
Engine "dasel/v1" is deprecated and will be removed in a future updatecli version. Please use "dasel/v3" instead.
----

[WARNING]
====
`dasel/v1` is still the **default**. A `json`, `toml`, or `csv` resource that never mentions `engine`
runs on the deprecated engine and emits that warning on every run. Set the engine explicitly to
silence it:

[source,yaml]
----
sources:
  default:
    kind: json
    spec:
      engine: dasel/v3
      file: package.json
      key: .version
----

`engine: dasel` is an alias that always resolves to the newest engine, currently `dasel/v3`. It is
not deprecated, but it does mean the behaviour of your manifest changes when a new engine lands.
====

Migrating the engine forces a second change. Under `dasel/v2` and `dasel/v3`, `query` is rejected
rather than warned about:

[source,text]
----
engine "dasel/v3" requires the parameter "key" over "query"
----

So rename `query` to `key` in the same edit.

=== Deprecated parameters

[cols="1,1,1,2,1", options="header"]
|===
| Plugin | Deprecated | Use instead | Notes | Since

| `json`, `toml`, `csv`
| `query`
| `key`
| Warning under `dasel/v1`, hard error under `dasel/v2` and `dasel/v3`
| v0.105.0

| `json`, `toml`, `csv`
| `multiple`
| `query`
| `key` + `multiple` is rewritten to `query`
| v0.37.0

| `maven`
| `url`
| `repository`
| Prefix the old URL onto the repository name
| v0.33.0

| `cargopackage`
| `indexurl`
| `registry.url`
| Copied across automatically
| v0.44.0

| `githubrelease`
| `key: name`
| `key: tagname`
|
| v0.97.0

| `githubrelease`
| `key: hash`
| `key: taghash`
|
| v0.97.0
|===

== Commit messages

[WARNING]
====
`commitmessage.title` is **ignored**, not renamed (deprecated in v0.114.0). The commit title is now
always generated from the target `name` (or its `description`), so a manifest that sets it sees no
effect at all beyond the warning:

[source,text]
----
commitMessage.title is deprecated and will be ignored. The commit title is now always generated from the target name or description.
----

To control the commit title, rename the target. Everything else under `commitmessage` (`type`,
`scope`, `body`, `footers`, `hidecredit`) still applies.
====

== YAML key syntax

[WARNING]
====
`yaml` keys are expected to be JSONPath expressions beginning with `$.`. A key written in the older
dotted form is rewritten automatically and warned about, since v0.51.0:

[source,text]
----
current yaml key is "spec.version" and should be updated to "$.spec.version"
----

The rewrite is **scheduled to become an error**. Update the keys now:

[cols="1,1", options="header"]
|===
| Deprecated | Use instead

| `key: spec.version`
| `key: $.spec.version`

| `key: metadata.annotations.example\.com/version`
| `key: $.metadata.annotations.'example.com/version'`
|===

This applies to `key` and to every entry in `keys`, on sources, conditions, and targets alike.
====

== Compose file name

The default compose file was renamed from `update-compose.yaml` to `updatecli-compose.yaml` in
v0.80.0. The old name is still picked up, with a warning:

[source,text]
----
Deprecated default compose file "update-compose.yaml" detected. Please rename it to "updatecli-compose.yaml"
----

If both files exist, Updatecli uses the deprecated one and says so:

[source,text]
----
Both default compose files "update-compose.yaml" and "updatecli-compose.yaml" detected. Please remove "update-compose.yaml" to start using "updatecli-compose.yaml"
----

Renaming the file is the whole migration. See the link:/docs/core/compose/["Compose" page].

== updatecli-action

=== Branches `v1` and `v2`

The `v1` and `v2` branches of `updatecli/updatecli-action` are deprecated. Pin a released version
instead, or track `main` if you deliberately want the branch tip.

Across a whole organization, an Updatecli policy does the migration for you:

.updatecli-compose.yaml
[source,yaml]
----
{{<include "assets/code_example/docs/help/deprecations/updatecli-compose.yaml">}}
----

Then:

[source,shell]
----
updatecli compose diff
updatecli compose apply
----

See the link:/docs/automate/github_action/["GitHub Action" page] for how to pin the action, and
link:/docs/core/compose/["Compose"] for the file format.

== Go Further

* link:/changelogs/updatecli[Changelogs] - what shipped in each release.
* link:/docs/help/troubleshooting/[Troubleshooting] - error messages and what causes them.
* link:/docs/commands/[Commands] - the current command reference.