Migração do nf-core-utils

O que Migração do nf-core-utils faz?

Mova um pipeline nf-core do código utilitário embutido para o plugin nf-core-utils (mais chamadas diretas ao nf-schema), uma versão de plugin por vez, sem quebrar execuções que iniciam o pipeline com configurações extras.

Citações de ferramentas construídas a partir do meta.yml dos módulos (blocos citationsOnTheFly, publication) são cobertas na seção Citações abaixo, como um PR separado após a migração. A infraestrutura de testes nf-test (tests/lib, snapshot helpers, nft-utils) está fora do escopo: mencione-a como um acompanhamento se a vir, não a inclua no PR de migração.

Migrações de referência que valem a pena ler antes de começar: nf-core/rnavar#233 (primeira remoção de subworkflows embutidos), nf-core/rnavar#252 (helpers de genoma e versões), nf-core/seqinspector#241 e nf-core/rnaseq#1977 (substituição completa). Obtenha-os com gh pr diff <n> -R nf-core/<repo>.

1. Inventariar o que já foi migrado

A migração acontece em estágios: cada lançamento do plugin absorve mais helpers, então um pipeline que "já usa nf-core-utils" muitas vezes ainda carrega cópias locais que sombreiam funções do plugin. Não presuma que a descrição do estado inicial fornecida pelo usuário está atualizada. Verifique:

ls subworkflows/nf-core/ | grep '^utils_'                      # subworkflows embutidos ainda presentes
grep -n '"utils_' modules.json                                  # suas entradas em modules.json
grep -rn "from 'plugin/" main.nf workflows subworkflows/local   # o que já é importado dos plugins
grep -n "^def " main.nf workflows/*.nf subworkflows/local/utils_*/main.nf   # definições locais de helpers
grep -n "id '" nextflow.config                                  # pins atuais dos plugins

Compare cada def local com as funções que a versão alvo do plugin exporta (passo 2). Uma definição local com o mesmo nome de uma exportação do plugin é candidata a remoção. Mantenha definições que contêm lógica específica do pipeline (validação personalizada, listas de ferramentas, texto de resumo específico do pipeline).

2. Ler as assinaturas da versão do plugin que será fixada

As APIs dos plugins mudam entre versões, e os diffs de outros pipelines podem ter como alvo uma versão diferente. Leia as assinaturas reais do plugin em cache, não da memória:

nextflow plugin install nf-core-utils@<ver>      # ou execute o pipeline uma vez; os plugins vão para ~/.nextflow/plugins/
P=~/.nextflow/plugins/nf-core-utils-<ver>
grep Plugin-Requires $P/classes/META-INF/MANIFEST.MF            # versão mínima do Nextflow
python3 -c "import json;[print(x['spec']['name'],[p['type'] for p in x['spec']['parameters']]) for x in json.load(open('$P/classes/META-INF/spec.json'))['definitions'] if x['type']=='Function']"
javap -cp $P/classes nfcore.plugin.NfUtilsExtension | grep <function>
javap -cp ~/.nextflow/plugins/nf-schema-<ver>/classes nextflow.validation.ValidationExtension | grep <function>

Se Plugin-Requires for maior que manifest.nextflowVersion, atualize manifest.nextflowVersion, a variável mínima NXF_VER em .github/workflows/nf-test.yml e o badge do README no mesmo PR.

Quando você mantém um pin antigo propositalmente (por exemplo, nf-schema 2.x porque o 3.x remove paramsSummaryLog(Map, WorkflowMetadata)), liste os locais de chamada que quebrariam na próxima versão principal na descrição do PR para que o acompanhamento fique visível.

3. Substituir os helpers

Use references/function-map.md para a substituição chamada por chamada de cada subworkflow embutido e helper local. Fixe o plugin no nextflow.config:

plugins {
    id 'nf-core-utils@<ver>' // nf-core-utils é uma coleção de utilitários para pipelines Nextflow
    id 'nf-schema@<ver>'     // Validação de parâmetros do pipeline e criação de um canal de entrada a partir de uma planilha de amostras
}

Em seguida, exclua subworkflows/nf-core/utils_nextflow_pipeline, utils_nfcore_pipeline e utils_nfschema_plugin (incluindo seus tests/) e suas entradas em modules.json. Prefira nf-core subworkflows remove <nome> para que modules.json permaneça consistente; se precisar editar modules.json manualmente, execute npx -y prettier@3 --write modules.json depois, pois um dump JSON explode os arrays installed_by.

4. Fixar plugins em todos os arquivos de configuração que não sejam o nextflow.config

Um bloco plugins {} em uma configuração em tempo de execução (o nextflow_config do Seqera Platform em .github/workflows/awsfulltest.yml / awstest.yml, configs do Tower, configs institucionais -c) substitui o bloco plugins {} do próprio pipeline em vez de mesclar com ele. Qualquer plugin que o pipeline importe com include { ... } from 'plugin/<nome>' mas que não esteja fixado nesse bloco resolve para o lançamento mais recente, o que quebra assim que uma nova versão principal é lançada.

Repita exatamente as versões do nextflow.config em cada um desses blocos, mais qualquer plugin que o bloco adicione para si:

nextflow_config: |
  plugins {
    id 'nf-core-utils@<mesma versão do nextflow.config>'
    id 'nf-schema@<mesma versão do nextflow.config>'
    id '[email protected]'
  }

Verifique se os pins concordam:

grep -rhoE "id '(nf-core-utils|nf-schema)@[^']+'" nextflow.config .github/workflows/ | sort | uniq -c

