Require an impact for each known compat break

Entries now explain why end users are not or only minimally affected,
and the docs say which version to key by and point to the breaking
changes decision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

scripts/version-compat-breaks.js

@@ -7,9 +7,9 @@
  *   {
  *     "2.0.3": {
  *       "messages": {
- *         "request FactorioVersionsRequest": { "pr": 1129, "reason": "..." }
+ *         "request FactorioVersionsRequest": { "pr": 1129, "reason": "...", "impact": "..." }
  *       },
- *       "connect": { "pr": 1234, "reason": "..." }
+ *       "connect": { "pr": 1234, "reason": "...", "impact": "..." }
  *     }
  *   }
  *
@@ -30,10 +30,12 @@ function validateBreak(value, where) {
 	if (!Number.isInteger(value.pr) || value.pr <= 0) {
 		throw new Error(`${where} must have a pr number`);
 	}
-	if (typeof value.reason !== "string" || !value.reason.trim()) {
-		throw new Error(`${where} must have a reason`);
+	for (const key of ["reason", "impact"]) {
+		if (typeof value[key] !== "string" || !value[key].trim()) {
+			throw new Error(`${where} is missing ${key}`);
+		}
 	}
-	const unknown = Object.keys(value).filter(key => !["pr", "reason"].includes(key));
+	const unknown = Object.keys(value).filter(key => !["pr", "reason", "impact"].includes(key));
 	if (unknown.length) {
 		throw new Error(`${where} has unknown properties ${unknown.join(", ")}`);
 	}

scripts/version-compat-breaks.json

@@ -3,11 +3,13 @@
 		"messages": {
 			"request FactorioVersionsRequest": {
 				"pr": 1129,
-				"reason": "Hosts send it while starting an instance, so a newer host cannot start instances on a 2.0.3 controller."
+				"reason": "Hosts send it while starting an instance, which a 2.0.3 controller rejects so the start fails.",
+				"impact": "The host stays connected and the instance goes back to stopped with the error shown, starting it works again once the controller is updated."
 			},
 			"request LatestReleasesRequest": {
 				"pr": 1129,
-				"reason": "Hosts send it while starting an instance that targets a release channel such as stable, which a 2.0.3 controller rejects."
+				"reason": "Hosts send it while starting an instance that targets a release channel such as stable.",
+				"impact": "Hosts send FactorioVersionsRequest first, so a 2.0.3 controller rejects the start before this is sent, starting it works again once the controller is updated."
 			}
 		}
 	}

scripts/version-compat-test.js

@@ -247,8 +247,8 @@ async function checkMessageCompat(publishedVersion, knownBreaks) {
 	const { known, unknown, stale } = matchBreaks(knownBreaks, changed.map(({ name }) => name));
 	for (const { name, fields, localSpec, publishedSpec } of changed) {
 		if (known.includes(name)) {
-			const { pr, reason } = knownBreaks.get(name);
-			annotate(`Link ${name} is a known break since ${publishedVersion} from #${pr}: ${reason}`);
+			const { pr, reason, impact } = knownBreaks.get(name);
+			annotate(`Link ${name} is a known break since ${publishedVersion} from #${pr}: ${reason} Impact: ${impact}`);
 			printChange(console.log, name, fields, localSpec, publishedSpec, publishedVersion);
 		} else {
 			printChange(console.error, name, fields, localSpec, publishedSpec, publishedVersion);
@@ -308,8 +308,10 @@ async function main() {
 	}
 	await checkMessageCompat(publishedLib.version, knownBreaks.messages);
 	if (knownBreaks.connect) {
-		const { pr, reason } = knownBreaks.connect;
-		annotate(`Skipping cluster test, known break since ${publishedLib.version} from #${pr}: ${reason}`);
+		const { pr, reason, impact } = knownBreaks.connect;
+		annotate(
+			`Skipping cluster test, known break since ${publishedLib.version} from #${pr}: ${reason} Impact: ${impact}`
+		);
 		console.log(`PASS: link messages match ${publishedLib.version} apart from known breaks`);
 		return;
 	}