Terminology

The ubiquitous language for how build sources, artifacts and collaborators are organized and shared between people and the Windmill engine.

Note

A Workbench is not a Windmill workspace. A workbench is a build sandbox on disk; the Windmill workspace (the kdevops workspace-as-code) holds flow and script content. They are different kinds of thing and the two words are never used interchangeably.

How the terms relate

A Developer publishes a git reference, or ref, to the Bare, and a Worker consumes that ref into its own Worktree. Each Worktree is paired with a Build, and each Build is identified by a Build identity, which keys the Store.

The containment of the on-host pieces is:

workbench/             the Workbench (relocatable; or $HOME/src)
├── system/            reserved singletons: bare/ mirror/ ssh/ store-index/
│                      ccache/ gitbin/ and the peers registry
├── workers/           per-worker sandboxes + a shared/ sibling
│   ├── <id>/          a worker sandbox
│   │   └── main/      the worker's fixed group
│   │       └── linux/ the worker worktree (build site)
│   └── shared/        cross-worker: vm/ (deployed-VM registry), ccache/, ...
├── vanilla/           the default developer's worktree-group
│   ├── linux/         a project worktree
│   │   ├── build/     child of the source
│   │   └── destdir/   install staging
│   └── qemu/          a project worktree
│       ├── build/
│       └── destdir/
└── largeio/           a further developer's worktree-group
    ├── linux/         a project worktree
    ├── qemu/
    ├── fio/
    └── xfstests/
vendor/                pinned upstream projects

The whole workbench/ relocates as a unit; system/ and workers/ each relocate on their own, since they are infrastructure rather than developer content, and the worktree-groups likewise relocate as a set, defaulting as the Workbench’s direct children but pointable elsewhere together. A workbench need not sit inside this project: point it at any directory such as $HOME/src, and that directory becomes the workbench, with worktree-groups directly under it (so $HOME/src/vanilla). The names system and workers are reserved, so a worktree-group may not take them. vendor/ holds the pinned upstream projects and stays a top-level sibling.

A project gains several worktrees by appearing in several worktree-groups: vanilla/linux and largeio/linux are two worktrees of one linux, both cut from the single system/bare/linux.git.

Actors

Worker

A Windmill worker unit; the build executor. A worker always builds in its own Worker sandbox and never modifies a Developer’s Worktree.

Avoid: builder.

Developer

A human authorized to drive the Windmill engine through its CLI or UI: to create Worktrees, publish refs, and so on. A developer hands work to a Worker only by publishing a ref to the Bare.

Avoid: operator, user.

Places

Workbench

A directory containing a Developer’s Worktree-groups and the kdevops-ng infrastructure (the System workbench and the Worker sandboxes) that defaults under it. It relocates as a whole (default workbench/, or for example $HOME/src), and the infrastructure relocates on its own. It is not a Windmill workspace.

Avoid: workspace, sandbox, bench.

Worktree-group

A topic or chain of work within a Workbench (default name vanilla; many may exist, such as largeio). It holds one Worktree per project the topic involves, and the developer switches between groups. The groups are the Workbench’s direct children by default and relocate as a set on their own.

Avoid: workbench, default.

System workbench

The host-local infrastructure singleton: the Mirrors, Bares, SSH keys, Store, the shared compiler cache, the Store index (the identity->store-path GC-root registry), and the peers registry (the cross-host peer list). It defaults to system/ under the Workbench but relocates on its own, and its Mirrors (the bulky shared object store, default system/mirror), compiler cache (default system/ccache) and Store index (default system/store-index, relocatable via STORE_INDEX_DIR) relocate apart from it again. It is user-scoped and sudo-less in steady state.

Avoid: service workbench.

Worker sandbox

A Worker’s own build area (default workers/<id>/, relocatable on its own). Inside it the worker keeps one worker worktree per project under the fixed main group (workers/<id>/main/<project>). A worker builds here, never in a Developer’s Worktree.

Avoid: workbench, worker dir.

Project name

A project’s upstream source-directory name, such as linux or qemu. The project folder within a Worktree-group is named by it.

Avoid: source name.

Source and artifacts

Worktree

A git checkout of a project within a Worktree-group, the folder named by its Project name, created with git-worktree(1); the project abbreviates git-worktree to worktree. The project keeps two kinds. A worker worktree is the build site: it lives in a Worker sandbox at workers/<id>/main/<project> under the worker’s fixed main group, is re-synced to the ref on every build, and is tunable only by wipe and reinitialize. A developer worktree is developer-owned, under WORKTREES_DIR/<group>/<project>, and is the checkout a developer fetches a build’s devel layer into for editor indexing; whether one exists is independent of where the build ran. A Worker never modifies a Developer’s worktree. A project gains several developer worktrees by appearing in several worktree-groups.

Avoid: tree, checkout.

Build

The build directory paired with one Worktree. By default it is a child of the source worktree so kbuild emits relative paths and artifacts relocate across hosts with no rewrite. There is one Build per worktree.

Avoid: build dir, O=.

Mirror

A disposable local cache of an upstream, force-refreshed on a timer. A pure ref and object source: it never holds Worktrees or development branches. It lives at system/mirror by default and, being the bulky shared object store, relocates on its own.

Avoid: cache, clone.

Bare

The durable working repo at system/bare/<project-name>.git: it holds development branches and all Worktrees, borrows the Mirror’s objects, and pulls the Mirror’s refs into a remotes namespace. It is never force-pruned, and there is one per host. The Bare is the ref channel between a Developer and a Worker.

Avoid: remote, clone.

Build identity

A content hash of a Build’s inputs: config, toolchain (the Nix devShell’s store hash), build flags, and the source tree (so a series re-applied with git am keeps one identity). Same identity implies the same bytes. Where it can, a project bakes the identity into its artifact so the result self-reports it; the kernel, for example, puts it in kernelrelease via LOCALVERSION.

Avoid: build hash, release.

Store

Maps a Build identity to its built artifacts, so a host that lacks an identity fetches it from a peer instead of rebuilding; fetch beats build. The artifacts live in the Nix store (added with nix store add-path, fetched with nix copy) and are indexed by identity, because a make build is not a Nix derivation and Nix offers no pre-build key to skip it.

Avoid: destdir, artefactory, registry, releases.