Linting Errors

This page contains detailed descriptions of the tests done by the nf-core/tools package. Linting errors should show URLs next to any failures that link to the relevant heading below.

Error #1 - File not found / must be removed

nf-core pipelines should adhere to a common file structure for consistency.

The lint test looks for the following required files:

The following files are suggested but not a hard requirement. If they are missing they trigger a warning:

Additionally, the following files must not be present:

Error #2 - Docker file check failed

Pipelines should have a files called Dockerfile in their root directory. The file is used for automated docker image builds. This test checks that the file exists and contains at least the string FROM (Dockerfile).

Error #3 - Licence check failed

nf-core pipelines must ship with an open source MIT licence.

This test fails if the following conditions are not met:

Error #4 - Nextflow config check failed

nf-core pipelines are required to be configured with a minimal set of variable names. This test fails or throws warnings if required variables are not set.

Note: These config variables must be set in nextflow.config or another config file imported from there. Any variables set in nextflow script files (eg. main.nf) are not checked and will be assumed to be missing.

The following variables fail the test if missing:

The following variables throw warnings if missing:

The following variables are depreciated and fail the test if they are still present:

Process-level configuration syntax is checked and fails if uses the old Nextflow syntax, for example: process.$fastqc instead of process withName:'fastqc'.

Error #5 - Continuous Integration configuration

nf-core pipelines must have CI testing with GitHub Actions.

GitHub Actions

There are 3 main GitHub Actions CI test files: ci.yml, linting.yml and branch.yml and they can all be found in the .github/workflows/ directory.

This test will fail if the following requirements are not met in these files:

  1. ci.yml: Contains all the commands required to test the pipeline

    • Must be turned on for push and pull_request:

      on: [push, pull_request]
    • The minimum Nextflow version specified in the pipeline's nextflow.config has to match that defined by nxf_ver in this file:

      jobs:
        test:
          runs-on: ubuntu-18.04
          strategy:
            matrix:
              # Nextflow versions: check pipeline minimum and current latest
              nxf_ver: ['19.10.0', '']
    • The Docker container for the pipeline must be tagged appropriately for:

      • Development pipelines: docker tag nfcore/<pipeline_name>:dev nfcore/<pipeline_name>:dev

      • Released pipelines: docker tag nfcore/<pipeline_name>:dev nfcore/<pipeline_name>:<tag>

        jobs:
          test:
            runs-on: ubuntu-18.04
            steps:
              - name: Pull image
                  run: |
                  docker pull nfcore/<pipeline_name>:dev
                  docker tag nfcore/<pipeline_name>:dev nfcore/<pipeline_name>:1.0.0
  2. linting.yml: Specifies the commands to lint the pipeline repository using nf-core lint and markdownlint

    • Must be turned on for push and pull_request.
    • Must have the command nf-core lint ${GITHUB_WORKSPACE}.
    • Must have the command markdownlint ${GITHUB_WORKSPACE} -c ${GITHUB_WORKSPACE}/.github/markdownlint.yml.
  3. branch.yml: Ensures that pull requests to the protected master branch are coming from the correct branch

    • Must be turned on for pull_request to master.

      on:
        pull_request:
          branches:
          - master
    • Checks that PRs to the protected master branch can only come from an nf-core dev branch or a fork patch branch:

      steps:
        # PRs are only ok if coming from an nf-core `dev` branch or a fork `patch` branch
        - name: Check PRs
          run: |
            { [[ $(git remote get-url origin) == *nf-core/<pipeline_name> ]] && [[ ${GITHUB_HEAD_REF} = "dev" ]]; } || [[ ${GITHUB_HEAD_REF} == "patch" ]]

Error #6 - Repository README.md tests

The README.md files for a project are very important and must meet some requirements:

Error #7 - Pipeline and container version numbers

This test only runs when --release is set or $GITHUB_REF is equal to master

These tests look at process.container and $GITHUB_REF only if they are set.

Error #8 - Conda environment tests

These tests only run when your pipeline has a root file called environment.yml

Each dependency is checked using the Anaconda API service. Dependency sublists are ignored with the exception of - pip: these packages are also checked for pinned version numbers and checked using the PyPI JSON API.

Note that conda dependencies with pinned channels (eg. conda-forge::openjdk) are fine and should be handled by the linting properly.

Each dependency can have the following lint failures and warnings:

NB: Conda package versions should be pinned with one equals sign (toolname=1.1), pip with two (toolname==1.2)

Error #9 - Dockerfile for use with Conda environments

This test only runs if there is both environment.yml and Dockerfile present in the workflow.

If a workflow has a conda environment.yml file (see above), the Dockerfile should use this to create the container. Such Dockerfiles can usually be very short, eg:

FROM nfcore/base:1.7
MAINTAINER Rocky Balboa <your@email.com>
LABEL authors="your@email.com" \
    description="Docker image containing all requirements for the nf-core mypipeline pipeline"

COPY environment.yml /
RUN conda env create -f /environment.yml && conda clean -a
RUN conda env export --name nf-core-mypipeline-1.0 > nf-core-mypipeline-1.0.yml
ENV PATH /opt/conda/envs/nf-core-mypipeline-1.0/bin:$PATH

To enforce this minimal Dockerfile and check for common copy+paste errors, we require that the above template is used. Failures are generated if the FROM, COPY and RUN statements above are not present. These lines must be an exact copy of the above example.

Note that the base nfcore/base image should be tagged to the most recent release. The linting tool compares the tag against the currently installed version.

Additional lines and different metadata can be added without causing the test to fail.

Error #10 - Template TODO statement found

The nf-core workflow template contains a number of comment lines with the following format:

// TODO nf-core: Make some kind of change to the workflow here

This lint test runs through all files in the pipeline and searches for these lines.

Error #11 - Singularity file found

As we are relying on Docker Hub instead of Singularity and all containers are automatically pulled from there, repositories should not have a Singularity file present.

Error #12 - Pipeline name

In order to ensure consistent naming, pipeline names should contain only lower case, alphabetical characters. Otherwise a warning is displayed.