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

Command icon 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

mably created an issue. See original summary.

mably’s picture

Title: Comments that describe unreachable states, and an @api name that means two different things » Comments that describe states the code cannot reach
Issue summary: View changes
Status: Active » Needs review
mably’s picture

Issue summary: View changes
mably’s picture

Title: Comments that describe states the code cannot reach » Describe the states the code can actually reach
Issue summary: View changes

  • mably committed bc205f4f on 1.x
    fix: #3620826 Describe the states the code can actually reach
    
    By: mably
    
mably’s picture

Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.