Workspace YAML format#

The workspace content under f/ is stored as YAML. wmill emits a canonical form when it serializes the instance, and this project keeps the files in exactly that form, so wmill sync push and wmill sync pull round-trip with no diff (see the wmill sync reference). That is what lets a contributor edit in the Windmill UI or through the CLI interchangeably. Treat the YAML as a wire format: do not hand-tune its layout, because the next sync would rewrite it.

Canonical form#

wmill always serializes the same way, so the on-disk shape is fixed:

  • Scalars use single quotes.

  • Map keys follow wmill’s order: a small fixed set of keys first, then the rest alphabetically, so a schema’s property children sort by name.

  • A script or flow description is a literal block (see below).

  • A lock is referenced as !inline <path> and stored in a sibling .lock file; commit the *.script.lock and *.inline_script.lock files.

  • A flow’s inline step scripts are externalized into .inline_script.* files.

A script file looks like this:

summary: 'QEMU: compile'
description: |-
  Build an already-configured QEMU in the build devShell.

  Reads build_dir from a prior prepare_worktree step.
lock: '!inline f/qemu/compile.script.lock'
kind: script
schema:
  $schema: https://json-schema.org/draft/2020-12/schema
  type: object
  order:
    - build_dir
  properties:
    build_dir:
      type: string
      description: Out-of-tree build directory.
  required:
    - build_dir

Descriptions#

wmill keeps a description as a readable literal |- block only when every rendered line fits in 80 columns. A single longer line flips the whole description to a folded > block, which double-spaces the prose and strands orphan words. So descriptions are wrapped so that no line passes 80 columns. A line is its indentation plus its content, so a deeper-nested description wraps narrower.

nix run .#reflow rewraps every description in place. nix flake check, through scripts/reflow-descriptions.py --check, fails if a committed description would fold. After editing a description in the UI or the CLI, run wmill sync pull, then nix run .#reflow, then wmill sync push, and commit.

What is preserved#

The canonical form changes only layout, never data. A field’s title, order and showExpr are values that survive a round-trip exactly, so curated field labels such as the acronym title QEMU Binary are safe to keep.

Generated files#

f/qsu/bringup.flow/flow.yaml is generated by scripts/gen-bringup.py in its own format and is never pulled, so the description-reflow rule does not apply to it; its generator owns its layout.