From 0a549596b00a62e47fdaf801584216a26b1831e8 Mon Sep 17 00:00:00 2001
From: Sebastian Weddmark Olsson <sebastiw@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:50:22 +0100
Subject: [PATCH] Compatibility matrix strategy (#389)

* Compatibility matrix strategy

Example on how one can maintain a compatibility matrix

* v2 -> v4

Co-authored-by: Kian-Meng Ang <kianmeng.ang@gmail.com>

* ubuntu-18 not longer available

* Update README.md after review suggestions

* Link rebar3 compat

Apparently rebar3 has started to maintain a version compatability table themselves. Missing older versions though

| 3.10.0 | 17         |
| 3.11.1 | 18         |

* Tweak README change proposal

* Apply suggestions from code review

Apply changes to resolve linter warnings

Co-authored-by: Paulo F. Oliveira <paulo.ferraz.oliveira@gmail.com>

---------

Co-authored-by: Kian-Meng Ang <kianmeng.ang@gmail.com>
Co-authored-by: Paulo F. Oliveira <paulo.ferraz.oliveira@gmail.com>
---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 8548460..5e87e83 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,11 @@ and Erlang/OTP.
 **Note** \*: prior to 23, Windows builds are only available for minor versions, e.g. 21.0, 21.3,
 22.0, etc.
 
+### Compatibility between Erlang/OTP and rebar3
+
+Check [version compatibility](https://github.com/erlang/rebar3?tab=readme-ov-file#compatibility-between-rebar3-and-erlangotp)
+in `erlang/rebar3`.
+
 ### Self-hosted runners
 
 Self-hosted runners need to set env. variable `ImageOS` to one of the following, since the action
@@ -292,6 +297,34 @@ jobs:
       - run: rebar3 ct
 ```
 
+### Compatibility
+
+To execute matrix testing with specific dependency versions, configure the environment matrix to
+use pinned, compatible releases:
+
+```yaml
+  test:
+    runs-on: ${{matrix.compat.os}}
+    name: Erlang/OTP ${{matrix.compat.otp}} / rebar3 ${{matrix.compat.rebar3}}
+    strategy:
+      matrix:
+        compat:
+          - otp: "26.2.5.5"
+            rebar3: "3.22.1"
+            os: ubuntu-24.04
+          - otp: "27.1.2"
+            rebar3: "3.22.1"
+            os: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: ${{matrix.compat.otp}}
+          rebar3-version: ${{matrix.compat.rebar3}}
+          version-type: strict
+      - run: rebar3 eunit
+```
+
 ### Erlang/OTP + `rebar3`, on Windows
 
 ```yaml