Improve static types migration docs (#6544)

Signed-off-by: Ben Sherman <[email protected]>

Author: bentsherman

docs/conf.py

@@ -384,9 +384,8 @@ class NextflowLexer(RegexLexer):
             (r'/\*.*?\*/', Comment.Multiline),
             # keywords: go before method names to avoid lexing "throw new XYZ"
             # as a method signature
-            (r'(assert|catch|else|'
-             r'if|instanceof|new|return|throw|try|in|as)\b',
-             Keyword),
+            (r'(assert|catch|else|if|instanceof|new|return|throw|try|in|as)\b', Keyword),
+            (r'(channel|log)', Name.Namespace),
             # method names
             (r'^(\s*(?:[a-zA-Z_][\w.\[\]]*\s+)+?)'  # return arguments
              r'('
@@ -397,9 +396,8 @@ class NextflowLexer(RegexLexer):
              r'(\s*)(\()',                          # signature start
              bygroups(using(this), Name.Function, Whitespace, Operator)),
             (r'@[a-zA-Z_][\w.]*', Name.Decorator),
-            (r'(def|enum|include|from|output|process|workflow)\b', Keyword.Declaration),
-            (r'(boolean|byte|char|double|float|int|long|short|void)\b',
-             Keyword.Type),
+            (r'(def|enum|include|from|output|params|process|workflow)\b', Keyword.Declaration),
+            (r'(boolean|byte|char|double|float|int|long|short|void)\b', Keyword.Type),
             (r'(true|false|null)\b', Keyword.Constant),
             (r'""".*?"""', String.Double),
             (r"'''.*?'''", String.Single),

docs/migrations/25-10.md

@@ -138,8 +138,14 @@ def x_opt: String? = null
 
 In the type system, queue channels are represented as `Channel`, while value channels are represented as `Value`. To make the terminology clearer and more concise, queue channels are now called *dataflow channels* (or simply *channels*), and value channels are now called *dataflow values*. See {ref}`dataflow-page` for more information.
 
-:::{note}
-Nextflow supports Groovy-style type annotations using the `<type> <name>` syntax, but this approach is deprecated in {ref}`strict syntax <strict-syntax-page>`. While Groovy-style annotations remain valid for functions and local variables, the language server and `nextflow lint` automatically convert them to Nextflow-style annotations during code formatting.
+Groovy-style type annotations (e.g., `String x`) are still supported for functions and local variables. However, the language server and `nextflow lint` will automatically convert them to Nextflow-style annotations during code formatting.
+
+:::{warning}
+Since Nextflow-style type annotations are new in Nextflow 25.10, formatting code with Groovy-style type annotations will make it incompatible with previous versions of Nextflow. If you need your code to remain compatible with versions prior to 25.10, run the formatter with Nextflow 25.04:
+
+```bash
+NXF_VER=25.04.8 nextflow lint -format .
+```
 :::
 
 See {ref}`migrating-static-types` for details.

docs/process.md

@@ -678,6 +678,8 @@ In the above example, the `tuple` input consists of the value `x` and the file `
 
 A `tuple` definition may contain any of the following qualifiers, as previously described: `val`, `env`, `path` and `stdin`. Files specified with the `path` qualifier are treated exactly the same as standalone `path` inputs.
 
+(process-input-each)=
+
 ### Input repeaters (`each`)
 
 The `each` qualifier allows you to repeat the execution of a process for each item in a collection, each time a new value is received. For example:
@@ -735,7 +737,7 @@ When multiple repeaters are defined, the process is executed for each *combinati
 :::
 
 :::{note}
-Input repeaters do not support tuples. Use the {ref}`operator-combine` or {ref}`operator-cross` operator to combine the repeated input with the other inputs to produce all of the desired input combinations.
+Input repeaters do not support tuples. Use the {ref}`operator-combine` operator to combine the repeated input with the other inputs to produce all of the desired input combinations.
 :::
 
 (process-multiple-inputs)=

docs/reference/cli.md

@@ -942,6 +942,14 @@ Lint and format all files in the current directory (and subdirectories) and use
 $ nextflow lint -format -spaces 2 .
 ```
 
+:::{note}
+Formatting code with the `lint` command in Nextflow 25.10 or later may make your code incompatible with previous versions of Nextflow. If you need your code to remain compatible with versions prior to 25.10, run the formatter with Nextflow 25.04:
+
+```bash
+NXF_VER=25.04.8 nextflow lint -format .
+```
+:::
+
 (cli-list)=
 
 ### `list`

docs/reference/operator.md

@@ -6,9 +6,6 @@
 
 ## branch
 
-:::{versionadded} 19.08.0-edge
-:::
-
 *Returns: multiple channels*
 
 The `branch` operator forwards each item from a source channel to one of multiple output channels, based on a selection criteria.
@@ -63,6 +60,10 @@ The `branchCriteria()` method can be used to create a branch criteria as a varia
 
 ## buffer
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: channel*
 
 The `buffer` operator collects items from a source channel into subsets and emits each subset separately.
@@ -133,6 +134,10 @@ See also: [collate](#collate)
 
 ## collate
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: channel*
 
 The `collate` operator collects items from a source channel into groups of *N* items.
@@ -360,7 +365,9 @@ For example:
 :language: console
 ```
 
-See also: [mix](#mix)
+:::{tip}
+As a best practice, use [`mix`](#mix) instead of `concat`. The `mix` operator does not wait for each source channel to emit all values before processing the next one.
+:::
 
 (operator-count)=
 
@@ -473,6 +480,10 @@ See also: [combine](#combine)
 
 ## distinct
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: channel*
 
 The `distinct` operator forwards a source channel with *consecutively* repeated items removed, such that each emitted item is different from the preceding one:
@@ -565,6 +576,10 @@ The following example filters a channel using a boolean predicate, which is a {r
 
 ## first
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: dataflow value*
 
 The `first` operator emits the first item in a source channel, or the first item that matches a condition. The condition can be a {ref}`regular expression<script-regexp>`, a type qualifier (i.e. Java class), or a boolean predicate. For example:
@@ -619,7 +634,9 @@ The `flatten` operator flattens each item from a source channel that is a list o
 
 As shown in the above example, deeply nested collections are also flattened.
 
-See also: [flatMap](#flatmap)
+:::{tip}
+As a best practice, use [`flatMap`](#flatmap) instead of `flatten`. The `flatMap` operator only flattens one level and has a well-defined return type.
+:::
 
 (operator-grouptuple)=
 
@@ -629,7 +646,7 @@ See also: [flatMap](#flatmap)
 
 The `groupTuple` operator collects lists (i.e. *tuples*) from a source channel into groups based on a grouping key. A new tuple is emitted for each distinct key.
 
-To be more precise, the operator transforms a sequence of tuples like *(K, V, W, ..)* into a sequence of tuples like *(K, list(V), list(W), ..)*.
+To be more precise, the operator transforms a sequence of tuples like *(K, V1, V2, ..)* into a sequence of tuples like *(K, list(V1), list(V2), ..)*.
 
 For example:
 
@@ -673,13 +690,10 @@ Available options:
 : The required number of items for each group. When a group reaches the required size, it is emitted.
 
 `sort`
-: Defines the sorting criteria for the grouped items. Can be one of the following values:
-
-  - `false`: No sorting is applied (default).
-  - `true`: Order the grouped items by the item's natural ordering i.e. numerical for number, lexicographic for string, etc. See the [Java documentation](http://docs.oracle.com/javase/tutorial/collections/interfaces/order.html) for more information.
-  - `'hash'`: Order the grouped items by the hash number associated to each entry.
-  - `'deep'`: Similar to the previous, but the hash number is created on actual entries content e.g. when the item is a file, the hash is created on the actual file content.
-  - A custom sorting criteria used to order the nested list elements of each tuple. It can be a {ref}`Closure <script-closure>` or a [Comparator](http://docs.oracle.com/javase/7/docs/api/java/util/Comparator.html) object.
+: Defines the sorting criteria for the grouped items.
+: :::{warning}
+  The `sort` option is discouraged because it can lead to inconsistent sorting when there are multiple groups. Perform sorting separately (e.g., in a subsequent `map` operation) to ensure correct results.
+  :::
 
 (operator-ifempty)=
 
@@ -717,7 +731,7 @@ See also: {ref}`channel-empty` channel factory
 
 The `join` operator emits the inner product of two source channels using a matching key.
 
-To be more precise, the operator transforms a sequence of tuples like *(K, V1, V2, ..)* and *(K, W1, W1, ..)* into a sequence of tuples like *(K, V1, V2, .., W1, W2, ..)*.
+To be more precise, the operator transforms a sequence of tuples like *(K, V1, V2, ..)* and *(K, W1, W2, ..)* into a sequence of tuples like *(K, V1, V2, .., W1, W2, ..)*.
 
 For example:
 
@@ -765,6 +779,10 @@ See also: [combine](#combine), [cross](#cross)
 
 ## last
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: dataflow value*
 
 The `last` operator emits the last item from a source channel:
@@ -837,6 +855,12 @@ The following examples show how to find the longest string in a channel:
 
 ## merge
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+
+Use [combine](#combine) or [join](#join) instead to combine multiple channels in a deterministic way, such as a matching key.
+:::
+
 *Returns: channel*
 
 The `merge` operator joins the items from two or more channels into a new channel:
@@ -865,12 +889,6 @@ The `merge` operator may return a channel or value depending on the inputs:
 
 - If the first argument is a dataflow value, the `merge` operator returns a dataflow value, merging the first value from each input, regardless of whether there are channel inputs with additional values.
 
-:::{danger}
-In general, the use of the `merge` operator is discouraged. Processes and channel operators are not guaranteed to emit items in the order that they were received, as they are executed concurrently. Therefore, if you try to merge output channels from different processes, the resulting channel may be different on each run, which will cause resumed runs to {ref}`not work properly <cache-nondeterministic-inputs>`.
-
-You should always use a matching key (e.g. sample ID) to merge multiple channels, so that they are combined in a deterministic way. For this purpose, you can use the [join](#join) operator.
-:::
-
 (operator-min)=
 
 ## min
@@ -940,9 +958,6 @@ See also: [concat](#concat)
 
 ## multiMap
 
-:::{versionadded} 19.11.0-edge
-:::
-
 *Returns: multiple channels*
 
 The `multiMap` operator applies a set of mapping functions to a source channel, producing a separate output channel for each mapping function.
@@ -985,6 +1000,10 @@ If you use `multiMap` to split a tuple or map into multiple channels, it is reco
 
 ## randomSample
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: channel*
 
 The `randomSample` operator emits a randomly-selected subset of items from a source channel:
@@ -1049,6 +1068,10 @@ Using `set` is semantically equivalent to assigning a variable:
 my_channel = channel.of(10, 20, 30)
 ```
 
+:::{tip}
+As a best practice, use a standard assignment (`=`) instead of `set`. Standard assignments enable more effective {ref}`type checking <preparing-static-types>`.
+:::
+
 See also: [tap](#tap)
 
 (operator-splitcsv)=
@@ -1102,9 +1125,6 @@ Available options:
 `decompress`
 : When `true`, decompress the content using the GZIP format before processing it (default: `false`). Files with the `.gz` extension are decompressed automatically.
 
-`elem`
-: The index of the element to split when the source items are lists or tuples (default: first file object or first element).
-
 `header`
 : When `true`, the first line is used as the columns names (default: `false`). Can also be a list of columns names.
 
@@ -1459,6 +1479,10 @@ An optional {ref}`closure <script-closure>` can be used to transform each item b
 
 ## take
 
+:::{warning}
+This operator depends on the ordering of values in the source channel. It can lead to {ref}`non-deterministic behavior <cache-nondeterministic-inputs>` if used improperly.
+:::
+
 *Returns: channel*
 
 The `take` operator takes the first *N* items from a source channel:
@@ -1491,7 +1515,9 @@ The `tap` operator assigns a source channel to a variable, and emits the source
 :language: console
 ```
 
-See also: [set](#set)
+:::{tip}
+As a best practice, use a standard assignment (`=`) instead of `tap`. Standard assignments enable more effective {ref}`type checking <preparing-static-types>`.
+:::
 
 ## toInteger
 
@@ -1588,7 +1614,7 @@ See also: [collect](#collect)
 
 The `transpose` operator "transposes" each tuple from a source channel by flattening any nested list in each tuple, emitting each nested item separately.
 
-To be more precise, the operator transforms a sequence of tuples like *(K, list(V), list(W), ..)* into a sequence of tuples like *(K, V, W, ..)*.
+To be more precise, the operator transforms a sequence of tuples like *(K, list(V1), list(V2), ..)* into a sequence of tuples like *(K, V1, V2, ..)*.
 
 For example:
 
@@ -1628,7 +1654,9 @@ Available options:
 `remainder`
 : When `true`, incomplete tuples are emitted with `null` values for missing elements, otherwise they are discarded (default: `false`). 
 
-See also: [groupTuple](#grouptuple)
+:::{tip}
+As a best practice, use [`flatMap`](#flatmap) instead of `transpose`, since `flatMap` has a well-defined return type.
+:::
 
 (operator-unique)=