maxulysse/nf-core-utils-migration

nf-core-utils 마이그레이션

nf-core 파이프라인을 벤더드 유틸리티 코드에서 nf-core-utils 플러그인(및 직접 nf-schema 호출)으로 한 플러그인 버전씩 이동하며, 추가 설정으로 파이프라인을 실행하더라도 중단되지 않도록 합니다.

모듈 meta.yml에서 빌드한 도구 인용 정보(citationsOnTheFly, publication 블록)는 아래 Citations 섹션에서 별도 PR로 다루며, 마이그레이션 PR에 포함하지 않습니다. nf-test 인프라(tests/lib, 스냅샷 헬퍼, nft-utils)는 범위 밖입니다. 이를 발견하면 후속 작업으로 언급하고, 마이그레이션 PR에 포함하지 마십시오.

시작하기 전에 읽어볼 만한 참조 마이그레이션: nf-core/rnavar#233 (벤더드 서브워크플로우 최초 제거), nf-core/rnavar#252 (게놈 및 버전 헬퍼), nf-core/seqinspector#241 및 nf-core/rnaseq#1977 (전체 교체). gh pr diff <n> -R nf-core/<repo> 명령어로 가져오십시오.

1. 이미 마이그레이션된 항목 인벤토리

마이그레이션은 여러 단계로 진행됩니다. 각 플러그인 릴리스는 더 많은 헬퍼를 흡수하므로, "이미 nf-core-utils를 사용한다"고 말하는 파이프라인도 종종 플러그인 함수를 가리는 로컬 사본을 가지고 있습니다. 사용자의 시작 상태 설명이 최신이라고 가정하지 마십시오. 확인:

ls subworkflows/nf-core/ | grep '^utils_'                      # 아직 존재하는 벤더드 서브워크플로우
grep -n '"utils_' modules.json                                  # modules.json 내 해당 항목
grep -rn "from 'plugin/" main.nf workflows subworkflows/local   # 플러그인에서 이미 가져온 항목
grep -n "^def " main.nf workflows/*.nf subworkflows/local/utils_*/main.nf   # 로컬 헬퍼 정의
grep -n "id '" nextflow.config                                  # 현재 플러그인 고정

모든 로컬 def를 대상 플러그인 버전이 내보내는 함수(2단계)와 비교하십시오. 플러그인 내보내기와 이름이 같은 로컬 def는 삭제 대상입니다. 파이프라인 특화 로직(사용자 정의 검증, 도구 목록, 파이프라인 특화 요약 텍스트)을 가진 def는 유지하십시오.

2. 고정할 플러그인 버전의 시그니처 읽기

플러그인 API는 버전 간에 변경되며, 다른 파이프라인의 diff는 다른 버전을 대상으로 할 수 있습니다. 기억에 의존하지 말고 캐시된 플러그인에서 실제 시그니처를 읽으십시오:

nextflow plugin install nf-core-utils@<ver>      # 또는 파이프라인을 한 번 실행하면 플러그인이 ~/.nextflow/plugins/에 위치함
P=~/.nextflow/plugins/nf-core-utils-<ver>
grep Plugin-Requires $P/classes/META-INF/MANIFEST.MF            # 최소 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>

Plugin-Requires가 manifest.nextflowVersion보다 높으면, manifest.nextflowVersion, .github/workflows/nf-test.yml의 최소 NXF_VER, README 배지를 같은 PR에서 올리십시오.

이전 버전을 의도적으로 유지할 때(예: nf-schema 2.x는 3.x가 paramsSummaryLog(Map, WorkflowMetadata)를 삭제함), 다음 메이저에서 깨질 호출 지점을 PR 설명에 나열하여 후속 작업이 보이도록 하십시오.

3. 헬퍼 교체

references/function-map.md를 사용하여 각 벤더드 서브워크플로우와 로컬 헬퍼를 호출 단위로 교체하십시오. nextflow.config에 플러그인 고정:

