wiki: Document IPC backwards compatibility

1 files changed, 17 insertions, 0 deletions

diff --git a/wiki/IPC.md b/wiki/IPC.md
index 853c3c3f..ee4ea82e 100644
--- a/wiki/IPC.md
+++ b/wiki/IPC.md
@@ -10,3 +10,20 @@ The communication over the IPC socket happens in JSON.
 > [!TIP]
 > If you're getting parsing errors from `niri msg` after upgrading niri, make sure that you've restarted niri itself.
 > You might be trying to run a newer `niri msg` against an older `niri` compositor.
+
+### Backwards Compatibility
+
+The JSON output *should* remain stable, as in:
+
+- existing fields and enum variants should not be renamed
+- non-optional existing fields should not be removed
+
+However, new fields and enum variants will be added, so you should handle unknown fields or variants gracefully where reasonable.
+
+I am not 100% committing to the stability yet because there aren't many users, and there might be something basic I had missed in the JSON output design.
+
+The formatted/human-readable output (i.e. without `--json` flag) is **not** considered stable.
+Please prefer the JSON output for scripts, since I reserve the right to make any changes to the human-readable output.
+
+The `niri-ipc` sub-crate (like other niri sub-crates) is *not* API-stable in terms of the Rust semver; rather, it follows the version of niri itself.
+In particular, new struct fields and enum variants will be added.