From 2b3a80b477865177dbdf030d9d5360191b03f312 Mon Sep 17 00:00:00 2001 From: Ivan Molodetskikh Date: Tue, 2 Apr 2024 09:08:36 +0400 Subject: wiki: Document IPC backwards compatibility --- wiki/IPC.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) 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. -- cgit