Publish advisories

Advisories are structured, long-lived notices for significant technical issues in pipelines, modules, subworkflows or configs. Advisories should focus on clarity, relevance, and practical value: if the issue is significant enough that users could waste hours chasing it down, it’s probably worth an advisory. Think of it as a way to save others from stepping into the same pothole.

Who can issue an advisory?

In short: anyone can create one. While in practice they’ll most often be written by maintainers of the affected pipelines or modules, the process is open to contributors who spot an issue worth sharing broadly.

What to publish?

Some examples of issues that should be communicated as advisories include:

  • A newly discovered issue that leads to incorrect results in a module or pipeline. This includes bugs in tools bundled within a specific pipeline version.
  • Known regressions that occur with certain parameter combinations.
  • Incompatibilities between a particular pipeline version and a specific Nextflow version.
  • Security vulnerabilities or other issues affecting a dependency or container image.
  • Problems with executors (e.g., SLURM, AWS Batch) that require special considerations.

These are the kinds of problems where a clear, structured advisory can help users avoid pitfalls and stay informed, but there’s no rigid rule on when to publish one — if you’ve identified a problem, understand its cause, possibly even have a solid workaround or fix, that’s a great time.

Where does one put the content?

To create an advisory, begin by forking the nf-core website repository and adding a new Markdown (or MDX) file in the sites/main-site/src/content/advisory directory. You can for example use the source file for the process shell advisory as a template.

The main body of the advisory is written in regular Markdown. Use it to clearly describe the issue, and if possible, include recommended workarounds or resolutions. You’re free to structure this section as you see fit — just aim for clarity and usefulness, and a constructive tone. Advisories are not the place for blame or finger-pointing. Bugs happen, and the goal here is to help the community learn and adapt, not to single out individuals or teams. You can also add references to related GitHub issues, pull requests, or Slack discussions to provide additional context.

While the narrative section is flexible, the real strength of advisories lies in their structured format: making them searchable, categorizable, and directly linkable to affected versions. To enable that structure, each advisory must begin with a frontmatter block, a YAML-style header enclosed by ---. This is where you define all the key metadata, such as affected pipelines, dependencies, and severity. If you’ve ever written a module’s meta.yaml, you’ll feel right at home here 😉.

Severity
High
Published on
3 December 2024
Type
Known Regression Incompatibility
Category
Pipelines
Configuration
Technical Details
Nextflow: 25.04.0 25.04.1 25.04.2
Executors: SLURM AWS Batch Local
Dependencies: Docker Singularity
Affected Pipelines
pipeline
workflow
Affected Subworkflows
subworkflow/example
Affected Modules
module/example
another/module
Affected Configuration
config-item
Reported by
Github user nf-core-bot
@nf-core-bot
Reviewed by
Github user MatthiasZepper
@MatthiasZepper
The technical details section of an advisory, showing structured metadata including severity, affected components, and version information.

Frontmatter reference

Find a reference for the supported categories and valid specifications below - you can find the same summary also on the website’s README.

---
# Required fields
title: "Advisory Title"
subtitle: "Brief description of the issue"
category:
    "pipelines" # Which part of the nf-core ecosystem this advisory affects
    # Options: ["pipelines", "modules", "subworkflows", "configuration"]
    # Can be single value or array for multi-category issues
type:
    "known_regression" # What kind of issue this is - helps users understand impact
    # Options: ["known_regression", "incompatibility", "security",
    #          "performance", "data_corruption", "other"]
    # Can be single value or array for issues with multiple aspects
severity:
    "high" # How serious this issue is for users
    # Options: ["low", "medium", "high", "critical"]
    # Note: "critical" is only allowed for security issues
publishedDate: "2024-01-15" # When this advisory was published (YYYY-MM-DD format)
 
# Optional reporter information - who discovered and reported this issue
reporter: # Can be null, array of usernames, or array of objects with details
    - "username" # Simple GitHub username
    - name: "Full Name" # Object with full name and GitHub username
      github: "username"
 
# Optional reviewer information - who reviewed and validated this advisory
reviewer: # Array of usernames or objects with reviewer details
    - "reviewer-username"
 
# Category-specific fields - REQUIRED if the corresponding category is specified above
pipelines: # List of affected pipelines (required if category includes "pipelines")
    - "pipeline-name" # Simple list of pipeline names
    # OR specify affected versions:
    - name: "pipeline-name" # Pipeline name with specific version information
      versions: ["1.0.0", "1.1.0"] # Semantic version numbers of affected releases
 
modules: # List of affected modules (required if category includes "modules")
    - "module_name"
    - "another/module"
 
subworkflows: # List of affected subworkflows (required if category includes "subworkflows")
    - "subworkflow/name"
 
configuration: # Configuration aspects affected (required if category includes "configuration")
    - "config-item"
 
# Optional details
nextflowVersions: # Specific Nextflow versions that exhibit this issue
    - "23.04.0" # Use semantic versioning format
    - "23.10.1"
 
nextflowExecutors: # Workflow execution environments where this issue occurs
    - "SLURM" # Specific executor names
    - "AWS Batch"
    - "Local"
 
softwareDependencies: # Container systems or package managers affected by this issue
    - "Docker" # Simple list of affected systems
    # OR specify affected versions:
    - name: "Singularity" # System name with version details
      versions: ["3.8.0", "3.9.0"] # Specific versions that have the issue
    # Available: ["Apptainer", "Charliecloud", "Docker", "Podman", "Sarus",
    #            "Shifter", "Singularity", "Conda", "Spack", "Wave"]
 
# Optional references - links to related information, bug reports, documentation
references:
    - title: "GitHub Issue" # Short title describing what this link is
      description: "Original bug report" # Longer explanation of what you'll find at this link
      url: "https://github.com/nf-core/pipeline/issues/123" # The actual URL
    - title: "Slack discussion"
      description: "Original reporting on the nf-core slack"
      url: "https://nfcore.slack.com/archives/C03EZ806PFT/p1730391850337429"
---
On this page