werkator/docs/prs/2026-10-04-PR#112-build-definition-applied-in-blocks.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

After PR#111 BuildDefinition.applyTo had the highest Mutation-CRAP score of Werkator: 34 at a complexity of 34. A score is never below the complexity, so no test could bring it under the limit of 15.

The method laid a build definition over its branch's settings in one copy of 21 fields, each with its own ?: fallback, the docker and werkdock blocks nested inside. What the definition says falls into three groups, but the method did not show them: what the build runs, the rules the instance runs it under, and the sandbox it runs in. Only one test checked a single field of it (Scenario#72.01); every other field was held only by tests of the config loader.

Non-Goals

• No change in behaviour: which settings a definition can say, how they inherit, and which are pinned stay as they are.

The Scenarios

Feature: A build definition laid over its branch's settings

Scenario#112.01: A definition that says nothing runs the branch's settings unchanged

So that builds.<name> with only a trigger builds exactly what the branch describes.

• Given a branch with a non-default value for every setting
• When an empty definition, or one with empty docker and werkdock blocks, is applied
• Then the result equals the branch's settings

Verified by

• BuildDefinitionUnitTest — Scenario#112.01

Scenario#112.02: Every setting a definition says replaces the branch's own

So that no key of builds.<name> is read and then silently dropped.

• Given the same branch, and a definition saying every setting, docker and werkdock included, with other values
• When the definition is applied
• Then every setting is the definition's

Verified by

• BuildDefinitionUnitTest — Scenario#112.02

Scenario#112.03: A definition saying some settings of a block keeps the rest of that block

So that docker.image alone does not reset the branch's network, socket or environment.

• Given the same branch, and a definition saying only the timeout, the docker image and the werkdock rootfs
• When the definition is applied
• Then those three are the definition's, everything else is the branch's

Verified by

• BuildDefinitionUnitTest — Scenario#112.03

The Solution

applyTo lays the definition over the branch in three blocks:

Block	Settings
withWork	buildCommand, cleanCommand, artifactDirs, stdoutLog, stderrLog
withRules	requirePullRequest, statusContext, timeout, restartsInstance
withSandbox	docker, werkdock

DockerOverrides.applyTo and WerkdockOverrides.applyTo lay each sandbox's overrides over the branch's sandbox of that kind. The overrides and their config class now stand side by side, where Scenario#72.03 already holds that every setting of the one exists in the other.

Measured with PIT as the nightly build runs it:

Method	Before	After
BuildDefinition.applyTo	34	no mutants
BuildDefinition.withWork	—	6
BuildDefinition.withRules	—	5
BuildDefinition.withSandbox	—	5
DockerOverrides.applyTo	—	8
WerkdockOverrides.applyTo	—	6

Every mutant of the new methods is killed, none is INCONCLUSIVE; each score equals its complexity.

The gate maxMutationCrap falls from 35 to 34: the highest score left is CapacitySizing.cpu at 33.17.

Additional Changes

• Version 1.34.9 with its release note.
• BuildExecutorUnitTest, Scenario#108.05, waits for the executing build's process before it cancels the build: a build counts as running before its process is started, and a cancel in between left no process to see terminated (List is empty, seen once in this PR's local build).

Follow-up PRs

• CapacitySizing.cpu (33.17) in its own PR.