document how to deal with backward compatibility breakage

xtask/src/backcompat.rs

@@ -1,3 +1,30 @@
+/*
+Backward compatibility test broke? Here's what needs to happen.
+
+# To land a pull-request (PR)
+
+Temporarily disable the test.
+
+- set the `DISABLED` constant below to `true`; commit this change into the PR branch
+- open issues to remind ourselves of the follow-up work: see next section
+- add (if not already there) "next release is blocked by issue <number>" (use the number of 'Second issue' below)
+- merge PR
+
+# Follow-up issues
+
+## First issue: "re-enable backcompat test (broken by PR <number>)"
+
+- create a PR that
+ - sets `DISABLED` constant back to `false`
+ - updates `REVISION_UNDER_TEST` constant to point to the hash of the merge commit of PR <number>
+
+## Second issue (if it doesn't already exist): "multiple decoder support"
+
+- create a PR that
+ - bumps the `DEFMT_VERSION` constant in `decoder/sc/lib.rs`
+ - implements what's decided in RFC596
+ */
+
 use std::{
  borrow::Cow,
  path::{Path, PathBuf},
@@ -10,6 +37,8 @@ use tempfile::TempDir;
 
 use crate::{ALL_ERRORS, ALL_SNAPSHOT_TESTS, SNAPSHOT_TESTS_DIRECTORY};
 
+const DISABLED: bool = false;
+
 // use this format: PR <number> - <what feature / change broke compatibility>
 // PR #569 - defmt::println!
 const REVISION_UNDER_TEST: &str = "8a6e8eebe40f943d9b0ba8725cd6da033b9c399e";
@@ -18,6 +47,11 @@ const REVISION_UNDER_TEST: &str = "8a6e8eebe40f943d9b0ba8725cd6da033b9c399e";
 const RUNNER_ENV_VAR: &str = "CARGO_TARGET_THUMBV7M_NONE_EABI_RUNNER";
 
 pub fn test() {
+ if DISABLED {
+ println!("⚠️ backcompat (DISABLED)");
+ return;
+ }
+
  println!("🧪 backcompat");
 
  println!("building old qemu-run.. (git revision: {})", REVISION_UNDER_TEST);
@@ -35,7 +69,10 @@ pub fn test() {
  };
 
  for snapshot_test in ALL_SNAPSHOT_TESTS {
- super::do_test(|| qemu_run.run_snapshot(snapshot_test), "backcompat");
+ super::do_test(
+ || qemu_run.run_snapshot(snapshot_test),
+ "backcompat (see xtask/src/backcompat.rs for FIXME instructions)",
+ );
  }
 }