maxulysse/nf-core-utils-migration

Migration nf-core-utils

Déplacer un pipeline nf-core des utilitaires vendus vers le plugin nf-core-utils (plus des appels directs à nf-schema), une version de plugin à la fois, sans casser les exécutions qui lancent le pipeline avec des configurations supplémentaires.

Les citations d'outils construites à partir du meta.yml des modules (blocs citationsOnTheFly, publication) sont couvertes dans la section Citations ci-dessous, dans une PR séparée après la migration. L'infrastructure nf-test (tests/lib, helpers de snapshot, nft-utils) est hors du périmètre : mentionnez-la comme suivi si vous la voyez, ne l'intégrez pas dans la PR de migration.

Migrations de référence à lire avant de commencer : nf-core/rnavar#233 (première suppression de sous-workflows vendus), nf-core/rnavar#252 (helpers genome et versions), nf-core/seqinspector#241 et nf-core/rnaseq#1977 (remplacement complet). Récupérez-les avec gh pr diff <n> -R nf-core/<repo>.

1. Inventorier ce qui est déjà migré

La migration se fait par étapes : chaque version du plugin absorbe plus de helpers, donc un pipeline qui "utilise déjà nf-core-utils" contient souvent encore des copies locales qui masquent les fonctions du plugin. Ne présumez pas que la description de l'état de départ par l'utilisateur est à jour. Vérifiez :

ls subworkflows/nf-core/ | grep '^utils_'                      # sous-workflows vendus encore présents
grep -n '"utils_' modules.json                                  # leurs entrées modules.json
grep -rn "from 'plugin/" main.nf workflows subworkflows/local   # ce qui est déjà importé des plugins
grep -n "^def " main.nf workflows/*.nf subworkflows/local/utils_*/main.nf   # définitions de helpers locaux
grep -n "id '" nextflow.config                                  # versions actuelles des plugins

Comparez chaque def locale avec les fonctions exportées par la version cible du plugin (étape 2). Une définition locale avec le même nom qu'une exportation du plugin est candidate à la suppression. Conservez les def qui contiennent une logique spécifique au pipeline (validation personnalisée, listes d'outils, texte de résumé spécifique).

2. Lire les signatures de la version du plugin que vous allez épingler

Les API des plugins changent entre versions, et les diffs d'autres pipelines peuvent cibler une version différente. Lisez les vraies signatures depuis le plugin en cache plutôt que de mémoire :

nextflow plugin install nf-core-utils@<ver>      # ou exécutez le pipeline une fois ; les plugins arrivent dans ~/.nextflow/plugins/
P=~/.nextflow/plugins/nf-core-utils-<ver>
grep Plugin-Requires $P/classes/META-INF/MANIFEST.MF            # version minimale 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 est supérieur à manifest.nextflowVersion, augmentez manifest.nextflowVersion, le NXF_VER minimum dans .github/workflows/nf-test.yml, et le badge README dans la même PR.

Lorsque vous conservez intentionnellement une version plus ancienne (par exemple nf-schema 2.x car 3.x supprime paramsSummaryLog(Map, WorkflowMetadata)), listez les sites d'appel qui casseraient lors de la prochaine version majeure dans la description de la PR pour que le suivi soit visible.

3. Remplacer les helpers

Utilisez references/function-map.md pour le remplacement appel par appel de chaque sous-workflow vendu et helper local. Épinglez le plugin dans nextflow.config :

plugins {
    id 'nf-core-utils@<ver>' // nf-core-utils est une collection d'utilitaires pour les pipelines Nextflow
    id 'nf-schema@<ver>'     // Validation des paramètres du pipeline et création d'un canal d'entrée à partir d'une feuille d'échantillons
}

Supprimez ensuite subworkflows/nf-core/utils_nextflow_pipeline, utils_nfcore_pipeline et utils_nfschema_plugin (y compris leurs tests/) ainsi que leurs entrées modules.json. Préférez nf-core subworkflows remove <name> pour que modules.json reste cohérent ; si vous devez éditer modules.json à la main, exécutez npx -y prettier@3 --write modules.json après, car un vidage JSON explosera les tableaux installed_by.

4. Épingler les plugins dans chaque configuration qui n'est pas nextflow.config

Un bloc plugins {} dans une configuration au moment du lancement (le nextflow_config de Seqera Platform dans .github/workflows/awsfulltest.yml / awstest.yml, les configs Tower, les configs institutionnelles -c) remplace le propre bloc plugins {} du pipeline au lieu de fusionner avec lui. Tout plugin que le pipeline importe avec include { ... } from 'plugin/<name>' mais qui n'est pas épinglé dans ce bloc sera alors résolu vers la version la plus récente, ce qui casse dès qu'une nouvelle version majeure est publiée.

Répétez exactement les versions de nextflow.config dans chacun de ces blocs, plus le plugin que le bloc ajoute pour lui-même :

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

Vérifiez que les versions concordent :

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

Chaque plugin doit apparaître avec une seule version.

5. Diagnostiquer les échecs de plugin à partir de preuves

Missing process or function X(...) -- Did you mean 'X' instead? signifie qu'une fonction appelée X existe mais qu'aucune surcharge ne correspond aux arguments. Interprétez cela comme une incompatibilité de version de plugin, pas une faute de frappe : trouvez quelle version a réellement été chargée, puis comparez ses signatures (étape 2) avec le site d'appel.

