Galaxy workflow comments

Use this note when authoring or translating a Galaxy gxformat2 workflow and deciding how to annotate it with editor comments — the top-level comments: array the workflow editor renders as on-canvas frames and notes. Comments carry no execution semantics; they document and visually organize the workflow. This is presentation guidance, not a content/patterns/ operation. Corpus evidence behind every rule here lives in iwc-comments-survey.

Comments are optional — roughly one in five IWC workflows use them. Add them when the workflow has enough steps that a reader benefits from a stage map; skip them on short linear workflows.

1. Box each analysis stage in a titled frame

The core move. Once topology is settled, partition the step set into type: frame comments — one frame per logical stage of the analysis — and give each a title: and a contains_steps: list of the step labels it groups:

comments:
  - type: frame
    position: [687.5, 395.8]
    size: [498.9, 345.5]
    color: green
    title: Genome quality evaluation
    contains_steps:
      - run BUSCO
      - summarize BUSCO

position and size are editor-canvas geometry (floats); set them so the frame encloses its steps, or copy them from the nearest IWC exemplar you are adapting.

2. Title by stage, not by tool

A frame title names the analysis phase, never the tool that implements it — Annotation with Braker3, Final MF assignment, Transcripts assembly, not braker3 or stringtie. Three title flavors, all valid:

• Stage frames — one per narrative step of the analysis (the common case).
• I/O region frames — Inputs, Data input, Visualization bracket the workflow’s entry and exit regions.
• Parameter-derivation frames — box the fiddly utility clusters that compute a parameter (Map Strandedness parameter, Downsample input BAM to get the same number of reads). This is the highest-value annotation: the frame is often the only place the intent of a non-obvious helper cluster is written down. Always frame these.

Titles are human prose — spaces, mixed case, and punctuation are fine.

3. Populate contains_steps

Prefer explicit contains_steps: (a list of step labels) over relying on canvas geometry alone. Both render identically, but a geometry-only frame loses the machine-readable step→frame mapping — a consumer can only recover membership by intersecting rectangles. List every step the frame covers.

4. Color is decorative — do not encode meaning

Pick any editor color: green, yellow, turquoise, red, blue, pink, lime, orange, black, or none (an unfilled outline). Color carries no semantic convention — do not use it to signal input vs output vs compute, and do not infer role from a frame’s color when reading a workflow. When forking a workflow, keep each frame’s color stable so the lineage stays visually recognizable.

5. Free-floating notes: markdown and text

For a labeled region without a box, use a type: markdown comment (a text: field holding a markdown body) or type: text (a text: field plus text_size:). Keep these short — they are mostly one-to-three-word region headers (Input files, Alpha diversity). The one place a longer markdown note earns its keep is workflow-level adaptation guidance — e.g. “to retarget this nanopore workflow for Illumina, replace Minimap2 with Bowtie2.” Reach for prose only when a stage title cannot carry the instruction.

6. Comments are reusable scaffold

Frames travel with workflow forks and templates: when deriving a workflow from an IWC exemplar, carry its frame set and adjust titles rather than starting bare. Embedded subworkflows can carry their own comments: array, so annotate at the scope the reader navigates.

7. Schema and validation

comments: is a schema-legal top-level workflow field (and a subworkflow field); emitted frames pass gxwf draft validation. Field shapes:

Cross-references

• Corpus evidence and distribution: iwc-comments-survey.
• gxformat2 field schema: gxformat2-schema.