Cada plugin deve aparecer com uma única versão.

5. Diagnosticar falhas de plugin a partir de evidências

Missing process or function X(...) -- Did you mean 'X' instead? significa que uma função chamada X existe, mas nenhuma sobrecarga corresponde aos argumentos. Leia como uma incompatibilidade de versão do plugin, não um erro de digitação: descubra qual versão realmente foi carregada e compare suas assinaturas (passo 2) com o local da chamada.

Confirme qual versão foi carregada antes de alterar qualquer coisa:

• Execução de megateste / Platform: gh run list -R nf-core/<pipeline> -w "nf-core AWS full size tests" e gh run view <id> --log, ou a mensagem do Slack enviada pelo nf-slack, ou o log da execução no Platform. Procure por Downloading plugin <name>@<ver> / Starting plugin <name>@<ver>.
• Reprodução local de uma sobrescrita de configuração: execute com uma config que contenha apenas o bloco plugins {} externo e verifique o log.

printf "plugins {\n  id '[email protected]'\n}\n" > /tmp/override.config
nextflow run . -profile test,docker --outdir /tmp/out -c /tmp/override.config 2>&1 | head -40
grep -E "plugin (nf-schema|nf-core-utils)@" .nextflow.log

Peça logs ao usuário somente depois que essas fontes não retornarem nada.

6. Verificar

Separe falhas que você causou de falhas já presentes no dev antes de relatar qualquer uma: reexecute o teste ou lint com falha em uma árvore de trabalho limpa.

git worktree add /tmp/dev-baseline origin/dev
(cd /tmp/dev-baseline && <mesmo comando de teste ou lint>)
git worktree remove --force /tmp/dev-baseline

Execute pelo menos:

• nextflow lint main.nf workflows subworkflows/local (sintaxe estrita)
• nf-core pipelines lint
• os nf-tests do pipeline, com NXF_VER definido para a versão mínima do Nextflow do pipeline
• nextflow run . --help, --help_full e --version, já que esses caminhos saem mais cedo e são fáceis de quebrar ao embutir UTILS_NFSCHEMA_PLUGIN / UTILS_NEXTFLOW_PIPELINE

Citações (PR separado)

Depois que os helpers vierem do plugin, a descrição dos métodos do MultiQC pode citar as ferramentas que realmente foram executadas, usando citationsOnTheFly (nf-core-utils 0.7.0 ou posterior) e as entradas tools: de cada meta.yml do módulo. Mantenha isso fora do PR de migração: ele toca em muitos arquivos de módulo, altera snapshots em todo o pipeline e envolve decisões de atribuição que o usuário deve tomar.

Leia references/citations.md antes de começar. Em resumo:

1. Conecte channel.topic("versions").collect(flat: false) no citationsOnTheFly, passando ferramentas que executam após o collect (MultiQC) como extras.
2. Preveja quais ferramentas registrarão No citation metadata found e quebrarão snapshots; cite ferramentas reais, ignore utilitários genéricos uma entrada exata por vez.
3. Combine com o usuário onde os metadados de citação ficam: nf-core/modules upstream, patches de módulo ou um arquivo de sobreposição local.
4. Tire cada DOI, lista de autores e título do Crossref / PubMed, nunca da memória, e pergunte antes de substituir um artigo citado de um módulo.
5. Mantenha os patches de módulo limitados a meta.yml e leia o texto renderizado Tools used de uma execução de teste.

Armadilhas

• Snapshots: softwareVersionsToYAML do plugin mantém versões de tupla como strings entre aspas, então snapshots que continham versões numéricas (1.21 em vez de "1.21") mudam em muitos arquivos. Isso é esperado; verifique se apenas as aspas mudaram.
• Colete versões para que tuplas e streams vazios sobrevivam: rnaseq#1977 coleta com .toList() e lê emissões legadas de versions.yml via entry instanceof Path ? entry.text : entry para que diretórios de trabalho remotos continuem funcionando.
• Mantenha validateParameters(cast_cli_params: false) se a chamada embutida de UTILS_NFSCHEMA_PLUGIN dependia disso; verifique a chamada antiga antes de embutir.
• getWorkflowVersion() lê o manifesto; passe workflow.manifest.version, workflow.commitId se o pipeline imprimia o sufixo git antes.
• methodsDescriptionText do plugin aceita um caminho String, então passe file.toString(), não o Path.
• Arquivos YAML do nf-core às vezes colocam chaves entre aspas (- "gatk4":). Edições em massa com regex devem corresponder a chaves com e sem aspas e, em seguida, contar os arquivos editados em relação à lista esperada.
• Se um módulo precisar ser corrigido, nf-core modules patch faz diff de arquivos ignorados pelo git sob modules/nf-core/<m>/tests/ também, então redefina-os para o SHA fixado primeiro (git -C ~/.config/nfcore/nf-core/modules show <git_sha>:modules/nf-core/<m>/<file>) e verifique se cada .diff nomeia apenas os arquivos que você pretendia alterar.

PR

• Abra o PR primeiro, depois escreva as entradas do CHANGELOG com o número real do PR. Adivinhar o próximo número compete com outros contribuidores.
• CHANGELOG: uma entrada em Changed, uma entrada Fixed se o PR corrigir um pin de plugin e uma tabela Dependencies - Nextflow plugins com versões antigas e novas.
• Descrição do PR: versões dos plugins antes/depois, cada bloco plugins {} externo que você fixou, quais helpers foram movidos para o plugin e quais permaneceram locais (e por quê), acompanhamentos (locais de chamada da próxima versão principal, citações, infraestrutura de testes).