plugins {
    id 'nf-core-utils@<ver>' // nf-core-utils는 Nextflow 파이프라인을 위한 유틸리티 모음입니다
    id 'nf-schema@<ver>'     // 파라미터 검증 및 샘플 시트로부터 입력 채널 생성
}

그런 다음 subworkflows/nf-core/utils_nextflow_pipeline, utils_nfcore_pipeline, utils_nfschema_plugin(및 해당 tests/ 디렉토리)과 그 modules.json 항목을 삭제하십시오. modules.json의 일관성을 위해 nf-core subworkflows remove <name>을 선호하십시오; 수동으로 modules.json을 편집해야 한다면, 이후에 npx -y prettier@3 --write modules.json을 실행하십시오. JSON 덤프는 installed_by 배열을 손상시킬 수 있습니다.

4. nextflow.config 이외의 모든 설정에 플러그인 고정

실행 시 설정(Seqera Platform의 .github/workflows/awsfulltest.yml/awstest.yml의 nextflow_config, Tower 설정, 기관 -c 설정)에 있는 plugins {} 블록은 파이프라인 자체의 plugins {} 블록을 병합하지 않고 대체합니다. 파이프라인이 include { ... } from 'plugin/<name>'으로 가져오지만 해당 블록에 고정되지 않은 플러그인은 최신 릴리스로 해석되어, 새로운 메이저가 출시되면 깨집니다.

nextflow.config의 버전을 이러한 모든 블록에 정확히 반복하고, 블록 자체를 위해 추가하는 플러그인도 포함하십시오:

nextflow_config: |
  plugins {
    id 'nf-core-utils@<nextflow.config와 동일한 버전>'
    id 'nf-schema@<nextflow.config와 동일한 버전>'
    id '[email protected]'
  }

고정 버전이 일치하는지 확인:

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

모든 플러그인이 단일 버전으로 나타나야 합니다.

5. 증거로 플러그인 실패 진단

Missing process or function X(...) -- Did you mean 'X' instead?는 X라는 함수는 존재하지만 일치하는 인수 오버로드가 없음을 의미합니다. 오타가 아니라 플러그인 버전 불일치로 읽으십시오: 실제로 로드된 버전을 찾은 다음, 그 시그니처(2단계)를 호출 지점과 비교하십시오.

변경하기 전에 어떤 버전이 로드되었는지 확인:

• 메가테스트/플랫폼 실행: gh run list -R nf-core/<pipeline> -w "nf-core AWS full size tests", gh run view <id> --log, 또는 nf-slack이 보낸 Slack 메시지, 플랫폼 실행 로그 확인. Downloading plugin <name>@<ver> / Starting plugin <name>@<ver>를 찾으십시오.
• 설정 오버라이드 로컬 재현: 외부 plugins {} 블록만 포함하는 설정으로 실행하고 로그 확인.

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

이러한 출처가 모두 비어 있을 때만 사용자에게 로그를 요청하십시오.

6. 검증

보고하기 전에 자신이 발생시킨 실패와 이미 dev에 있던 실패를 분리하십시오: 깨끗한 작업 트리에서 실패한 테스트나 린트를 다시 실행하십시오.

git worktree add /tmp/dev-baseline origin/dev
(cd /tmp/dev-baseline && <동일한 테스트 또는 린트 명령어>)
git worktree remove --force /tmp/dev-baseline

적어도 다음을 실행:

• nextflow lint main.nf workflows subworkflows/local (엄격한 문법)
• nf-core pipelines lint
• 파이프라인 nf-tests, NXF_VER을 파이프라인의 최소 Nextflow 버전으로 설정
• nextflow run . --help, --help_full, --version (이 경로는 일찍 종료되며 UTILS_NFSCHEMA_PLUGIN/UTILS_NEXTFLOW_PIPELINE 인라인 시 쉽게 깨짐)

인용 (별도 PR)

