Migración de nf-core-utils

¿Qué hace Migración de nf-core-utils?

Mueve un pipeline nf-core del código de utilidades vendido al plugin nf-core-utils (más llamadas directas a nf-schema), una versión del plugin a la vez, sin romper ejecuciones que lancen el pipeline con configuraciones adicionales.

Las citas de herramientas construidas a partir de meta.yml de los módulos (citationsOnTheFly, bloques publication) se cubren en la sección de Citas más abajo, como un PR separado después de la migración. La infraestructura de nf-test (tests/lib, ayudantes de snapshot, nft-utils) está fuera del alcance: menciónala como seguimiento si la ves, no la incluyas en el PR de migración.

Migraciones de referencia que vale la pena leer antes de empezar: nf-core/rnavar#233 (primera eliminación de subworkflows vendidos), nf-core/rnavar#252 (ayudantes de genoma y versiones), nf-core/seqinspector#241 y nf-core/rnaseq#1977 (reemplazo completo). Recupéralas con gh pr diff <n> -R nf-core/<repo>.

1. Inventario de lo que ya está migrado

La migración ocurre por etapas: cada versión del plugin absorbe más ayudantes, por lo que un pipeline que "ya usa nf-core-utils" a menudo todavía carga copias locales que ocultan funciones del plugin. No asumas que la descripción del usuario sobre el estado inicial está actualizada. Verifica:

ls subworkflows/nf-core/ | grep '^utils_'                      # subworkflows vendidos aún presentes
grep -n '"utils_' modules.json                                  # sus entradas en modules.json
grep -rn "from 'plugin/" main.nf workflows subworkflows/local   # qué ya se importa desde plugins
grep -n "^def " main.nf workflows/*.nf subworkflows/local/utils_*/main.nf   # definiciones de ayudantes locales
grep -n "id '" nextflow.config                                  # pines actuales de plugins

Compara cada def local con las funciones que exporta la versión del plugin de destino (paso 2). Una definición local con el mismo nombre que una exportación del plugin es candidata a eliminación. Mantén las definiciones que contengan lógica específica del pipeline (validación personalizada, listas de herramientas, texto de resumen específico del pipeline).

2. Leer las firmas de la versión del plugin que se va a fijar

Las APIs de los plugins cambian entre versiones, y los diffs de otros pipelines pueden apuntar a una versión diferente. Lee las firmas reales del plugin en caché, no de memoria:

nextflow plugin install nf-core-utils@<ver>      # o ejecuta el pipeline una vez; los plugins caen en ~/.nextflow/plugins/
P=~/.nextflow/plugins/nf-core-utils-<ver>
grep Plugin-Requires $P/classes/META-INF/MANIFEST.MF            # versión mínima de 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>

Si Plugin-Requires es superior a manifest.nextflowVersion, actualiza manifest.nextflowVersion, la NXF_VER mínima en .github/workflows/nf-test.yml y la insignia del README en el mismo PR.

Cuando mantengas deliberadamente un pin antiguo (por ejemplo, nf-schema 2.x porque 3.x elimina paramsSummaryLog(Map, WorkflowMetadata)), enumera los sitios de llamada que se romperían en la siguiente versión principal en la descripción del PR para que el seguimiento sea visible.

3. Reemplazar los ayudantes

Usa references/function-map.md para el reemplazo llamada por llamada de cada subworkflow vendido y ayudante local. Fija el plugin en nextflow.config:

plugins {
    id 'nf-core-utils@<ver>' // nf-core-utils es una colección de utilidades para pipelines de Nextflow
    id 'nf-schema@<ver>'     // Validación de parámetros del pipeline y creación de un canal de entrada a partir de una hoja de muestras
}

Luego elimina subworkflows/nf-core/utils_nextflow_pipeline, utils_nfcore_pipeline y utils_nfschema_plugin (incluyendo sus tests/) y sus entradas en modules.json. Prefiere nf-core subworkflows remove <name> para que modules.json se mantenga consistente; si debes editar modules.json a mano, ejecuta npx -y prettier@3 --write modules.json después, porque un volcado JSON explota los arreglos installed_by.

4. Fijar plugins en cada configuración que no sea nextflow.config

Un bloque plugins {} en una configuración de lanzamiento (el nextflow_config de Seqera Platform en .github/workflows/awsfulltest.yml / awstest.yml, configuraciones de Tower, configuraciones institucionales -c) reemplaza el bloque plugins {} del pipeline en lugar de fusionarse con él. Cualquier plugin que el pipeline importe con include { ... } from 'plugin/<name>' pero que no esté fijado en ese bloque se resuelve entonces a la última versión, lo que se rompe tan pronto como se publique una nueva versión principal.

Repite exactamente las versiones de nextflow.config en cada uno de esos bloques, más el plugin que el bloque añada por sí mismo:

nextflow_config: |
  plugins {
    id 'nf-core-utils@<misma que en nextflow.config>'
    id 'nf-schema@<misma que en nextflow.config>'
    id '[email protected]'
  }

Verifica que los pines coincidan:

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

Cada plugin debe aparecer con una única versión.

5. Diagnosticar fallos de plugin a partir de evidencia

