From 7a8d5133446a736971f758777360ef4e2857037b Mon Sep 17 00:00:00 2001 From: Ehsan ESTAJI <71376358+ehsanestaji@users.noreply.github.com> Date: Fri, 3 Jul 2026 20:35:04 +0200 Subject: [PATCH] docs: define workflow readiness path --- README.md | 1 + docs/adoption-plan.md | 38 +++++- docs/workflow-readiness.md | 120 ++++++++++++++++++ examples/nf-core/README.md | 3 + .../modules/local/fastaguard/environment.yml | 5 + examples/snakemake/wrapper/README.md | 3 + examples/snakemake/wrapper/meta.yaml | 19 +++ tests/python/test_adoption_assets.py | 40 ++++++ 8 files changed, 227 insertions(+), 2 deletions(-) create mode 100644 docs/workflow-readiness.md create mode 100644 examples/nf-core/modules/local/fastaguard/environment.yml create mode 100644 examples/snakemake/wrapper/meta.yaml diff --git a/README.md b/README.md index 3dfad92..7b14e13 100644 --- a/README.md +++ b/README.md @@ -316,6 +316,7 @@ FastaGuard catches FASTA-level assembly problems before expensive assembly QC. - [Output contract](docs/output-contract.md) - [Tool landscape](docs/tool-landscape.md) - [Adoption plan](docs/adoption-plan.md) +- [Workflow readiness](docs/workflow-readiness.md) - [LLM and tooling vision](docs/llm-tooling-vision.md) - [Benchmarking](docs/benchmarking.md) - [v0.2 evidence pack](docs/evidence/fastaguard-v0.2-evidence.md) diff --git a/docs/adoption-plan.md b/docs/adoption-plan.md index 69d901e..8f85a67 100644 --- a/docs/adoption-plan.md +++ b/docs/adoption-plan.md @@ -8,7 +8,7 @@ adding many new biological heuristics. Priority: ```text -Bioconda published -> BioContainers available -> MultiQC plugin -> public benchmarks -> upstream workflow examples +Bioconda published -> BioContainers available -> MultiQC plugin -> public benchmarks -> upstream workflow readiness ``` ## Phase 1: Package @@ -65,7 +65,41 @@ Goal: show why FastaGuard is worth adding before expensive tools. Done when the README can show real examples rather than only promises. -## Phase 4: Expand +## Phase 4: Workflow Readiness + +Goal: make local workflow starters credible enough to become upstream +submissions. + +Status: local nf-core-style and Snakemake wrapper-style starters are present, +pinned to the v0.5.0 Bioconda package and BioContainers image, and documented +as starters rather than official upstream submissions. + +Next work: + +- complete nf-core lint and test harness requirements +- complete Snakemake wrapper metadata, pin, and upstream test requirements +- preserve the collect-then-gate pattern so JSON, TSV, HTML, and MultiQC + evidence survives blocking FASTA results +- keep the workflow examples focused on stable FastaGuard contracts instead of + broad biological interpretation + +Detailed checklist: `docs/workflow-readiness.md`. + +## Phase 5: Upstream workflow readiness + +Goal: submit the starter assets upstream once the package, container, examples, +and tests are aligned with current community expectations. + +Done when: + +```text +nf-core module PR ready + Snakemake wrapper PR ready + local evidence-preserving examples verified +``` + +This phase should not claim official upstream status until those PRs are +accepted. + +## Phase 6: Expand Goal: add profiles once the assembly preflight contract is trusted. diff --git a/docs/workflow-readiness.md b/docs/workflow-readiness.md new file mode 100644 index 0000000..b3e7114 --- /dev/null +++ b/docs/workflow-readiness.md @@ -0,0 +1,120 @@ +# Workflow Readiness + +## Current State + +FastaGuard is ready for local workflow use through the published v0.5.0 +Bioconda package and BioContainers image: + +```bash +mamba install -c conda-forge -c bioconda fastaguard=0.5.0 +docker pull quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0 +``` + +The repository includes local starters for: + +- nf-core-style Nextflow modules in `examples/nf-core/` +- Snakemake wrapper-style usage in `examples/snakemake/wrapper/` +- MultiQC custom-content aggregation through `fastaguard_mqc.json` + +These are workflow adoption starters. They are not yet an upstream nf-core module. +They are not yet an official Snakemake wrapper. + +## Integration Pattern + +FastaGuard should run before QUAST, BUSCO, BlobToolKit, CheckM, annotation, or +official submission validators. The default workflow pattern is: + +```text +collect FASTA-level evidence -> apply stop/go policy -> route downstream tools +``` + +For local fail-fast runs, `--gate pipeline` and `--gate submission` write JSON, +TSV, HTML, and MultiQC-compatible evidence before returning a blocking exit +code. Some workflow engines remove failed-job outputs by default, so production +integrations should use a collect-then-gate pattern when evidence preservation +matters. The important contract fields are: + +- `verdict.status` +- `gate.mode` +- `gate.status` +- `gate.blocking_findings` +- `readiness.categories` +- `provenance.input_sha256` + +## nf-core Readiness + +The local module already carries the expected interface shape: + +- input channel: `tuple val(meta), path(fasta)` +- outputs: HTML, JSON, TSV, MultiQC custom-content JSON, and versions metadata +- runtime: `bioconda::fastaguard=0.5.0` +- container: `quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0` + +Before an upstream nf-core module submission, complete this checklist: + +- regenerate or validate the module against the current `nf-core/tools` + template +- run `nf-core modules lint fastaguard` +- run `nf-core modules test fastaguard` +- add nf-test cases for PASS, WARN, FAIL, and invalid FASTA inputs +- assert that `.fastaguard.json`, `.fastaguard.tsv`, `.fastaguard.html`, + `.fastaguard_mqc.json`, and version outputs are produced +- align `meta.yml` with current nf-core channel metadata expectations +- check current nf-core topic channels guidance for version outputs +- document that FastaGuard remains a FASTA preflight gate, not a replacement + for downstream interpretive QC + +The upstream submission should keep the module boring: database-free, pinned to +Bioconda/BioContainers, and focused on stable machine-readable outputs. + +## Snakemake Readiness + +The local wrapper starter already provides: + +- `wrapper.py` +- `environment.yaml` +- `meta.yaml` +- a copy-pasteable `Snakefile` +- outputs for HTML, JSON, TSV, and MultiQC custom-content JSON + +Before an official Snakemake wrapper submission, complete this checklist: + +- generate `environment.linux-64.pin.yaml` from the wrapper environment +- add `test/Snakefile` with tiny FASTA fixtures +- update `test_wrappers.py` so wrapper tests run in the upstream repository +- test PASS, WARN, FAIL, and invalid FASTA behavior +- ensure the wrapper can handle arbitrary input and output paths +- preserve evidence on blocking FASTA results, either through workflow-specific + output handling or a collect-then-gate wrapper pattern + +## Submission Gate Usage + +For repository-preflight workflows, use: + +```bash +fastaguard sample.fa \ + --profile assembly \ + --gate submission \ + --submission-target ncbi \ + --json fastaguard.json \ + --tsv fastaguard.tsv \ + --out fastaguard_report.html \ + --multiqc fastaguard_mqc.json +``` + +This is FASTA-level readiness only. It can identify identifier hazards, +duplicate first-token IDs, high ambiguity, gap-like N runs, and tiny-record +advisories. It does not guarantee repository acceptance and does not replace +NCBI, ENA, DDBJ, NCBI FCS, annotation validation, QUAST, BUSCO, BlobToolKit, or +CheckM. + +## References Checked + +Current upstream expectations were checked on 2026-07-03 against: + +- nf-core modules repository and `nf-core modules lint` workflow: + https://github.com/nf-core/modules +- nf-core topic channels migration guidance: + https://nf-co.re/docs/tutorials/migrate_to_topics/update_modules +- Snakemake wrappers contributing guidance: + https://snakemake-wrappers.readthedocs.io/en/stable/contributing.html diff --git a/examples/nf-core/README.md b/examples/nf-core/README.md index c9d79d4..2677eba 100644 --- a/examples/nf-core/README.md +++ b/examples/nf-core/README.md @@ -2,6 +2,9 @@ This directory is a starter for a local nf-core-style FastaGuard module. It is not yet an upstream nf-core module. +See `../../docs/workflow-readiness.md` for the current upstream readiness +checklist before submitting this starter to nf-core. + Expected input channel: ```nextflow diff --git a/examples/nf-core/modules/local/fastaguard/environment.yml b/examples/nf-core/modules/local/fastaguard/environment.yml new file mode 100644 index 0000000..6786c8e --- /dev/null +++ b/examples/nf-core/modules/local/fastaguard/environment.yml @@ -0,0 +1,5 @@ +channels: + - conda-forge + - bioconda +dependencies: + - bioconda::fastaguard=0.5.0 diff --git a/examples/snakemake/wrapper/README.md b/examples/snakemake/wrapper/README.md index e8231e0..97d9901 100644 --- a/examples/snakemake/wrapper/README.md +++ b/examples/snakemake/wrapper/README.md @@ -2,6 +2,9 @@ This is a local wrapper-style starter for FastaGuard. It assumes `fastaguard` is available on `PATH`. +See `../../../docs/workflow-readiness.md` for the current upstream readiness +checklist before submitting this starter as an official Snakemake wrapper. + Published Bioconda provides v0.5.0: ```bash diff --git a/examples/snakemake/wrapper/meta.yaml b/examples/snakemake/wrapper/meta.yaml new file mode 100644 index 0000000..9914541 --- /dev/null +++ b/examples/snakemake/wrapper/meta.yaml @@ -0,0 +1,19 @@ +name: fastaguard +description: FASTA preflight QC for assembly and submission-readiness workflows. +url: https://github.com/ehsanestaji/FastaGuard +authors: + - FastaGuard contributors +input: + fasta: Assembly FASTA file to validate before downstream QC. +output: + html: Human-readable FastaGuard report. + json: Machine-readable FastaGuard report. + tsv: Tabular FastaGuard summary. + multiqc: MultiQC custom-content JSON. +params: + profile: FastaGuard profile, normally assembly. + gate: FastaGuard gate mode, normally pipeline or submission. + extra: Additional command-line arguments passed to FastaGuard. +notes: > + FastaGuard is a FASTA preflight layer. It should run before downstream + interpretive QC tools and official validators, not replace them. diff --git a/tests/python/test_adoption_assets.py b/tests/python/test_adoption_assets.py index 98db0a7..3159a02 100644 --- a/tests/python/test_adoption_assets.py +++ b/tests/python/test_adoption_assets.py @@ -533,6 +533,46 @@ def test_workflow_docs_reference_bioconda_and_container_status(self): snakemake_readme, ) + def test_workflow_readiness_plan_defines_upstream_submission_path(self): + readme = (ROOT / "README.md").read_text() + adoption = (ROOT / "docs" / "adoption-plan.md").read_text() + readiness = (ROOT / "docs" / "workflow-readiness.md").read_text() + nfcore_readme = (ROOT / "examples" / "nf-core" / "README.md").read_text() + nfcore_environment = ( + ROOT + / "examples" + / "nf-core" + / "modules" + / "local" + / "fastaguard" + / "environment.yml" + ).read_text() + snakemake_readme = ( + ROOT / "examples" / "snakemake" / "wrapper" / "README.md" + ).read_text() + snakemake_meta = ( + ROOT / "examples" / "snakemake" / "wrapper" / "meta.yaml" + ).read_text() + + self.assertIn("[Workflow readiness](docs/workflow-readiness.md)", readme) + self.assertIn("Phase 5: Upstream workflow readiness", adoption) + self.assertIn("not yet an upstream nf-core module", readiness) + self.assertIn("not yet an official Snakemake wrapper", readiness) + self.assertIn("collect-then-gate", readiness) + self.assertIn("nf-core modules lint", readiness) + self.assertIn("nf-core modules test", readiness) + self.assertIn("topic channels", readiness) + self.assertIn("environment.linux-64.pin.yaml", readiness) + self.assertIn("test_wrappers.py", readiness) + self.assertIn("--gate submission", readiness) + self.assertIn("quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0", readiness) + self.assertIn("docs/workflow-readiness.md", nfcore_readme) + self.assertIn("docs/workflow-readiness.md", snakemake_readme) + self.assertIn("fastaguard=0.5.0", nfcore_environment) + self.assertIn("name: fastaguard", snakemake_meta) + self.assertIn("description:", snakemake_meta) + self.assertIn("output:", snakemake_meta) + def test_benchmarking_docs_include_v0_2_evidence_topics(self): text = (ROOT / "docs" / "benchmarking.md").read_text()