Deprecate process when section in favor of process.when config setting

[bentsherman]

The process when section is an anti-pattern when used in place of explicit workflow logic (an if statement or filter operator). Its remaining use case is temporarily disabling a process at runtime, which is how nf-core uses it:

when:
task.ext.when == null || task.ext.when

Setting when in the process config already worked by accident: unknown config settings are copied into the process config, and TaskConfig.getWhenGuard() evaluates them like a when: section. This PR makes that official and deprecates the when section.

Changes

• Add when to the process config scope spec (not to process directives or the agent scope), so it can only be set in config
• Stop warning about when as an unknown directive in ProcessConfigBuilder
• Warn about the deprecated when section in ScriptAstBuilder (typed and legacy processes), replacing the type checker soft error and the paranoid warning
• Docs: new "Disabling processes" config section, deprecation notes in the process and strict syntax pages (including nf-core migration), moved the when section from Discouraged to Deprecated on the deprecations page, 26.10 migration notes

when can be a boolean or a closure that is evaluated per task, with access to task inputs and params:

process {
    withName: 'FASTQC' {
        when = { meta.id != params.skip_sample }
    }
}

Caveat (documented): disabling a process that emits dataflow values produces empty dataflow values, which will likely break the run.

Compatibility

Setting when in the process config already works in Nextflow 24.10 (tested with 24.10.0), including closures and withName selectors that override a when section in the script. Older versions just print an Unknown directive `when` warning for each process. Pipelines can therefore migrate from ext.when to when without raising their minimum Nextflow version.

[netlify]

✅ Deploy Preview for nextflow-docs canceled.

Name	Link
🔨 Latest commit	0adc9b3
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs/deploys/6ac7fa882dcc1900070288d9

[jorgee]

Looks good. I added a couple of doc suggestions inline, to make clear that when both the when section and the process.when config setting are set, the config setting wins.

One question: the deprecation warning for the when section is only shown by nextflow lint and the editor. nextflow run doesn't print it. Would it be worth also warning at run time, or would that be too noisy, since most nf-core pipelines would get one warning per module?

[bentsherman]

Thanks, I added your suggestions while cleaning up the PR.

Indeed, we only want to show a lint warning because it is intended for developers rather than users. So users won't get flooded with warnings, but developers will see it when they lint their pipeline code.