Merge pull request 'Name what a held release holds, and where it is released (ADR 0258)' (#155) from fix/release-held-says-what-waits into main

cmd/mesh-controller/plain_words.go

@@ -387,10 +387,7 @@ var plainWordings = map[string]func(conditions.Observation) words{
 			Resolved:    "Resolved: " + m + " runs a good build again"}
 	}),
 	"release-held": worded(func(o conditions.Observation) words {
-		return words{Headline: "Updates wait for your release",
-			Needs:       "release them, or leave them held.",
-			Explanation: "Some module updates wait for a person to release them, and are not delivered until then.",
-			Resolved:    "Resolved: the held updates are released"}
+		return releaseHeldWords(nil, o.Also)
 	}),
 	"facts-stale": worded(func(o conditions.Observation) words {
 		return words{Headline: "Merge checks use outdated facts",
@@ -402,21 +399,21 @@ var plainWordings = map[string]func(conditions.Observation) words{
 	// The controller and the core.
 	"controller-deaf": worded(func(o conditions.Observation) words {
 		return words{Headline: "The controller stopped listening",
-			Needs: "restart the controller if this stays.",
+			Needs: "restart the controller if this stays, " + FromMeshMCPServer,
 			Explanation: "The controller, which coordinates the mesh, has taken no messages for minutes while some " +
 				"wait. Changes and repairs do not happen until it recovers.",
 			Resolved: "The controller listens again"}
 	}),
 	"self-check-silent": worded(func(o conditions.Observation) words {
 		return words{Headline: "The mesh's self-check stopped",
-			Needs: "restart the controller if this stays.",
+			Needs: "restart the controller if this stays, " + FromMeshMCPServer,
 			Explanation: "The self-check, which looks over the whole mesh every few minutes, has not finished a run. " +
 				"Problems may go unnoticed until it runs again.",
 			Resolved: "The self-check runs again"}
 	}),
 	"watchdogs-silent": worded(func(o conditions.Observation) words {
 		return words{Headline: "The mesh's watchdogs stopped",
-			Needs: "restart the controller if this stays.",
+			Needs: "restart the controller if this stays, " + FromMeshMCPServer,
 			Explanation: "The watchdogs, which notice when something expected does not happen, have not run, so " +
 				"missed signals are not noticed.",
 			Resolved: "The watchdogs run again"}
@@ -683,6 +680,32 @@ func moduleNeeds(node string, rs []inventory.ResourceHealth) string {
 // authorised (to-be 46 phases 5 and 6).
 const FromMeshMCPServer = "from the mesh MCP server; this notification cannot do it."
 
+// releaseHeldWords are the plain words of updates held after a walk failed: which modules wait,
+// on which machines, and where the operator releases them (ADR 0258: a release is not an acknowledgement, so
+// no notification gives it). Raised with the modules and machines (backlogObservation); the kind's fallback
+// knows neither.
+func releaseHeldWords(modules, machines []string) words {
+	what := "Some module updates"
+	headline := "Updates wait for your release"
+	if len(modules) > 0 {
+		what = "Updates of " + namesWords(modules, 3)
+		if h := what + " wait for your release"; len(h) <= conditions.HeadlineMax {
+			headline = h
+		} else if h := fmt.Sprintf("%d module updates wait for your release", len(modules)); len(h) <= conditions.HeadlineMax {
+			headline = h
+		}
+	}
+	where := ""
+	if len(machines) > 0 {
+		where = " on " + namesWords(machines, 4)
+	}
+	return words{Headline: headline,
+		Needs: "release them " + FromMeshMCPServer,
+		Explanation: fmt.Sprintf("%s%s wait for a person to release them, because the last walk failed."+
+			" They are not delivered until then, and stay held if you leave them.", what, where),
+		Resolved: "Resolved: the held updates are released"}
+}
+
 // reloginNeeds is what an account waiting for its groups needs (ADR 0252).
 func reloginNeeds(node string) string {
 	return fmt.Sprintf("log out of %s completely and log in again, or restart it.", node)