maxulysse/nf-core-utils-migration

nf-core-utils Migration

Verschiebe eine nf-core-Pipeline von eingebetteten Hilfscode auf das nf-core-utils-Plugin (plus direkte nf-schema-Aufrufe), eine Plugin-Version nach der anderen, ohne dass Läufe mit zusätzlichen Konfigurationen brechen.

Tool-Zitationen, die aus Modul-meta.yml (Blöcke citationsOnTheFly, publication) erstellt werden, sind im Abschnitt Zitationen unten als separater PR nach der Migration abgedeckt. nf-test-Infrastruktur (tests/lib, Snapshot-Helfer, nft-utils) ist nicht Gegenstand: Erwähne sie als Folgeaufgabe, wenn du sie siehst, aber nimm sie nicht in den Migrations-PR auf.

Referenzmigrationen, die es wert sind, vor dem Start gelesen zu werden: nf-core/rnavar#233 (erste Entfernung von eingebetteten Subworkflows), nf-core/rnavar#252 (Genom- und Version-Helfer), nf-core/seqinspector#241 und nf-core/rnaseq#1977 (vollständiger Austausch). Rufe sie mit gh pr diff <n> -R nf-core/<repo> ab.

1. Bestandsaufnahme: Was wurde bereits migriert

Die Migration erfolgt in Stufen: Jede Plugin-Version nimmt mehr Helfer auf, sodass eine Pipeline, die „bereits nf-core-utils verwendet“, oft noch lokale Kopien enthält, die Plugin-Funktionen überschatten. Gehe nicht davon aus, dass die Beschreibung des Startzustands des Benutzers aktuell ist. Überprüfe:

ls subworkflows/nf-core/ | grep '^utils_'                      # eingebettete Subworkflows noch vorhanden
grep -n '"utils_' modules.json                                 # ihre modules.json-Einträge
grep -rn "from 'plugin/" main.nf workflows subworkflows/local   # was wird bereits aus Plugins importiert
grep -n "^def " main.nf workflows/*.nf subworkflows/local/utils_*/main.nf   # lokale Helferdefinitionen
grep -n "id '" nextflow.config                                 # aktuelle Plugin-Pins

Vergleiche jede lokale def mit den Funktionen, die die Ziel-Plugin-Version exportiert (Schritt 2). Eine lokale def mit demselben Namen wie ein Plugin-Export ist ein Kandidat für die Löschung. Behalte defs, die pipelinespezifische Logik enthalten (benutzerdefinierte Validierung, Tool-Listen, pipelinespezifischer Zusammenfassungstext).

2. Signaturen aus der zu pindenden Plugin-Version auslesen

Plugin-APIs ändern sich zwischen Versionen, und die Diffs anderer Pipelines können auf eine andere Version abzielen. Lese die tatsächlichen Signaturen aus dem gecachten Plugin aus, nicht aus dem Gedächtnis:

nextflow plugin install nf-core-utils@<ver>      # oder führe die Pipeline einmal aus; Plugins landen in ~/.nextflow/plugins/
P=~/.nextflow/plugins/nf-core-utils-<ver>
grep Plugin-Requires $P/classes/META-INF/MANIFEST.MF            # minimale Nextflow-Version
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>

Wenn Plugin-Requires über manifest.nextflowVersion liegt, erhöhe manifest.nextflowVersion, die minimale NXF_VER in .github/workflows/nf-test.yml und das README-Abzeichen im selben PR.

Wenn du absichtlich einen älteren Pin beibehältst (z. B. nf-schema 2.x, weil 3.x paramsSummaryLog(Map, WorkflowMetadata) entfernt), liste die Aufrufstellen, die beim nächsten Major brechen würden, in der PR-Beschreibung auf, damit die Folgeaufgabe sichtbar ist.

3. Ersetze die Helfer

Verwende references/function-map.md für den aufrufweisen Austausch jedes eingebetteten Subworkflows und lokalen Helfers. Pinde das Plugin in nextflow.config:

plugins {
    id 'nf-core-utils@<ver>' // nf-core-utils ist eine Sammlung von Hilfsprogrammen für Nextflow-Pipelines
    id 'nf-schema@<ver>'     // Validierung von Pipeline-Parametern und Erstellung eines Input-Channels aus einer Sample-Sheet
}

Lösche dann subworkflows/nf-core/utils_nextflow_pipeline, utils_nfcore_pipeline und utils_nfschema_plugin (einschließlich ihrer tests/) und ihre modules.json-Einträge. Bevorzuge nf-core subworkflows remove <name>, damit modules.json konsistent bleibt; falls du modules.json von Hand bearbeiten musst, führe danach npx -y prettier@3 --write modules.json aus, da ein JSON-Dump die installed_by-Arrays aufbläht.

4. Pinde Plugins in jeder Konfiguration, die nicht nextflow.config ist

Ein plugins {}-Block in einer Laufzeitkonfiguration (der nextflow_configder Seqera-Plattform in.github/workflows/awsfulltest.yml/awstest.yml, Tower-Konfigurationen, institutionelle -c-Konfigurationen) ersetzt den eigenen plugins {}-Block der Pipeline, anstatt sich mit ihm zu vereinen. Jedes Plugin, das die Pipeline mit include { ... } from 'plugin/<name>' importiert, aber in diesem Block nicht gepinnt ist, wird dann auf die neueste Version aufgelöst, was sofort bricht, sobald ein neues Major erscheint.

Wiederhole exakt die Versionen aus nextflow.config in jedem solchen Block, plus das Plugin, das der Block für sich selbst hinzufügt:

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

Überprüfe, ob die Pins übereinstimmen:

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

Jedes Plugin sollte mit einer einzigen Version erscheinen.

5. Plugin-Fehler anhand von Beweisen diagnostizieren

Missing process or function X(...) -- Did you mean 'X' instead? bedeutet, dass eine Funktion namens X existiert, aber keine Überladung zu den Argumenten passt. Betrachte es als Plugin-Versionskonflikt, nicht als Tippfehler: Finde heraus, welche Version tatsächlich geladen wurde, und vergleiche dann ihre Signaturen (Schritt 2) mit der Aufrufstelle.

Bestätige, welche Version geladen wurde, bevor du etwas änderst:

• Megatest / Platform-Lauf: gh run list -R nf-core/<pipeline> -w "nf-core AWS full size tests" und gh run view <id> --log, oder die von nf-slack gepostete Slack-Nachricht, oder das Platform-Laufprotokoll. Suche nach Downloading plugin <name>@<ver> / Starting plugin <name>@<ver>.
• Lokale Reproduktion einer Konfigurationsüberschreibung: Führe mit einer Konfiguration aus, die nur den externen `plugins {}-Block enthält, und prüfe das Protokoll.

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

Frage den Benutzer erst nach Protokollen, wenn diese Quellen nichts ergeben.

6. Verifizieren

Trenne Fehler, die du verursacht hast, von Fehlern, die bereits auf dev vorhanden sind, bevor du einen von beiden meldest: Führe den fehlschlagenden Test oder Lint auf einem sauberen Arbeitsbaum erneut aus.

git worktree add /tmp/dev-baseline origin/dev
(cd /tmp/dev-baseline && <gleicher Test- oder Lint-Befehl>)
git worktree remove --force /tmp/dev-baseline

Führe mindestens aus:

• nextflow lint main.nf workflows subworkflows/local (strenge Syntax)
• nf-core pipelines lint
• die Pipeline-nf-Tests mit NXF_VER gesetzt auf die minimale Nextflow-Version der Pipeline
• nextflow run . --help, --help_full und --version, da diese Pfade früh beenden und leicht brechen, wenn UTILS_NFSCHEMA_PLUGIN / UTILS_NEXTFLOW_PIPELINE inline ersetzt werden

Zitationen (separater PR)

Sobald die Helfer aus dem Plugin kommen, kann die MultiQC-Methodenbeschreibung die tatsächlich ausgeführten Tools mit citationsOnTheFly (nf-core-utils 0.7.0 oder höher) und den tools:-Einträgen jedes Modul-meta.yml zitieren. Halte dies aus dem Migrations-PR heraus: Es betrifft viele Moduldateien, ändert Snapshots pipelineweit und involviert Zitationsentscheidungen, die der Benutzer treffen sollte.

Lies references/citations.md vor dem Start. Kurzgefasst:

1. Verdrahte channel.topic("versions").collect(flat: false) in citationsOnTheFly und übergib Tools, die nach dem Collect (MultiQC) laufen, als Extras.
2. Sage voraus, welche Tools No citation metadata found protokollieren und Snapshots brechen werden; zitiere reale Tools, ignoriere generische Hilfsprogramme Eintrag für Eintrag.
3. Stimme mit dem Benutzer ab, wo die Zitationsmetadaten leben: upstream nf-core/modules, Modul-Patches oder eine lokale Overlay-Datei.
4. Nimm jede DOI, Autorenliste und Titel von Crossref / PubMed, niemals aus dem Gedächtnis, und frage nach, bevor du ein zitiertes Paper eines Moduls ersetzt.
5. Halte Modul-Patches auf meta.yml beschränkt und lies den gerenderten Text Tools used aus einem Testlauf.

Fallstricke

• Snapshots: softwareVersionsToYAML aus dem Plugin behält Tuple-Versionen als quoted Strings, sodass Snapshots, die numerische Versionen enthielten (1.21 statt "1.21"), sich in vielen Dateien ändern. Das ist erwartet; überprüfe, dass sich nur die Anführungszeichen geändert haben.
• Sammle Versionen so, dass Tupel und leere Streams überleben: rnaseq#1977 sammelt mit .toList() und liest Legacy-versions.yml-Ausgaben via entry instanceof Path ? entry.text : entry, sodass entfernte Arbeitsverzeichnisse funktionsfähig bleiben.
• Behalte validateParameters(cast_cli_params: false) bei, wenn der eingebettete UTILS_NFSCHEMA_PLUGIN-Aufruf darauf angewiesen war; überprüfe den alten Aufruf vor dem Inlinen.
• getWorkflowVersion() liest das Manifest; übergib workflow.manifest.version, workflow.commitId, wenn die Pipeline zuvor das Git-Suffix ausgegeben hat.
• methodsDescriptionText aus dem Plugin erwartet einen String-Pfad, übergib also file.toString(), nicht den Path.
• nf-core YAML-Dateien setzen manchmal Schlüssel in Anführungszeichen (- "gatk4":). Bulk-Edits mit Regex müssen quotierte und unquotierte Schlüssel abgleichen und dann die bearbeiteten Dateien mit der erwarteten Liste abgleichen.
• Wenn ein Modul gepatcht werden muss, diffed nf-core modules patch auch gitiggnorierte Dateien unter modules/nf-core/<m>/tests/, setze sie daher zuerst auf den gepinnten SHA zurück (git -C ~/.config/nfcore/nf-core/modules show <git_sha>:modules/nf-core/<m>/<file>) und überprüfe, dass jeder .diff nur die Dateien nennt, die du ändern wolltest.

PR

• Öffne den PR zuerst, schreibe dann die CHANGELOG-Einträge mit der tatsächlichen PR-Nummer. Das Erraten der nächsten Nummer konkurriert mit anderen Beitragenden.
• CHANGELOG: ein Eintrag unter Changed, ein Fixed-Eintrag, wenn der PR einen Plugin-Pin repariert, und eine Tabelle Dependencies - Nextflow plugins mit alten und neuen Versionen.
• PR-Beschreibung: Plugin-Versionen vorher/nachher, jeden externen `plugins {}-Block, den du gepinnt hast, welche Helfer zum Plugin verschoben wurden und welche lokal geblieben sind (und warum), Folgeaufgaben (nächste-Major-Aufrufstellen, Zitationen, Testinfrastruktur).