docs(compose): rewrap the rewritten comments and tighten four of them

Follow-up of the two previous commits, from their review: rewrap the
comments they left with an orphan line, give two of them back a subject,
point one at the plan's wait nodes, and drop the "imperative engine"
wording of the restart tests, restart being the one command that still
walks the dependency order itself.

Comments only: the token stream of every Go file, comments excluded, is
unchanged.

Part of #14081

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
This commit is contained in:
Nicolas De Loof 2026-10-27 10:05:41 +01:00 • committed by Nicolas De loof
parent 05e47b3065
commit f8cc1c2d24
5 changed files with 28 additions and 27 deletions

View file

@ -39,10 +39,10 @@ type planExecutor struct {
project *types.Project
pctx *reconciliationContext
// listener streams pre_start/post_start hook logs. It is set once, when the Start phase is entered
// (planRun.runStart): an attached caller only has one by then, its printer
// not existing before the Create phase is done. nil leaves hook execution
// silent, matching detached behavior.
// listener streams pre_start/post_start hook logs. It is set once, when
// the Start phase is entered (planRun.runStart): an attached caller only
// has one by then, its printer not existing before the Create phase is
// done. nil leaves hook execution silent, matching detached behavior.
listener api.ContainerEventListener
// containersByService is a live view used to resolve service references
@ -551,8 +551,8 @@ func (e *waitInterrupted) Error() string { return "wait interrupted" }
// translateWaitTimeout turns a plan failure caused by a wait node's own
// --wait-timeout window (see errWaitTimeout) into the "timeout waiting for
// dependencies" message a depends_on wait timing out has always reported,
// with or without --wait, and leaves any other
// error as is. It is deliberately not the "application not healthy" message:
// with or without --wait, and leaves any other error as is. It is
// deliberately not the "application not healthy" message:
// that one belongs to the final --wait readiness check that runs after the
// plan, which has its own translation.
func translateWaitTimeout(err error) error {

View file

@ -961,8 +961,8 @@ func (r *reconciler) reconcileService(service types.ServiceConfig) error {
// here; it never creates one itself.
//
// Purges are best-effort (a failed removal only warns) but the creates depend
// on them: runner names are deterministic,
// so a genuinely stuck old runner surfaces as a name conflict on the create.
// on them: runner names are deterministic, so a genuinely stuck old runner
// surfaces as a name conflict on the create.
// The creates also depend on every replica node and on the infrastructure, so
// the executor resolves the target replica (VolumesFrom) against a final live
// view with networks in place. When a running replica survives the plan, the
@ -1385,8 +1385,8 @@ func (r *reconciler) waitConditionNode(dep string, cfg types.ServiceDependency,
// planProviderStart is the start-phase visit of a provider service: no
// container to start, but its own depends_on still applies, as for every
// service, providers included. Its chain
// end is its create-phase RunProvider node (the deployment itself), plus
// service, providers included. Its chain end is its create-phase
// RunProvider node (the deployment itself), plus
// those dependency prerequisites when it has any -- a consumer must wait for
// both: the provider's own dependencies satisfied AND the provider actually
// deployed, not either in isolation. Before this ordering was corrected, a
@ -1465,8 +1465,8 @@ func (r *reconciler) planServiceStart(service types.ServiceConfig) error {
if service.Provider != nil {
return r.planProviderStart(service)
}
// deploy.replicas: 0 is an unconditional
// no-op, but a service with scale: 0 is still visited -- its depends_on
// deploy.replicas: 0 is an unconditional no-op, but a service with
// scale: 0 is still visited -- its depends_on
// conditions are evaluated and its dependents ordered after them -- and
// whatever replicas it already owns are started (scope Start only: the
// create phase removes them all under CreateStart). It is just never an
@ -1477,17 +1477,17 @@ func (r *reconciler) planServiceStart(service types.ServiceConfig) error {
replicas, anyRunning := r.startPhaseReplicas(service)
// dependency conditions are evaluated even when nothing has to start:
// every visited service evaluates its dependencies
// BEFORE looking at what to start, so an up with everything running
// still fails on an unhealthy required dependency — and a dependency
// every visited service evaluates its dependencies (the plan's wait
// nodes) BEFORE looking at what to start, so an up with everything
// running still fails on an unhealthy required dependency — and a dependency
// error wins over "no container to start", in that same order
depNodes, err := r.startPhaseDependencies(service)
if err != nil {
return err
}
if len(replicas) == 0 && !anyRunning && r.options.Scope == ScopeStart && service.GetScale() > 0 && !r.observedAnyContainer() {
// the "no container to start" check
// is project-wide -- it looks at the whole project's container list,
// the "no container to start" check is project-wide -- it looks at
// the whole project's container list,
// so a service without a container next to existing ones is a no-op
// and only a project with no container at all fails. Only reachable
// under scope Start, since CreateStart would have planned the
@ -1517,7 +1517,7 @@ func (r *reconciler) planServiceStart(service types.ServiceConfig) error {
// no entry otherwise (ScopeStart, all running, no depends_on): the
// visit had no effect, so dependents have nothing to order after —
// a service_started condition on a running dependency is already
// satisfied, as after an empty visit
// satisfied, as when nothing needs starting
return nil
}

View file

@ -992,9 +992,9 @@ func TestPlanStart_OrdinaryPathBareStartsAStaleRelay(t *testing.T) {
// test for the second Copilot review finding on #14296, the symmetric gap:
// a service declared provider: whose observed container is NOT a relay (a
// stale normal replica left over from before the service became
// provider-backed) must still be started -- Provider != nil is only
// special-cased for the ZERO-containers
// case, so an existing non-relay container is always started normally,
// provider-backed) must still be started -- the start path only
// special-cases Provider != nil for the ZERO-containers case, so an
// existing non-relay container is always started normally,
// including post_start hooks. planProviderRelayRestart's first version
// silently dropped this case (filtered on isRelayContainer), returning
// success without starting anything.

View file

@ -33,11 +33,11 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
// These tests characterize the restart path before the lifecycle engines
// converge (#14081): which depends_on relations survive project preparation,
// and the per-container sequence (pre_stop → ContainerRestart → post_start)
// with its events. restart stays on the imperative engine but shares the
// hook/wait primitives with the plan.
// These tests characterize the restart path: which depends_on relations
// survive project preparation, and the per-container sequence (pre_stop →
// ContainerRestart → post_start) with its events. restart still walks the
// dependency order itself (InDependencyOrder) but shares the hook/wait
// primitives with the plan.
// TestPrepareRestartProject locks the selection semantics: only depends_on
// relations declaring restart:true are kept, and naming services includes

View file

@ -80,7 +80,8 @@ func (s *composeService) start(ctx context.Context, projectName string, options
// Unlike upDetached/create, start() never calls emitRunningEvents: a
// no-op `compose start` (every container already running) must stay
// silent. emitRunningEvents is create-oriented: it exists so `up`/`create`'s full
// silent. emitRunningEvents is create-oriented: it exists so
// `up`/`create`'s full
// project-status display accounts for containers the plan won't touch,
// a concern start() has never had.