Update modules to use topic channels

In this tutorial, we will go through the steps needed to update existing nf-core modules to use the new topic channels feature for version outputs. This will be the main way to update most modules, the only exceptions being modules that use template scripts. Take a look at the template migration chapter for more information on how to update those modules.

Prerequisites

• nf-core tools version 3.5.0 or higher
• A clone of the nf-core/modules repository
• Nextflow version 25.04.0 or higher

Updating standard modules

To update a module to use topic channels for version outputs:

1. Open the modules main.nf file.

2. Identify the code that looks similar to the following:

   cat <<-END_VERSIONS > versions.yml
   "${task.process}":
       <tool1>: \$(tool1 --version)
       <tool2>: \$(tool2 --version)
   END_VERSIONS

3. Remove the versions.yml file from the output block.

4. Add the following outputs for each tool in the module:

   tuple val("${task.process}"), val('<tool1>'), eval('tool1 --version'), emit: versions_tool1, topic: versions

   Update <tool1> and tool1 --version with the tool name and version command. Repeat this for each tool used in the module.

5. Run nf-core modules lint <module_name> --fix to automatically update the meta.yml file with the new topic outputs.

6. Add a type and description field for each field in the versions output. Use the following template:

   versions_<tool>:
     - - ${task.process}:
           type: string
           description: The process the versions were collected from
       - <tool>:
           type: string
           description: The tool name
       - <versions_command>:
           type: string
           description: The version of the tool

   Update <tool>, <versions_command> to the output channel values.

7. Add the topics block to the meta.ymlfile. Ideally, underneath the outputs section:

topics:
  - versions:
      - - process:
            type: string
            description: The process the versions were collected from
        - tool:
            type: string
            description: The tool name
        - version:
            type: string
            description: The version of the tool

1. Update the main.nf.test file to check for the new version outputs.

• If the test runs on all process output (snapshot(process.out).match()), do nothing.
• If the test checks for specific outputs, update it to check for the new version outputs. process.out.versions should be changed to process.out.findAll { key, val -> key.startsWith('versions') }.

1. Run the tests to regenerate the snapshots:

   nf-core modules test <module_name> --update

2. Check that the snapshot is correct and that all versions are being captured correctly. If not, return to step 3 and update any incorrect information in the module.

3. Commit and push your changes to your fork.

4. Open a pull request to the main nf-core/modules repository.

Template migration

Modules that use template scripts for version outputs will need to be updated slightly differently:

1. Open the modules main.nf file.

2. Update the path "versions.yml", emit: versions line to the following:

   path "versions.yml", emit: versions, topic: versions

3. Add the following lines to the meta.yml file underneath the outputs section:

   versions:
     - versions.yml:
         type: file
         description: YAML file containing versions of tools used in the module

4. Commit and push your changes to your fork.

5. Open a pull request to the main nf-core/modules repository.