Deprecates experimental_shell_command, replacing with `shell_comman…

…d` (pantsbuild#18255)

Retains the `experimental_shell_command` alias, with removal set for
2.18.

🎉

docs/markdown/Helm/helm-deployments.md

@@ -290,7 +290,7 @@ helm_deployment(
 )
 ```
 
-In the previous example we define a `experimental_shell_command` target that will invoke the `vals eval` command (`vals` needs to be installed in the local machine) as part of the Helm post-rendering machinery, which will result on the `ref+vault` reference being replaced by the actual value stored in Vault at the given path.
+In the previous example we define a `shell_command` target that will invoke the `vals eval` command (`vals` needs to be installed in the local machine) as part of the Helm post-rendering machinery, which will result on the `ref+vault` reference being replaced by the actual value stored in Vault at the given path.
 
 > 📘 Using multiple post-renderers
 >

docs/markdown/Shell/run-shell-commands.md

@@ -6,10 +6,10 @@ hidden: false
 createdAt: "2021-10-04T12:37:58.934Z"
 updatedAt: "2022-02-08T21:13:55.807Z"
 ---
-The [`experimental_shell_command`](doc:reference-experimental_shell_command) target allows you to run any command during a Pants execution, for the purpose of modifying or creating files to be used by other targets, or its (idempotent: see below) side-effects when accessing services over the network.
+The [`shell_command`](doc:reference-shell_command) target allows you to run any command during a Pants execution, for the purpose of modifying or creating files to be used by other targets, or its (idempotent: see below) side-effects when accessing services over the network.
 
 ```python BUILD
-experimental_shell_command(
+shell_command(
     command="./my-script.sh download some-archive.tar.gz",
     tools=["curl", "env", "bash", "mkdir", "tar"],
     outputs=["files/"],
@@ -31,7 +31,7 @@ case "$1" in
 esac
 ```
 
-The `experimental_shell_command` target
+The `shell_command` target
 ---------------------------------------
 
 The `command` field is passed to `bash -c <command>`. The execution sandbox will include any files from the `dependencies` field. Any executable tools that might be used must be specified in the `tools` field, in order to be available on the `PATH` while executing the command.
@@ -51,6 +51,6 @@ In case there are resulting files that should be captured and passed to any cons
 The `experimental_run_shell_command` target
 -------------------------------------------
 
-Unlike `experimental_shell_command`, the [`experimental_run_shell_command` target](doc:reference-experimental_run_shell_command) runs directly in your workspace, without sandboxing.
+Unlike `shell_command`, the [`experimental_run_shell_command` target](doc:reference-experimental_run_shell_command) runs directly in your workspace, without sandboxing.
 
 This target type allows you to formalize the Pants dependencies of shell scripts, and track when their impact on your workspace might have changed. But since its outputs cannot be captured, it must be a root target in your build graph (i.e.: it may not be consumed by other targets).

src/python/pants/backend/shell/goals/test_test.py

@@ -52,7 +52,7 @@ def test_shell_command_as_test(rule_runner: RuleRunner) -> None:
                 """\
                 shell_sources(name="src")
 
-                experimental_shell_command(
+                shell_command(
                   name="msg-gen",
                   command="echo message > msg.txt",
                   tools=["echo"],

src/python/pants/backend/shell/target_types.py

@@ -362,7 +362,9 @@ class SkipShellCommandTestsField(BoolField):
 
 
 class ShellCommandTarget(Target):
-    alias = "experimental_shell_command"
+    alias = "shell_command"
+    deprecated_alias = "experimental_shell_command"
+    deprecated_alias_removal_version = "2.18.0.dev0"
     core_fields = (
         *COMMON_TARGET_FIELDS,
         ShellCommandOutputDependenciesField,
@@ -386,7 +388,7 @@ class ShellCommandTarget(Target):
 
         Example BUILD file:
 
-            experimental_shell_command(
+            shell_command(
                 command="./my-script.sh --flag",
                 tools=["tar", "curl", "cat", "bash", "env"],
                 execution_dependencies=[":scripts"],
@@ -427,7 +429,7 @@ class ShellCommandRunTarget(Target):
         The `command` may use either `{chroot}` on the command line, or the `$CHROOT`
         environment variable to get the root directory for where any dependencies are located.
 
-        In contrast to the `experimental_shell_command`, in addition to `workdir` you only have
+        In contrast to the `shell_command`, in addition to `workdir` you only have
         the `command` and `execution_dependencies` fields as the `tools` you are going to use are
         already on the PATH which is inherited from the Pants environment. Also, the `outputs` does
         not apply, as any output files produced will end up directly in your project tree.

src/python/pants/backend/shell/util_rules/shell_command_test.py

@@ -102,7 +102,7 @@ def test_sources_and_files(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="hello",
                   execution_dependencies=[":build-utils", ":files"],
                   tools=[
@@ -154,7 +154,7 @@ def test_quotes_command(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="quotes",
                   tools=["echo", "tee"],
                   command='echo "foo bar" | tee out.log',
@@ -178,7 +178,7 @@ def test_chained_shell_commands(rule_runner: RuleRunner) -> None:
         {
             "src/a/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="msg",
                   tools=["echo"],
                   output_files=["../msg"],
@@ -188,7 +188,7 @@ def test_chained_shell_commands(rule_runner: RuleRunner) -> None:
             ),
             "src/b/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="msg",
                   tools=["cp", "echo"],
                   output_files=["../msg"],
@@ -218,7 +218,7 @@ def test_chained_shell_commands_with_workdir(rule_runner: RuleRunner) -> None:
         {
             "src/a/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="msg",
                   tools=["echo"],
                   output_files=["msg"],
@@ -229,7 +229,7 @@ def test_chained_shell_commands_with_workdir(rule_runner: RuleRunner) -> None:
             ),
             "src/b/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="msg",
                   tools=["cp", "echo"],
                   output_files=["msg"],
@@ -263,7 +263,7 @@ def test_side_effecting_command(caplog, rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="side-effect",
                   command="echo 'server started' && echo 'warn msg' >&2",
                   tools=["echo"],
@@ -294,7 +294,7 @@ def test_tool_search_path_stable(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="paths",
                   command="mkdir subdir; cd subdir; ls .",
                   tools=["cd", "ls", "mkdir"],
@@ -316,7 +316,7 @@ def test_shell_command_masquerade_as_a_files_target(rule_runner: RuleRunner) ->
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="content-gen",
                   command="echo contents > contents.txt",
                   tools=["echo"],
@@ -359,7 +359,7 @@ def test_package_dependencies(caplog, rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="msg-gen",
                   command="echo message > msg.txt",
                   tools=["echo"],
@@ -372,7 +372,7 @@ def test_package_dependencies(caplog, rule_runner: RuleRunner) -> None:
                   files=[":msg-gen"],
                 )
 
-                experimental_shell_command(
+                shell_command(
                   name="test",
                   command="ls",
                   tools=["ls"],
@@ -403,14 +403,14 @@ def test_execution_dependencies(caplog, rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="a1",
                   command="echo message > msg.txt",
                   output_files=["msg.txt"],
                   workdir="/",
                 )
 
-                experimental_shell_command(
+                shell_command(
                     name="a2",
                     tools=["cat"],
                     command="cat msg.txt > msg2.txt",
@@ -421,7 +421,7 @@ def test_execution_dependencies(caplog, rule_runner: RuleRunner) -> None:
 
                 # Fails because runtime dependencies are not exported
                 # transitively
-                experimental_shell_command(
+                shell_command(
                     name="expect_fail_1",
                     tools=["cat"],
                     command="cat msg.txt",
@@ -430,7 +430,7 @@ def test_execution_dependencies(caplog, rule_runner: RuleRunner) -> None:
                 )
 
                 # Fails because `output_dependencies` are not available at runtime
-                experimental_shell_command(
+                shell_command(
                     name="expect_fail_2",
                     tools=["cat"],
                     command="cat msg.txt",
@@ -441,7 +441,7 @@ def test_execution_dependencies(caplog, rule_runner: RuleRunner) -> None:
 
                 # Fails because runtime dependencies are not fetched transitively
                 # even if the root is requested through `output_dependencies`
-                experimental_shell_command(
+                shell_command(
                     name="expect_fail_3",
                     tools=["cat"],
                     command="cat msg.txt",
@@ -450,7 +450,7 @@ def test_execution_dependencies(caplog, rule_runner: RuleRunner) -> None:
                 )
 
                 # Succeeds because `a1` and `a2` are requested directly
-                experimental_shell_command(
+                shell_command(
                     name="expect_success_1",
                     tools=["cat"],
                     command="cat msg.txt msg2.txt > output.txt",
@@ -461,7 +461,7 @@ def test_execution_dependencies(caplog, rule_runner: RuleRunner) -> None:
 
                 # Succeeds becuase `a1` and `a2` are requested directly and `output_dependencies`
                 # are made available at runtime
-                experimental_shell_command(
+                shell_command(
                     name="expect_success_2",
                     tools=["cat"],
                     command="cat msg.txt msg2.txt > output.txt",
@@ -506,14 +506,14 @@ def test_old_style_dependencies(caplog, rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="a1",
                   command="echo message > msg.txt",
                   outputs=["msg.txt"],
                   workdir="/",\
                 )
 
-                experimental_shell_command(
+                shell_command(
                     name="a2",
                     tools=["cat"],
                     command="cat msg.txt > msg2.txt",
@@ -522,7 +522,7 @@ def test_old_style_dependencies(caplog, rule_runner: RuleRunner) -> None:
                     workdir="/",
                 )
 
-                experimental_shell_command(
+                shell_command(
                     name="expect_success",
                     tools=["cat"],
                     command="cat msg.txt msg2.txt > output.txt",
@@ -594,7 +594,7 @@ def test_path_populated_with_tools(
         {
             "src/BUILD": dedent(
                 f"""\
-                experimental_shell_command(
+                shell_command(
                   name="tools-populated",
                   tools=["which", "{tool_name}"],
                   command='which {tool_name}',
@@ -627,7 +627,7 @@ def test_shell_command_boot_script(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="boot-script-test",
                   tools=[
                     "python3.8",
@@ -656,7 +656,7 @@ def test_shell_command_boot_script_in_build_root(rule_runner: RuleRunner) -> Non
         {
             "BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="boot-script-test",
                   tools=[
                     "python3.8",
@@ -684,7 +684,7 @@ def test_shell_command_extra_env_vars(caplog, rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="extra-env-test",
                   tools=["echo"],
                   extra_env_vars=["FOO", "HELLO=world", "BAR"],
@@ -710,7 +710,7 @@ def test_relative_directories(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="quotes",
                   tools=["echo"],
                   command='echo foosh > ../foosh.txt',
@@ -733,7 +733,7 @@ def test_relative_directories_2(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="quotes",
                   tools=["echo"],
                   command='echo foosh > ../newdir/foosh.txt',
@@ -756,7 +756,7 @@ def test_cannot_escape_build_root(rule_runner: RuleRunner) -> None:
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="quotes",
                   tools=["echo"],
                   command='echo foosh > ../../invalid.txt',
@@ -785,7 +785,7 @@ def test_missing_tool_called(
         {
             "src/BUILD": dedent(
                 """\
-                experimental_shell_command(
+                shell_command(
                   name="gerald-is-not-here",
                   command="gerald hello",
                   log_output=True,

src/python/pants/core/util_rules/adhoc_process_support.py

@@ -103,10 +103,7 @@ async def resolve_execution_environment(
         execution_dependencies = Addresses()
         warn_or_error(
             "2.17.0.dev0",
-            (
-                "Using `dependencies` to specify execution-time dependencies for "
-                "`experimental_shell_command` "
-            ),
+            ("Using `dependencies` to specify execution-time dependencies for `shell_command` "),
             (
                 "To clear this warning, use the `output_dependencies` and `execution_dependencies`"
                 "fields. Set `execution_dependencies=()` if you have no execution-time "

src/python/pants/core/util_rules/wrap_source_intergration_test.py

@@ -11,7 +11,7 @@ def test_synthesized_python_is_included_in_package() -> None:
     sources = {
         "src/BUILD": dedent(
             """\
-            experimental_shell_command(
+            shell_command(
                 name="manufacture_python_code",
                 tools=["touch",],
                 command='echo print\\\\(\\\\"Hello, World!\\\\"\\\\) > hello_world.py',

src/python/pants/notes/2.16.x.md

@@ -46,7 +46,7 @@ available on various target types.
 A new `experimental_test_shell_command` target type has been added to allow defining arbitrary shell commands
 as tests which can be invoked using the `./pants test` goal.
 
-`experimental_shell_command` now supports the `environment` field for running in non-local environments.
+`shell_command` now supports the `environment` field for running in non-local environments.
 
 #### New: Preamble
 

testprojects/wrap_as/BUILD

@@ -1,12 +1,12 @@
 # Copyright 2022 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-experimental_shell_command(
+shell_command(
     name="manufacture_python_code",
     command='echo print\\(\\"Hello, World!\\"\\) > hello_world.py',
     output_files=["hello_world.py"],
 )
 
-experimental_shell_command(
+shell_command(
     name="manufacture_resource",
     command="echo hi > resource.txt",
     output_files=["resource.txt"],