fix: alias depends_on to depends-on (#1310)

Inspired by #1308

Note that the schema is updated to also understand both but with
deprecation documentation. And the ability to removed this after future
releases to force users that lint their toml to be using the correct
version.

docs/examples/cpp-sdl.md

@@ -23,7 +23,7 @@ Run the `start` command
 pixi run start
 ```
 
-Using the [`depends_on`](../features/advanced_tasks.md#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks.
+Using the [`depends-on`](../features/advanced_tasks.md#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks.
 
 ```shell
 # Configure the CMake project

docs/features/advanced_tasks.md

@@ -27,7 +27,7 @@ configure = { cmd = [
 ] }
 
 # Depend on other tasks
-build = { cmd = ["ninja", "-C", ".build"], depends_on = ["configure"] }
+build = { cmd = ["ninja", "-C", ".build"], depends-on = ["configure"] }
 
 # Using environment variables
 run = "python main.py $PIXI_PROJECT_ROOT"
@@ -62,9 +62,9 @@ Results in the following lines added to the `pixi.toml`
 # Configures CMake
 configure = "cmake -G Ninja -S . -B .build"
 # Build the executable but make sure CMake is configured first.
-build = { cmd = "ninja -C .build", depends_on = ["configure"] }
+build = { cmd = "ninja -C .build", depends-on = ["configure"] }
 # Start the built executable
-start = { cmd = ".build/bin/sdl_example", depends_on = ["build"] }
+start = { cmd = ".build/bin/sdl_example", depends-on = ["build"] }
 ```
 
 ```shell
@@ -95,7 +95,7 @@ Results in the following `pixi.toml`.
 ```toml title="pixi.toml"
 fmt = "ruff"
 lint = "pylint"
-style = { depends_on = ["fmt", "lint"] }
+style = { depends-on = ["fmt", "lint"] }
 ```
 
 Now run both tools with one command.

docs/reference/cli.md

@@ -155,12 +155,12 @@ pixi run --environment cuda python
     This is done so that the run commands can be run across all platforms.
 
 !!! tip "Cross environment tasks"
-    If you're using the `depends_on` feature of the `tasks`, the tasks will be run in the order you specified them.
-    The `depends_on` can be used cross environment, e.g. you have this `pixi.toml`:
+    If you're using the `depends-on` feature of the `tasks`, the tasks will be run in the order you specified them.
+    The `depends-on` can be used cross environment, e.g. you have this `pixi.toml`:
     ??? "pixi.toml"
         ```toml
         [tasks]
-        start = { cmd = "python start.py", depends_on = ["build"] }
+        start = { cmd = "python start.py", depends-on = ["build"] }
 
         [feature.build.tasks]
         build = "cargo build"
@@ -250,7 +250,7 @@ This adds the following to the [manifest file](configuration.md):
 [tasks]
 cow = "cowpy \"Hello User\""
 tls = { cmd = "ls", cwd = "tests" }
-test = { cmd = "cargo t", depends_on = ["build"] }
+test = { cmd = "cargo t", depends-on = ["build"] }
 
 [target.osx-64.tasks]
 build-osx = "METAL=1 cargo build"

docs/reference/configuration.md

@@ -171,8 +171,8 @@ Pixi's tasks are run in a pixi environment using `pixi run` and are executed usi
 [tasks]
 simple = "echo This is a simple task"
 cmd = { cmd="echo Same as a simple task but now more verbose"}
-depending = { cmd="echo run after simple", depends_on="simple"}
-alias = { depends_on=["depending"]}
+depending = { cmd="echo run after simple", depends-on="simple"}
+alias = { depends-on=["depending"]}
 download = { cmd="curl -o file.txt https://example.com/file.txt" , outputs=["file.txt"]}
 build = { cmd="npm build", cwd="frontend", inputs=["frontend/package.json", "frontend/*.js"]}
 run = { cmd="python run.py $ARGUMENT", env={ ARGUMENT="value" }}

docs/tutorials/ros2.md

@@ -168,7 +168,7 @@ pixi run hello
 ???+ tip "Advanced task usage"
     Tasks are a powerful feature in pixi.
 
-    - You can add [`depends_on`](../features/advanced_tasks.md#depends-on) to the tasks to create a task chain.
+    - You can add [`depends-on`](../features/advanced_tasks.md#depends-on) to the tasks to create a task chain.
     - You can add [`cwd`](../features/advanced_tasks.md#working-directory) to the tasks to run the task in a different directory from the root of the project.
     - You can add [`inputs` and `outputs`](../features/advanced_tasks.md#caching) to the tasks to create a task that only runs when the inputs are changed.
     - You can use the [`target`](../reference/configuration.md#the-target-table) syntax to run specific tasks on specific machines.
@@ -177,7 +177,7 @@ pixi run hello
 [tasks]
 sim = "ros2 run turtlesim turtlesim_node"
 build = {cmd = "colcon build --symlink-install", inputs = ["src"]}
-hello = { cmd = "ros2 run my_package my_node", depends_on = ["build"] }
+hello = { cmd = "ros2 run my_package my_node", depends-on = ["build"] }
 ```
 
 ## Build a C++ node

docs/tutorials/rust.md

@@ -177,7 +177,7 @@ You can add a formatting task to your project:
 pixi task add fmt "cargo fmt"
 ```
 
-You can extend these tasks to run multiple commands with the use of the `depends_on` field.
+You can extend these tasks to run multiple commands with the use of the `depends-on` field.
 ```shell
 pixi task add lint "cargo clippy" --depends-on fmt
 ```

examples/cpp-sdl/pixi.toml

@@ -9,7 +9,7 @@ platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
 [tasks.start]
 # Start the built executable
 cmd = ".build/bin/sdl_example"
-depends_on = ["build"]
+depends-on = ["build"]
 
 [dependencies]
 sdl2 = "2.26.5.*"
@@ -36,7 +36,7 @@ outputs = [".build/CMakeFiles/"]
 # Build the executable but make sure CMake is configured first.
 [feature.build.tasks.build]
 cmd = ["cmake", "--build", ".build"]
-depends_on = ["configure"]
+depends-on = ["configure"]
 inputs = ["CMakeLists.txt", "src/*"]
 outputs = [".build/bin/sdl_example"]
 

examples/ctypes-factorial/README.md

@@ -6,7 +6,7 @@ This examples calculates approximate factorials of large numbers using pure Pyth
 ## Features demonstrated:
 - packaging C and Python libraries together
 - compiling with gcc through Pixi tasks
-- conditional Pixi task execution (`depends_on`)
+- conditional Pixi task execution (`depends-on`)
 - defining tasks with arguments
 
 

examples/ctypes-factorial/pixi.toml

@@ -35,7 +35,7 @@ start = { cmd = [
   "12345678",
   "-e",
   "python",
-], depends_on = "compile" }
+], depends-on = "compile" }
 
 [target.osx-64.tasks]
 compile = { cmd = "clang -shared -o src/factorial.so src/factorial.c" }

examples/multi-machine/pixi.toml

@@ -8,7 +8,7 @@ platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
 [tasks]
 train = "python train.py"
 test = "python test.py"
-start = { depends_on = ["train", "test"] }
+start = { depends-on = ["train", "test"] }
 
 [dependencies]
 python = "3.11.*"

examples/qgis/pixi.toml

@@ -8,7 +8,7 @@ platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"]
 
 [tasks]
 get-data = "python get_data.py"
-start = { cmd = "qgis earthquakes_example.qgz", depends_on = "get-data" }
+start = { cmd = "qgis earthquakes_example.qgz", depends-on = "get-data" }
 
 [dependencies]
 qgis = "3.32.1.*"

pixi.toml

@@ -53,6 +53,7 @@ deploy-dev = "mike deploy --push dev devel"
 
 [feature.schema.tasks]
 generate-schema = { cmd = "python model.py > schema.json", cwd = "schema" }
+# Using deprecated `depends_on` to avoid conflicts in ci. Changes after release.
 test-schema = { cmd = "pytest -s", depends_on = "generate-schema", cwd = "schema" }
 toml-lint = "taplo lint --verbose **/pixi.toml"
 toml-format = "taplo fmt **/pixi.toml"

schema/examples/valid/full.toml

@@ -41,13 +41,14 @@ package1 = { version = ">=1.2.3", build="py34_0" }
 
 [tasks]
 build = "conda build ."
+# deprecated depends_on
 test = { cmd = "pytest", cwd = "tests", depends_on = ["build"] }
 test2 = { cmd = "pytest", cwd = "tests"}
-test3 = { cmd = "pytest", depends_on = ["test2"] }
-test4 = { cmd = "pytest", cwd = "tests", depends_on = ["test2"] }
+test3 = { cmd = "pytest", depends-on = ["test2"] }
+test4 = { cmd = "pytest", cwd = "tests", depends-on = ["test2"] }
 test5 = { cmd = "pytest" }
-test6 = { depends_on = ["test5"] }
-test7 = { cmd = "pytest", cwd = "tests", depends_on = ["test5"], env = {PYTHONPATH = "bla", "WEIRD_STRING" = "blu"}}
+test6 = { depends-on = ["test5"] }
+test7 = { cmd = "pytest", cwd = "tests", depends-on = ["test5"], env = {PYTHONPATH = "bla", "WEIRD_STRING" = "blu"}}
 
 [system-requirements]
 linux = "5.10"
@@ -102,12 +103,12 @@ package1 = { version = ">=1.2.3", build="py34_0" }
 
 [target.linux-64.tasks]
 build = "conda build ."
-test = { cmd = "pytest", cwd = "tests", depends_on = ["build"] }
+test = { cmd = "pytest", cwd = "tests", depends-on = ["build"] }
 test2 = { cmd = "pytest", cwd = "tests"}
-test3 = { cmd = "pytest", depends_on = ["test2"] }
-test4 = { cmd = "pytest", cwd = "tests", depends_on = ["test2"] }
+test3 = { cmd = "pytest", depends-on = ["test2"] }
+test4 = { cmd = "pytest", cwd = "tests", depends-on = ["test2"] }
 test5 = { cmd = "pytest" }
-test6 = { depends_on = ["test5"] }
+test6 = { depends-on = ["test5"] }
 
 [feature.test.target.linux-64.dependencies]
 test = "*"

schema/model.py

@@ -235,8 +235,15 @@ class TaskInlineTable(StrictBaseModel):
         description="A shell command to run the task in the limited, but cross-platform `bash`-like `deno_task_shell`. See the documentation for [supported syntax](https://pixi.sh/latest/features/advanced_tasks/#syntax)",
     )
     cwd: PathNoBackslash | None = Field(None, description="The working directory to run the task")
+    # BREAK: `depends_on` is deprecated, use `depends-on`
+    depends_on_deprecated: list[TaskName] | TaskName | None = Field(
+        None,
+        alias = "depends_on",
+        description="The tasks that this task depends on. Environment variables will **not** be expanded. Deprecated in favor of `depends-on` from v0.21.0 onward.",
+    )
     depends_on: list[TaskName] | TaskName | None = Field(
         None,
+        alias="depends-on",
         description="The tasks that this task depends on. Environment variables will **not** be expanded.",
     )
     inputs: list[Glob] | None = Field(

schema/schema.json

@@ -1135,9 +1135,28 @@
           "type": "string",
           "pattern": "^[^\\\\]+$"
         },
+        "depends-on": {
+          "title": "Depends-On",
+          "description": "The tasks that this task depends on. Environment variables will **not** be expanded.",
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "description": "A valid task name.",
+                "type": "string",
+                "pattern": "^[^\\s\\$]+$"
+              }
+            },
+            {
+              "description": "A valid task name.",
+              "type": "string",
+              "pattern": "^[^\\s\\$]+$"
+            }
+          ]
+        },
         "depends_on": {
           "title": "Depends On",
-          "description": "The tasks that this task depends on. Environment variables will **not** be expanded.",
+          "description": "The tasks that this task depends on. Environment variables will **not** be expanded. Deprecated in favor of `depends-on` from v0.21.0 onward.",
           "anyOf": [
             {
               "type": "array",

src/cli/task.rs

@@ -347,7 +347,7 @@ impl From<Task> for Item {
                 }
                 if !process.depends_on.is_empty() {
                     table.insert(
-                        "depends_on",
+                        "depends-on",
                         Value::Array(Array::from_iter(
                             process
                                 .depends_on
@@ -368,7 +368,7 @@ impl From<Task> for Item {
             Task::Alias(alias) => {
                 let mut table = Table::new().into_inline_table();
                 table.insert(
-                    "depends_on",
+                    "depends-on",
                     Value::Array(Array::from_iter(
                         alias
                             .depends_on

src/project/manifest/pyproject.rs

@@ -280,11 +280,11 @@ mod tests {
 
         [tool.pixi.tasks]
         build = "conda build ."
-        test = { cmd = "pytest", cwd = "tests", depends_on = ["build"] }
+        test = { cmd = "pytest", cwd = "tests", depends-on = ["build"] }
         test2 = { cmd = "pytest", cwd = "tests"}
-        test3 = { cmd = "pytest", depends_on = ["test2"] }
+        test3 = { cmd = "pytest", depends-on = ["test2"] }
         test5 = { cmd = "pytest" }
-        test6 = { depends_on = ["test5"] }
+        test6 = { depends-on = ["test5"] }
 
         [tool.pixi.system-requirements]
         linux = "5.10"
@@ -333,11 +333,11 @@ mod tests {
 
         [tool.pixi.target.linux-64.tasks]
         build = "conda build ."
-        test = { cmd = "pytest", cwd = "tests", depends_on = ["build"] }
+        test = { cmd = "pytest", cwd = "tests", depends-on = ["build"] }
         test2 = { cmd = "pytest", cwd = "tests"}
-        test3 = { cmd = "pytest", depends_on = ["test2"] }
+        test3 = { cmd = "pytest", depends-on = ["test2"] }
         test5 = { cmd = "pytest" }
-        test6 = { depends_on = ["test5"] }
+        test6 = { depends-on = ["test5"] }
 
         [tool.pixi.feature.test.target.linux-64.dependencies]
         test = "bla"

src/task/mod.rs

@@ -172,7 +172,8 @@ pub struct Execute {
     pub outputs: Option<Vec<String>>,
 
     /// A list of commands that should be run before this one
-    #[serde(default)]
+    // BREAK: Make the alias a renamed field to force kebab-case
+    #[serde(default, alias = "depends-on")]
     #[serde_as(deserialize_as = "OneOrMany<_, PreferMany>")]
     pub depends_on: Vec<TaskName>,
 
@@ -247,6 +248,7 @@ impl CmdArgs {
 #[serde_as]
 pub struct Alias {
     /// A list of commands that should be run before this one
+    #[serde(alias = "depends-on")]
     #[serde_as(deserialize_as = "OneOrMany<_, PreferMany>")]
     pub depends_on: Vec<TaskName>,
 }
@@ -269,13 +271,13 @@ impl Display for Task {
             if depends_on.len() == 1 {
                 write!(
                     f,
-                    ", depends_on = '{}'",
+                    ", depends-on = '{}'",
                     depends_on.iter().map(|t| t.fancy_display()).join(",")
                 )?;
             } else {
                 write!(
                     f,
-                    ", depends_on = [{}]",
+                    ", depends-on = [{}]",
                     depends_on.iter().map(|t| t.fancy_display()).join(",")
                 )?;
             }