Contributing to existing pipelines

nf-core pipelines are community-driven bioinformatics workflows that enable reproducible analyses across research groups. Contributing to existing pipelines helps improve functionality, fix bugs, and add new features that benefit the entire community.

This guide explains how to contribute code to existing nf-core pipelines. Whether you’re adding a new feature, fixing a bug, or improving documentation, the nf-core community welcomes your contributions.

Contribute to an existing pipeline

1. Check if someone is already working on your idea:

   Check the pipeline repository for:

   • Open issues to see if your idea has been discussed
   • Open pull requests to avoid duplicating work

2. Create an issue to let others know you’re working on it:

   • Use a clear title that describes your contribution
   • Describe what you plan to add or change
   • Add yourself to the Assignees

3. Fork the pipeline repository to your GitHub account and clone it locally:

   git clone https://github.com/<github_username>/<pipeline_name>.git
   cd <pipeline_name>
   git remote add upstream https://github.com/nf-core/<pipeline_name>.git
   git checkout -b <branch_name>

   Note

   Replace <github_username>, <pipeline_name>, and <branch_name> with appropriate values.

Use descriptive branch names like add-fastqc-module or fix-memory-issue. :::

1. Make your changes following the pipeline conventions:

   • Make changes on the dev branch
   • Follow the pipeline’s existing code style and structure
   • Add or update tests as needed
   • Update documentation to reflect your changes

2. Add new parameters to the pipeline schema:

   If you added new parameters, update the JSON schema:

   nf-core pipelines schema build

   Note

   This command updates nextflow_schema.json with your new parameters and provides an interactive interface to add descriptions and validation rules.

3. Test your changes locally:

   nextflow run . -profile debug,test,docker --outdir <OUTDIR>

   Tip

   The debug profile provides warnings about process selectors and other debug information that can help identify issues.

4. Run linting checks to ensure code quality:

   nf-core pipelines lint .

   Note

   Address any failures or warnings.

Follow the listed URLs for documentation on how to fix specific issues. :::

1. Commit and push your changes with a clear message:

   git add .
   git commit -m "Add feature: <description>"
   git push origin <branch_name>

   Tip

   Before creating a pull request, sync your branch with upstream to apply your changes on top of the latest updates:

   git pull --rebase upstream dev

2. Submit a pull request against the dev branch:

   Go to the pipeline repository on GitHub and create a pull request:

   • Use the pull request template provided
   • Reference the issue you created
   • Describe what you changed and why
   • Explain how you tested your changes
   • Include example commands or screenshots if helpful

3. Address review feedback

   Note

   The nf-core maintainers and automated tests will review your contribution.

Common feedback includes:

• Code style improvements
• Additional or updated tests
• Documentation clarifications
• Linting fixes
• Pipeline-specific conventions

Pull requests are typically fully reviewed when automated tests pass. :::

1. When approved, a maintainer will merge your pull request

Automated testing

When you create a pull request, GitHub Actions automatically runs tests to ensure code quality and functionality. Pull requests are typically fully reviewed when these tests pass.

Lint tests

All nf-core pipelines must adhere to a set of guidelines. The linting tool checks that your code follows these standards:

nf-core pipelines lint <pipeline-directory>

The tool verifies:

• Code structure and organization
• Documentation completeness
• Configuration file formatting
• Pipeline metadata

Pipeline tests

Each nf-core pipeline includes a minimal test dataset. GitHub Actions runs the pipeline on this data to verify successful execution:

• Tests run with the latest version of Nextflow
• Tests run with the minimum required Nextflow version specified in the pipeline

If tests fail, review the GitHub Actions logs to identify and fix issues before requesting review.

Patching bugs in releases

If a release contains a critical bug that requires immediate fixing:

1. Create a new patch branch based on upstream/master
2. Fix the bug and bump the patch version (X.Y.Z+1)
3. Submit a pull request to master (not dev) to directly resolve the bug

This workflow bypasses the normal development cycle for urgent production fixes.

Pipeline contribution conventions

Follow these conventions to ensure code quality and consistency across nf-core pipelines.

Adding a new process

When adding a new process to a pipeline:

1. Define the input channel from the expected previous process
2. Write the process block following pipeline conventions
3. Define output channels as needed
4. Add new parameters to nextflow.config with sensible defaults
5. Update nextflow_schema.json using nf-core pipelines schema build
6. Add validation for all relevant parameters
7. Test locally to verify the new process works correctly
8. Add test commands to .github/workflow/ci.yml if applicable
9. Update MultiQC configuration in assets/multiqc_config.yml:
   • Add relevant file suffixes and cleanup rules
   • Ensure module plots appear in the correct order
10. Document output files in docs/output.md with MultiQC screenshots if relevant

Parameters

Define parameters with default values in nextflow.config under the params scope:

params {
    my_parameter = 'default_value'
}

After adding parameters, update the schema:

nf-core pipelines schema build

This adds your parameters to nextflow_schema.json with descriptions and validation rules.

Resource requirements

Define process resource requirements (CPUs, memory, time) in conf/base.config using withLabel: selectors:

withLabel: process_low {
    cpus = 2
    memory = 4.GB
}

Use standardized labels from the nf-core pipeline template. Reference resources dynamically in process blocks:

script:
"""
tool --threads ${task.cpus} --memory ${task.memory}
"""

Channel naming

Use consistent naming schemes for channels:

• Initial process output: ch_output_from_<process>
• Intermediate and terminal channels: ch_<previousprocess>_for_<nextprocess>

Example:

ch_output_from_fastqc
ch_fastqc_for_multiqc

Nextflow version requirements

If you use new Nextflow features, update the minimum required version:

nf-core pipelines bump-version --nextflow . [min_nf_version]

Images and figures

Follow the nf-core style guidelines for pipeline diagrams, workflow images, and other visual documentation.

Additional resources

If you need assistance:

• Ask in the pipeline-specific channel on nf-core Slack (e.g., #<pipeline-name>)
• Consult the pipeline’s documentation and usage guides
• Review existing code in the pipeline for examples
• Check the nf-core contributing guidelines

The nf-core community is here to help. Don’t hesitate to ask questions.