Skip to content

Document reference selection for consuming pipelines - #167

Closed
maxulysse wants to merge 3 commits into
devfrom
docs/reference-selection
Closed

Document reference selection for consuming pipelines#167
maxulysse wants to merge 3 commits into
devfrom
docs/reference-selection

Conversation

@maxulysse

@maxulysse maxulysse commented Oct 24, 2026

Copy link
Copy Markdown
Member

PR checklist

  • This comment contains a description of changes (for why/what changed, see CONTRIBUTING.md)
  • Container version(s) are updated/rebuilt and pin changed software (if needed)
  • CHANGELOG.md is updated
  • nextflow_schema.json is updated (if needed)
  • docs/usage.md is updated (if needed)
  • docs/output.md is updated (if needed)
  • assets/ is updated (if needed)
  • Remove all TODO comments
  • Test this locally and/or on CI (particularly with GPU/singularity tests)
  • For modules: nf-core/modules PR along with basic tests on Linux, macOS and Windows
  • For pipelines: template update at nf-core/tools along with basic tests (stub run on all profiles)

Description

Adds a Reference selection in consuming pipelines section to docs/usage.md, under Asset input after --references_base_path.

The section states the resolution order shared by pipelines that consume these assets: the first source that supplies a usable record wins, a source runs only when the previous ones did not supply fasta, and selecting a datasheet and an iGenomes catalogue entry at once is an error.

This became worth writing after nf-core/bamtofastq#159 received a review asking that the precedence currently living in a code comment be documented. The pattern is meant to be reused across pipelines, so the wording lives here rather than in any one consumer, and each pipeline keeps its own parameter names in its own usage pages. nf-core/bamtofastq documents its chain and links back to https://nf-co.re/references/usage.

Format facts (field names, the placeholder syntax, the schema that validates files) stay in nf-core/references-datasheets, where the data contract lives.

Testing

  • prek passes with the files staged: prettier, trailing-whitespace, end-of-file-fixer, check-for-added-large-files, check-for-merge-conflicts.
  • Documentation only. No Nextflow code changed, so the test suite is unaffected and was not rerun.

@maxulysse
Document reference selection for consuming pipelines
9e5e044 
Describe the shared resolution order in docs/usage.md: the first source
that supplies a usable record wins, each source runs only when the
previous ones did not supply fasta, and selecting a datasheet and a
catalogue entry at once is an error.

Pipeline-specific parameter names stay in each consuming pipeline;
nf-core/bamtofastq documents its own and links here.

Generated by OpenCode
@maxulysse
Merge branch 'dev' into docs/reference-selection
7a7c66b
@github-actions

github-actions Bot commented Oct 24, 2026

Copy link
Copy Markdown

Warning

Newer version of the nf-core template is available.

Your pipeline is using an old version of the nf-core template: 4.1.0.
Please update your pipeline to the latest version.

For more documentation on how to update your pipeline, please see the Synchronisation documentation.

@github-actions

github-actions Bot commented Oct 24, 2026 •
edited
Loading

Copy link
Copy Markdown

nf-core pipelines lint overall result: Passed ✅ ⚠️

Posted for pipeline commit ec235d0

+| ✅ 219 tests passed       |+
#| ❔  12 tests were ignored |#
#| ❔   1 tests had warnings |#
!| ❗   8 tests had warnings |!
Details

❗ Test warnings:

  • files_exist - File not found: .github/workflows/awsfulltest.yml
  • pipeline_todos - TODO string in main.nf: Optionally add in-text citation tools to this list.
  • pipeline_todos - TODO string in main.nf: Optionally add bibliographic entries to this list.
  • pipeline_todos - TODO string in main.nf: Only uncomment below if logic in toolCitationText/toolBibliographyText has been filled!
  • pipeline_todos - TODO string in methods_description_template.yml: #Update the HTML below to your preferred methods description, e.g. add publication citation for this pipeline
  • pipeline_todos - TODO string in base.config: Check the defaults for all processes
  • pipeline_todos - TODO string in usage.md: Add documentation about anything specific to running your pipeline. For general topics, please point to (and add to) the main nf-core website.
  • pipeline_todos - TODO string in output.md: Write this documentation describing your workflow's output

❔ Tests ignored:

❔ Tests fixed:

✅ Tests passed:

Run details

  • nf-core/tools version 4.1.0
  • Run at 2026-10-28 16:05:49

@maxulysse @claude
Clarify per-key reference resolution in usage docs
ec235d0 
Resolution is per key, the datasheet and iGenomes catalogue are one
mutually exclusive step, and the section moves to its own top-level
heading. Drop bamtofastq parameter names in favour of a link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@maxulysse

maxulysse commented Oct 28, 2026

Copy link
Copy Markdown
Member Author

Closing. The shared reference resolution order spans pipelines that release independently, so it will be published as an nf-core website page as part of the consuming-pipeline documentation work, not in this pipeline's docs/usage.md. docs/usage.md stays about running nf-core/references.

@maxulysse maxulysse closed this Oct 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@maxulysse