Missing process or function X(...) -- Did you mean 'X' instead? significa que existe una función llamada X pero ninguna sobrecarga coincide con los argumentos. Interprétalo como una discrepancia de versión del plugin, no un error tipográfico: encuentra qué versión se cargó realmente, luego compara sus firmas (paso 2) con el sitio de llamada.

Confirma qué versión se cargó antes de cambiar nada:

• Ejecución de megatest / Platform: gh run list -R nf-core/<pipeline> -w "nf-core AWS full size tests" y gh run view <id> --log, o el mensaje de Slack publicado por nf-slack, o el log de ejecución de Platform. Busca Downloading plugin <name>@<ver> / Starting plugin <name>@<ver>.
• Reproducción local de una anulación de configuración: ejecuta con una configuración que solo contenga el bloque plugins {} externo y verifica el 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

Pide los logs al usuario solo si estas fuentes no aportan nada.

6. Verificación

Separa los fallos que tú causaste de los fallos ya presentes en dev antes de informar de cualquiera: vuelve a ejecutar la prueba o el linting que falla en un árbol de trabajo limpio.

git worktree add /tmp/dev-baseline origin/dev
(cd /tmp/dev-baseline && <mismo comando de test o lint>)
git worktree remove --force /tmp/dev-baseline

Ejecuta al menos:

• nextflow lint main.nf workflows subworkflows/local (sintaxis estricta)
• nf-core pipelines lint
• los nf-tests del pipeline, con NXF_VER fijado a la versión mínima de Nextflow del pipeline
• nextflow run . --help, --help_full, y --version, ya que estas rutas salen temprano y son fáciles de romper al incluir en línea UTILS_NFSCHEMA_PLUGIN / UTILS_NEXTFLOW_PIPELINE

Citas (PR separado)

Una vez que los ayudantes provengan del plugin, la descripción de métodos de MultiQC puede citar las herramientas que realmente se ejecutaron, usando citationsOnTheFly (nf-core-utils 0.7.0 o posterior) y las entradas tools: de cada meta.yml de módulo. Mantén esto fuera del PR de migración: toca muchos archivos de módulos, cambia snapshots en todo el pipeline e implica decisiones de atribución que el usuario debe tomar.

Lee references/citations.md antes de empezar. En resumen:

1. Conecta channel.topic("versions").collect(flat: false) en citationsOnTheFly, pasando las herramientas que se ejecutan después del collect (MultiQC) como extras.
2. Predice qué herramientas registrarán No citation metadata found y romperán snapshots; cita herramientas reales, ignora utilidades genéricas una entrada exacta a la vez.
3. Acuerda con el usuario dónde vive los metadatos de citas: upstream nf-core/modules, parches de módulos, o un archivo de superposición local.
4. Toma cada DOI, lista de autores y título de Crossref / PubMed, nunca de memoria, y pregunta antes de reemplazar el artículo citado de un módulo.
5. Limita los parches de módulos a meta.yml, y lee el texto renderizado Tools used desde una ejecución de prueba.

Gotchas

• Snapshots: softwareVersionsToYAML del plugin mantiene las versiones de tuplas como cadenas entrecomilladas, por lo que los snapshots que contenían versiones numéricas (1.21 en lugar de "1.21") cambian en muchos archivos. Esto es esperado; verifica que solo haya cambiado el entrecomillado.
• Recolecta versiones para que las tuplas y los streams vacíos sobrevivan: rnaseq#1977 recolecta con .toList() y lee las emisiones versions.yml heredadas mediante entry instanceof Path ? entry.text : entry para que los directorios de trabajo remotos sigan funcionando.
• Mantén validateParameters(cast_cli_params: false) si la llamada vendida UTILS_NFSCHEMA_PLUGIN dependía de ello; verifica la llamada antigua antes de incluirla en línea.
• getWorkflowVersion() lee el manifiesto; pasa workflow.manifest.version, workflow.commitId si el pipeline imprimía el sufijo git antes.
• methodsDescriptionText del plugin toma una ruta String, así que pasa file.toString(), no el Path.
• Los archivos YAML de nf-core a veces entrecomillan claves (- "gatk4":). Las ediciones masivas con expresiones regulares deben coincidir con claves entrecomilladas y no entrecomilladas, luego contar los archivos editados contra la lista esperada.
• Si un módulo debe ser parcheado, nf-core modules patch diff también archivos ignorados por git bajo modules/nf-core/<m>/tests/, así que restablécelos primero al SHA fijado (git -C ~/.config/nfcore/nf-core/modules show <git_sha>:modules/nf-core/<m>/<file>) y verifica que cada .diff solo nombre los archivos que pretendías cambiar.

PR

• Abre el PR primero, luego escribe las entradas del CHANGELOG con el número real del PR. Adivinar el siguiente número compite con otros contribuidores.
• CHANGELOG: una entrada bajo Changed, una entrada Fixed si el PR corrige un pin de plugin, y una tabla Dependencies - Nextflow plugins con las versiones antiguas y nuevas.
• Descripción del PR: versiones de plugin antes/después, cada bloque plugins {} externo que fijaste, qué ayudantes se movieron al plugin y cuáles se quedaron locales (y por qué), seguimientos (sitios de llamada de la siguiente versión principal, citas, infraestructura de prueba).