.. SPDX-License-Identifier: copyleft-next-0.3.1

=====================
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.

.. _wmill sync: https://www.windmill.dev/docs/advanced/cli/sync

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
===============

:src:`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.