Proposal: Machine-Readable Compatibility Matrix

[lukebakken]

RabbitMQ series

4.2.x

Operating system (distribution) used

Linux

How is RabbitMQ deployed?

Other

What would you like to suggest for a future version of RabbitMQ?

The current Erlang/Elixir compatibility information for RabbitMQ releases is only available in HTML format on the documentation website. This makes it difficult to programmatically validate version compatibility. Tools must either parse HTML tables (fragile and error-prone) or hardcode compatibility information, which could becomes stale or inaccurate.

The Erlang project provides the otp_versions.table file which helps facilitate automation around Erlang releases and associated applications.

Proposed Solution

Add a machine-readable compatibility file to the rabbitmq/rabbitmq-server repository that serves as the canonical source of truth for version compatibility. The HTML table in this document would then be generated from this file, ensuring consistency between the human-readable documentation and machine-consumable data.

To capture this information, I suggest the use of a JSON file with version ranges expressed using mathematical interval notation:

{
  "4.2.3": {
    "erlang": "[26.2,28.0)",
    "elixir": "[1.16.0,1.20.0)"
  },
  "4.0.4": {
    "erlang": "[26.2,28.0)",
    "elixir": "[1.16.0,1.19.0)"
  },
  "4.0.3": {
    "erlang": "[26.2,26.3)",
    "elixir": "[1.16.0,1.19.0)"
  },
  "3.13.8": {
    "erlang": "[26.0,26.3)",
    "elixir": "[1.16.0,1.19.0)"
  }
}

The interval notation uses [ for inclusive bounds and ) for exclusive bounds. For example, [26.2,28.0) means 26.2 ≤ version < 28.0. This notation is used by Maven and NuGet, and comes from standard mathematical interval notation, making it familiar to developers across multiple ecosystems.

This format provides a single source of truth that both humans and machines can consume. Deployment tools can validate compatibility before starting lengthy deployments, catching version mismatches in seconds rather than after 20 minutes of provisioning. The HTML documentation table can be generated from this file, ensuring the website always reflects the canonical data.

The file would include versions from 3.11.0 onwards, as earlier versions are no longer referenced on the web site. It would be maintained manually with each release, similar to how the HTML table is currently maintained. A CI check could validate that the file is well-formed JSON with properly formatted version ranges. The existing HTML table would remain authoritative during a transition period until the JSON file is complete and validated.

At some point in the future, it would be great to automatically manage this compatibility data when a new RabbitMQ release is published.

[michaelklishin]

@lukebakken I like this idea. We can keep it under docs in this repo or something like that.

[lukebakken]

Voila! #15543