Deprecate process shell block (#5508)

Signed-off-by: Ben Sherman <[email protected]>
Co-authored-by: Paolo Di Tommaso <[email protected]>

Author: bentsherman

docs/process.md

@@ -212,6 +212,10 @@ Template scripts are generally discouraged due to the caveats described above. T
 
 ### Shell
 
+:::{deprecated} 24.11.0-edge
+Use the `script` block instead. Consider using the {ref}`VS Code extension <vscode-page>`, which provides syntax highlighting and error checking to distinguish Nextflow variables from Bash variables in the process script.
+:::
+
 The `shell` block is a string expression that defines the script that is executed by the process. It is an alternative to the {ref}`process-script` definition with one important difference: it uses the exclamation mark `!` character, instead of the usual dollar `$` character, to denote Nextflow variables.
 
 This way, it is possible to use both Nextflow and Bash variables in the same script without having to escape the latter, which makes process scripts easier to read and maintain. For example:

docs/reference/syntax.md

@@ -187,7 +187,7 @@ process sayHello {
 }
 ```
 
-A process may define additional sections for *directives*, *inputs*, *outputs*, *script*, *shell*, *exec*, and *stub*:
+A process may define additional sections for *directives*, *inputs*, *outputs*, *script*, *exec*, and *stub*:
 
 ```nextflow
 process greet {
@@ -202,7 +202,7 @@ process greet {
     output:
     stdout
 
-    script: // or shell: or exec:
+    script: // or exec:
     """
     echo '${greeting}, ${name}!'
     """
@@ -214,27 +214,17 @@ process greet {
 }
 ```
 
-- A process must define a script, shell, or exec section (see below). All other sections are optional. Directives do not have an explicit section label, but must be defined first.
+- A process must define a script or exec section (see below). All other sections are optional. Directives do not have an explicit section label, but must be defined first.
 
 - The `script:` section label can be omitted only when there are no other sections in the body.
 
 - Sections must be defined in the order shown above, with the exception of the output section, which can also be specified after the script and stub.
 
 Each section may contain one or more statements. For directives, inputs, and outputs, these statements must be [function calls](#function-call). See {ref}`process-reference` for the set of available input qualifiers, output qualifiers, and directives.
 
-The script section can be substituted with a shell or exec section:
+The script section can be substituted with an exec section:
 
 ```nextflow
-process greetShell {
-    input: 
-    val greeting
-
-    shell:
-    '''
-    echo '!{greeting}, ${USER}!'
-    '''
-}
-
 process greetExec {
     input: 
     val greeting
@@ -248,7 +238,7 @@ process greetExec {
 }
 ```
 
-The script, shell, and stub sections must return a string in the same manner as a [function](#function).
+The script and stub sections must return a string in the same manner as a [function](#function).
 
 See {ref}`process-page` for more information on the semantics of each process section.
 
@@ -356,7 +346,7 @@ Variables declared in a function, as well as the parameters of that function, ex
 
 Workflow inputs exist for the entire workflow body. Variables declared in the main section exist for the main, emit, and publish sections. Named outputs are not considered variable declarations and therefore do not have any scope.
 
-Process input variables exist for the entire process body. Variables declared in the process script, shell, exec, and stub sections exist only in their respective section, with one exception -- variables declared without the `def` keyword also exist in the output section.
+Process input variables exist for the entire process body. Variables declared in the process script, exec, and stub sections exist only in their respective section, with one exception -- variables declared without the `def` keyword also exist in the output section.
 
 Variables declared in an if or else branch exist only within that branch:
 
@@ -958,4 +948,5 @@ The following legacy features were excluded from this page because they are depr
 
 - The `addParams` and `params` clauses of include declarations. See {ref}`module-params` for more information.
 - The `when:` section of a process definition. See {ref}`process-when` for more information.
+- The `shell:` section of a process definition. See {ref}`process-shell` for more information.
 - The implicit `it` closure parameter. See {ref}`script-closure` for more information.

docs/vscode.md

@@ -1,3 +1,4 @@
+(vscode-page)=
 
 # VS Code integration
 
@@ -443,6 +444,10 @@ The `each` process input is deprecated. Use the `combine` or `cross` operator to
 
 The process `when` section is deprecated. Use conditional logic, such as an `if` statement or the `filter` operator, to control the process invocation in the calling workflow.
 
+**Process shell section**
+
+The process `shell` section is deprecated. Use the `script` block instead. The VS Code extension provides syntax highlighting and error checking to help distinguish between Nextflow variables and Bash variables.
+
 ### Configuration syntax
 
 See {ref}`config-syntax` for a comprehensive description of the configuration language.

modules/nextflow/src/main/groovy/nextflow/processor/TaskProcessor.groovy

@@ -309,6 +309,8 @@ class TaskProcessor {
         this.ownerScript = script
         this.config = config
         this.taskBody = taskBody
+        if( taskBody.isShell )
+            log.warn "Process ${name} > the `shell` block is deprecated, use `script` instead"
         this.name = name
         this.maxForks = config.maxForks && config.maxForks>0 ? config.maxForks as int : 0
         this.forksCount = maxForks ? new LongAdder() : null