Problem
Left over from the documentation audit in #3620617. Comments, docblocks, a shipped field description and three documentation pages each state something the code does not do.
Two claims carry most of it. The first is that an instance can be created before versioning: no such instance exists on a supported install, because this is a pre-1.0 line with no update path. The one run that legitimately pins nothing is one started while the versioning mode was Off, which ensureCurrentVersion() short-circuits before it resolves anything; auto and manual both pin at the start. The second is that a pinned snapshot can have been pruned: pruneOrphans() skips every revision an instance references, and asks nothing about that instance's state, so a run cannot lose the version it pins.
One of these is not a docblock. The definition_version field description is shipped, translated, user-visible text, so it told an operator on a versioning site something false about their own instances.
What changes
The docblocks name the one run that pins nothing, and say that turning the mode on afterwards pins only new runs, so unpinned instances outlive the setting that produced them. The field description says the same, and its French follows it.
retention.md no longer gates snapshot pruning on retention, which the cron hook has never done, and no longer promises to remove a version cron always keeps: a live workflow's latest is kept whatever happens, because a revision delete refuses the default. versioning.md stops widening, in its closing sentence, a translation guarantee it had just scoped correctly. troubleshooting.md no longer advises switching versioning off to reach a stuck instance, which cannot work, because nothing consults the mode once a run has started.
The example_quorum ballots describe the audience they actually share, rather than a distinction the config does not make. Two comments that pointed at methods no class has now point at the ones that exist, and the modeler's edit warning stops describing an unpinned run as history when Off is a mode a site can be in today.
Tests
Each corrected claim gains an assertion that fails if the claim stops holding: a finished run protecting its snapshot, a live workflow keeping its latest version, a superseded revision keeping the wording it was cut with, a pinned run surviving a mode change, the timeout join refusing a timeout it cannot measure with, one row per attachment key, and a non-default tenant carrying the delete operation the default one is denied.
A new DocblockReferenceTest sweeps every comment naming one of this project's own methods and fails on one that does not exist, so a reference that drifts is caught rather than read as a fact about the design.
AI-Generated: Yes (Claude Code was used to help draft this issue summary, to make the corrections and to write their tests. I reviewed all of it. The reference sweep was confirmed to fail on the two stale references and to pass once they were corrected; the other tests pin invariants this change does not alter.)
Issue fork orchestra-3620826
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #3
mably commentedComment #4
mably commentedComment #5
mably commentedComment #7
mably commented