Add 26.04 migration docs

docs/migrations/26-04.md

@@ -0,0 +1,363 @@
+(migrating-26-04-page)=
+
+# Migrating to 26.04 (preview)
+
+This page summarizes the upcoming changes in Nextflow 26.04, which will be released in April 2026.
+
+:::{note}
+This page is a work in progress and will be updated as features are finalized. It should not be considered complete until the 26.04 release.
+:::
+
+## New features
+
+<h3>Module system</h3>
+
+Nextflow now has native support for publishing, installing, running, and including remote modules using the [Nextflow registry](https://registry.nextflow.io/).
+
+The new `module` command can be used to work with remote modules:
+
+```bash
+# Run a module directly
+nextflow module run nf-core/fastqc --meta.id 1 --reads sample1.fastq
+
+# Search for modules in registry
+nextflow module search bwa
+
+# Get info about a module
+nextflow module info nf-core/bwa/mem
+
+# Install a module
+nextflow module install nf-core/bwa/mem
+```
+
+Remotes modules are installed into the `modules` directory of your project. They can be included in scripts by name instead of relative path:
+
+```nextflow
+// before
+include { BWA_MEM } from '../../../modules/nf-core/bwa/mem'
+
+// after
+include { BWA_MEM } from 'nf-core/bwa/mem'
+```
+
+:::{note}
+All [nf-core modules](https://github.com/nf-core/modules) are automatically synced to the registry from GitHub. They are available as `nf-core/<name>` as shown above.
+:::
+
+See {ref}`module-registry` and the {ref}`cli-module` command reference for details.
+
+<h3>Record types</h3>
+
+Records are a new data structure for modeling composite data. They serve as an alternative to tuples -- whereas tuple elements must be accessed by index, record fields are accessed by name. This allows you to model data with meaningful names instead of keeping track of how tuple elements are ordered.
+
+A record can be created using the `record()` function:
+
+```nextflow
+sample = record(
+    id: '1',
+    fastq_1: file('1_1.fastq'),
+    fastq_2: file('1_2.fastq')
+)
+
+println sample.id
+println sample.foo  // error: unrecognized property `foo`
+```
+
+Record types are a way to define custom types for validating records:
+
+```nextflow
+record Sample {
+    id: String
+    fastq_1: Path
+    fastq_2: Path?
+}
+```
+
+While records created with the `record()` function can have any set of fields, record types can be used to specify a minimum set of requirements in a particular context, such as a process, function, or workflow:
+
+```nextflow
+def hello(sample: Sample) {
+    println "Hello sample ${sample.id}!"
+}
+
+workflow {
+    sample1 = record(id: '1', fastq_2: file('1_2.fastq'))
+    hello(sample1) // error: `sample1` is missing `fastq_1` field required by Sample
+
+    sample2 = record(id: '1', fastq_1: file('1_1.fastq'))
+    hello(sample2) // ok
+
+    sample3 = record(id: '1', single_end: true, fastq_1: file('1_1.fastq'))
+    hello(sample3) // also ok
+}
+```
+
+See {ref}`script-records` for details. See {ref}`migrating-static-types` for more information about migrating from tuples to records.
+
+<h3>Static typing (preview)</h3>
+
+:::{note}
+Typed processes and typed workflows require the `nextflow.preview.types` feature flag to be enabled in every script that uses them.
+:::
+
+Nextflow 26.04 brings full support for static typing with {ref}`typed processes <process-typed-page>` and {ref}`typed workflows <workflow-typed-page>`.
+
+Typed processes can now declare record inputs and outputs:
+
+```nextflow
+nextflow.preview.types = true
+
+process FASTQC {
+    input:
+    record(
+        id: String,
+        fastq_1: Path,
+        fastq_2: Path
+    )
+
+    output:
+    record(
+        id: id,
+        fastqc: file('fastqc_logs')
+    )
+
+    script:
+    // ...
+}
+```
+
+Typed workflows can declare typed inputs and outputs, and provide first-class support for static typing in dataflow logic:
+
+```nextflow
+nextflow.preview.types = true
+
+workflow RNASEQ {
+    take:
+    read_pairs_ch: Channel<Sample>
+    transcriptome: Path
+
+    main:
+    index = INDEX(transcriptome)
+    fastqc_ch = FASTQC(read_pairs_ch)
+    quant_ch = QUANT(read_pairs_ch, index)
+    samples_ch = fastqc_ch.join(quant_ch, by: 'id')
+
+    emit:
+    samples: Channel<AlignedSample> = samples_ch
+}
+
+record Sample { /* ... */ }
+record AlignedSample { /* ... */ }
+```
+
+Several operators have been extended to support static typing and records:
+
+- `combine` can now combine records or tuples
+- `groupBy` can group channel values while being statically typed (replaces `groupTuple`)
+- `join` can now join records by matching field
+
+Breaking changes from the {ref}`first preview <static-typing-first-preview>`:
+
+- The syntax for process tuple inputs has been updated:
+
+  ```nextflow
+  // 25.10
+  input:
+  (id, fastq_1, fastq_2): Tuple<String,Path,Path>
+
+  // 26.04
+  input:
+  tuple(id: String, fastq_1: Path, fastq_2: Path)
+  ```
+
+- The method signature for the `stageAs` directive was changed from `(filePattern, value)` to `(value, filePattern)`.
+
+- The `nextflow.preview.types` feature flag must be enabled in order to use type annotations in workflow takes/emits.
+
+See {ref}`migrating-static-types` for more information about migrating to static typing. See {ref}`migrating-static-types-operators` for best practices on using operators with static typing.
+
+## Enhancements
+
+<h3>Strict syntax parser enabled by default</h3>
+
+The {ref}`strict syntax parser <strict-syntax-page>` is now enabled by default. This change brings the rich error checking of `nextflow lint` to `nextflow run`, and makes it easier to adopt new language features.
+
+The legacy parser can be re-enabled by setting the `NXF_SYNTAX_PARSER` environment variable to `v1`.
+
+<h3>Agent logging mode</h3>
+
+Nextflow prints logs in an agent-friendly format when enabled via `NXF_AGENT_MODE=1`:
+
+```console
+$ NXF_AGENT_MODE=1 nextflow run [...]
+[PIPELINE] nf-core/rnaseq 3.14.0 | profile=test,docker
+[WORKDIR] /path/to/work
+[PROCESS b8/623fc3] sayHello (3)
+[PROCESS 5f/761e51] sayHello (2)
+
+[WARN] Task runtime metrics are not reported when using macOS
+
+[ERROR] FASTQC (sample_1)
+exit: 127
+cmd: fastqc --version
+stderr: bash: fastqc: command not found
+workdir: /path/to/work/ab/123456
+
+[SUCCESS] completed=10 failed=0 cached=5
+```
+
+Agent mode provides minimal structured logging for efficient token usage. It is ideal when using agents to run and debug Nextflow runs.
+
+<h3>Multi-revision checkout for pipelines</h3>
+
+Nextflow now checks out pipelines separately by revision when running remote pipelines, allowing you to run multiple revisions of a pipeline at the same time.
+
+Nextflow uses the default branch specified by the Git repository when no revision is specified, instead of defaulting to the `master` branch. Since each revision is checked out separately, using a specific revision doesn't prevent the use of the default branch on subsequent runs.
+
+Because of this update, the `manifest.defaultBranch` config option is no longer needed.
+
+<h3>Load collection-type params automatically from files</h3>
+
+When using the `params` block, collection-type parameters such as `List<Record>` can be loaded automatically from a CSV, JSON, or YAML file. This feature simplifies the loading of samplesheet inputs and allows a pipeline to support multiple structured data formats.
+
+See {ref}`workflow-typed-params` for details. See {ref}`migrating-static-types` for a migration example.
+
+<h3>Print workflow outputs on run completion</h3>
+
+Nextflow prints a summary of the workflow outputs at the end of a run, when the `output` block is defined.
+
+For example, given the following output block:
+
+```nextflow
+workflow {
+    // ...
+}
+
+output {
+    samples {
+        path { sample -> "${sample.id}" }
+        index {
+            path 'samples.csv'
+        }
+    }
+
+    multiqc_report {
+        path 'multiqc_report.html'
+    }
+}
+```
+
+Nextflow prints the following summary:
+
+```console
+$ nextflow -q run main.nf
+Outputs:
+
+  /path/to/results
+
+  samples: samples.csv
+
+  multiqc_report: multiqc_report.html
+```
+
+You can specify `-output-format json` to produce JSON output instead:
+
+```console
+$ nextflow -q run main.nf -output-format json
+{
+    "samples": "/path/to/results/samples.csv",
+    "multiqc_report": "/path/to/results/multiqc_report.html"
+}
+```
+
+The `module run` command prints a summary of the module outputs:
+
+```console
+$ nextflow -q module run nf-core/fastqc --meta.id 1 --reads sample1.fastq -output-format json
+{
+    "html": [
+        {
+            "id": "SRR6357070_1"
+        },
+        "/path/to/results/SRR6357070_1_fastqc.html"
+    ],
+    "zip": [
+        {
+            "id": "SRR6357070_1"
+        },
+        "/path/to/results/SRR6357070_1_fastqc.zip"
+    ]
+}
+```
+
+See the {ref}`cli-run` command reference for details.
+
+<h3>New <code>-project-dir</code> option for <code>lint</code> command</h3>
+
+The `lint` command now has a `-project-dir` option, which can be used to specify the project root when linting files.
+
+For example, given the following project structure:
+
+```
+├── lib
+│   └── Utils.groovy
+├── modules
+│   └── nf-core
+│       └── fastqc
+│           ├── main.nf
+│           └── ...
+├── workflows
+│   └── rnaseq.nf
+├── main.nf
+└── nextflow.config
+```
+
+You can specify `-project-dir` when linting from a location other than the project root:
+
+```bash
+cd workflows
+nextflow lint -project-dir ../ rnaseq.nf
+```
+
+This option allows the linter to resolve remote module includes and Groovy code in the `lib` directory:
+
+```nextflow
+// workflows/rnaseq.nf
+
+include { FASTQC } from 'nf-core/fastqc'
+
+workflow RNASEQ {
+    // ...
+
+    Utils.validateInput( /* ... */ )
+
+    // ...
+}
+```
+
+See the {ref}`cli-lint` command reference for details.
+
+## Breaking changes
+
+- The {ref}`strict syntax parser <strict-syntax-page>` is now enabled by default. The legacy parser can be enabled by setting the `NXF_SYNTAX_PARSER` environment variable to `v1`.
+
+## Deprecations
+
+- The `nextflow.enable.strict` feature flag is deprecated. It is not needed when {ref}`strict syntax <strict-syntax-page>` is enabled.
+
+- The `manifest.defaultBranch` config option is deprecated. Nextflow can automatically detect the default branch when using a remote pipeline.
+
+- The Path `listFiles()` method is deprecated. Use `listDirectory()` instead.
+
+- Several operators have been deprecated. See {ref}`operator-page` for details.
+
+## Miscellaneous
+
+- New config option: `aws.batch.forceGlacierTransfer`
+- New config option: `executor.onlyJobState`
+- New config option: `google.batch.installOpsAgent`
+- New config option: `google.batch.logsPath`
+- New config option: `wave.build.conda.baseImage`
+- New config option: `wave.build.template`
+- New standard library function: `listDirectory()`
+- Support Java 26

docs/migrations/index.md

@@ -7,6 +7,7 @@ This section covers important information for migrating between Nextflow version
 ```{toctree}
 :maxdepth: 1
 
+26-04
 25-10
 25-04
 24-10