헬퍼가 플러그인에서 제공되면, MultiQC 방법 설명은 citationsOnTheFly(nf-core-utils 0.7.0 이상)와 각 모듈 meta.yml의 tools: 항목을 사용하여 실제로 실행된 도구를 인용할 수 있습니다. 이를 마이그레이션 PR 밖에 두십시오: 많은 모듈 파일을 건드리고, 파이프라인 전체의 스냅샷을 변경하며, 사용자가 결정해야 할 저작권 속성 결정이 포함됩니다.

시작하기 전에 references/citations.md를 읽으십시오. 요약:

1. channel.topic("versions").collect(flat: false)를 citationsOnTheFly에 연결하고, 수집 후 실행되는 도구(MultiQC)를 추가로 전달합니다.
2. No citation metadata found 메시지를 기록하고 스냅샷을 깨뜨릴 도구를 예측합니다. 실제 도구를 인용하고, 일반 유틸리티는 정확히 하나씩 건너뜁니다.
3. 사용자와 인용 메타데이터 위치를 협의합니다: 업스트림 nf-core/modules, 모듈 패치, 또는 로컬 오버레이 파일.
4. 모든 DOI, 저자 목록 및 제목은 Crossref/PubMed에서 가져오고, 절대 기억에 의존하지 마십시오. 모듈의 인용 논문을 교체하기 전에 문의하십시오.
5. 모듈 패치는 meta.yml로 제한하고, 렌더링된 Tools used 텍스트는 테스트 실행 결과를 확인하십시오.

주의사항

• 스냅샷: 플러그인의 softwareVersionsToYAML은 튜플 버전을 따옴표로 묶은 문자열로 유지하므로, 숫자 버전(1.21 대신 "1.21")을 보유한 스냅샷이 여러 파일에서 변경됩니다. 이는 예상된 동작이며, 따옴표만 변경되었는지 확인하십시오.
• 튜플과 빈 스트림이 생존하도록 버전을 수집: rnaseq#1977은 .toList()로 수집하고, 레거시 versions.yml 출력을 entry instanceof Path ? entry.text : entry를 통해 읽어 원격 작업 디렉토리가 계속 작동하도록 합니다.
• 벤더드 UTILS_NFSCHEMA_PLUGIN 호출이 이에 의존했다면 validateParameters(cast_cli_params: false)를 유지하십시오. 인라인 전에 이전 호출을 확인하십시오.
• getWorkflowVersion()은 매니페스트를 읽습니다. 파이프라인이 이전에 git 접미사를 출력했다면 workflow.manifest.version, workflow.commitId를 전달하십시오.
• 플러그인의 methodsDescriptionText는 String 경로를 받으므로, Path가 아닌 file.toString()을 전달하십시오.
• nf-core YAML 파일은 때때로 키를 따옴표로 묶습니다(- "gatk4":). 정규식으로 대량 편집할 때는 따옴표가 있거나 없는 키를 모두 매칭한 다음, 편집된 파일 수를 예상 목록과 비교하십시오.
• 모듈을 패치해야 하는 경우, nf-core modules patch는 modules/nf-core/<m>/tests/ 아래의 gitignore된 파일도 diff하므로, 먼저 고정된 SHA로 재설정(git -C ~/.config/nfcore/nf-core/modules show <git_sha>:modules/nf-core/<m>/<file>)하고 각 .diff가 변경하려는 파일만 명명하는지 확인하십시오.

PR

• 먼저 PR을 열고, 실제 PR 번호로 CHANGELOG 항목을 작성하십시오. 다음 번호를 추측하면 다른 기여자와 경합을 일으킵니다.
• CHANGELOG: Changed 아래 항목, PR이 플러그인 고정을 수정하는 경우 Fixed 항목, 그리고 이전 및 새 버전이 포함된 Dependencies - Nextflow plugins 테이블.
• PR 설명: 이전/이후 플러그인 버전, 고정한 모든 외부 plugins {} 블록, 플러그인으로 이동한 헬퍼와 로컬에 남은 헬퍼(및 그 이유), 후속 작업(다음 메이저 호출 지점, 인용, 테스트 인프라).