Confirmez quelle version a été chargée avant de changer quoi que ce soit :

• Méga-test / exécution Platform : gh run list -R nf-core/<pipeline> -w "nf-core AWS full size tests" et gh run view <id> --log, ou le message Slack posté par nf-slack, ou le journal d'exécution Platform. Cherchez Downloading plugin <name>@<ver> / Starting plugin <name>@<ver>.
• Reproduction locale d'un remplacement de configuration : exécutez avec une configuration qui ne contient que le bloc plugins {} externe et vérifiez le journal.

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

Demandez les journaux à l'utilisateur uniquement après que ces sources n'ont rien donné.

6. Vérifier

Séparez les échecs que vous avez causés des échecs déjà présents sur dev avant de signaler l'un ou l'autre : réexécutez le test ou le lint en échec sur un espace de travail propre.

git worktree add /tmp/dev-baseline origin/dev
(cd /tmp/dev-baseline && <même commande de test ou lint>)
git worktree remove --force /tmp/dev-baseline

Exécutez au moins :

• nextflow lint main.nf workflows subworkflows/local (syntaxe stricte)
• nf-core pipelines lint
• les nf-tests du pipeline, avec NXF_VER défini sur la version minimale Nextflow du pipeline
• nextflow run . --help, --help_full, et --version, car ces chemins se terminent tôt et sont faciles à casser lors de l'inlining de UTILS_NFSCHEMA_PLUGIN / UTILS_NEXTFLOW_PIPELINE

Citations (PR séparée)

Une fois que les helpers proviennent du plugin, la description des méthodes MultiQC peut citer les outils qui ont réellement été exécutés, en utilisant citationsOnTheFly (nf-core-utils 0.7.0 ou version ultérieure) et les entrées tools: de chaque meta.yml de module. Gardez cela en dehors de la PR de migration : cela touche de nombreux fichiers de modules, change les snapshots dans tout le pipeline, et implique des décisions d'attribution que l'utilisateur doit prendre.

Lisez references/citations.md avant de commencer. En résumé :

1. Connectez channel.topic("versions").collect(flat: false) dans citationsOnTheFly, en passant les outils qui s'exécutent après le collect (MultiQC) comme extras.
2. Prédisez quels outils enregistreront No citation metadata found et casseront les snapshots ; citez les vrais outils, ignorez les utilitaires génériques une entrée exacte à la fois.
3. Accordez avec l'utilisateur où résident les métadonnées de citation : en amont dans nf-core/modules, dans des correctifs de modules, ou dans un fichier de superposition local.
4. Prenez chaque DOI, liste d'auteurs et titre depuis Crossref / PubMed, jamais de mémoire, et demandez avant de remplacer un article cité d'un module.
5. Limitez les correctifs de modules à meta.yml, et lisez le texte rendu Tools used à partir d'une exécution de test.

Pièges

• Snapshots : softwareVersionsToYAML depuis le plugin conserve les versions de tuples comme des chaînes entre guillemets, donc les snapshots qui contenaient des versions numériques (1.21 au lieu de "1.21") changent dans de nombreux fichiers. C'est attendu ; vérifiez que seul le guillemetage a changé.
• Collectez les versions pour que les tuples et les flux vides survivent : rnaseq#1977 collecte avec .toList() et lit les émissions versions.yml héritées via entry instanceof Path ? entry.text : entry pour que les répertoires de travail distants continuent de fonctionner.
• Conservez validateParameters(cast_cli_params: false) si l'appel vendu UTILS_NFSCHEMA_PLUGIN en dépendait ; vérifiez l'ancien appel avant d'inliner.
• getWorkflowVersion() lit le manifeste ; passez workflow.manifest.version, workflow.commitId si le pipeline imprimait le suffixe git auparavant.
• methodsDescriptionText depuis le plugin prend un chemin String, donc passez file.toString(), pas le Path.
• Les fichiers YAML de nf-core mettent parfois des clés entre guillemets (- "gatk4":). Les modifications en masse avec des regex doivent correspondre aux clés avec et sans guillemets, puis comptez les fichiers modifiés par rapport à la liste attendue.
• Si un module doit être corrigé, nf-core modules patch affiche les différences pour les fichiers sous modules/nf-core/<m>/tests/ même s'ils sont gitignorés, donc réinitialisez-les d'abord au SHA épinglé (git -C ~/.config/nfcore/nf-core/modules show <git_sha>:modules/nf-core/<m>/<file>) et vérifiez que chaque .diff ne nomme que les fichiers que vous vouliez modifier.

PR

• Ouvrez d'abord la PR, puis écrivez les entrées CHANGELOG avec le vrai numéro de PR. Deviner le numéro suivant entre en conflit avec d'autres contributeurs.
• CHANGELOG : une entrée sous Changed, une entrée Fixed si la PR corrige une version de plugin, et un tableau Dependencies - Nextflow plugins avec les anciennes et nouvelles versions.
• Description de la PR : versions des plugins avant/après, chaque bloc plugins {} externe que vous avez épinglé, quels helpers sont passés au plugin et lesquels sont restés locaux (et pourquoi), les suivis (sites d'appel pour la version majeure suivante, citations, infrastructure de test).