From 55b9a25c8449c58b28bfcc8e28b454529309ce7f Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch <antonin@delpeuch.eu>
Date: Sun, 26 Oct 2025 16:51:08 +0100
Subject: [PATCH] docs: New page about ABI versions for parser users

Closes #374.

The statement about the intended backwards compatibility is purely
speculative and provided as a "straw man" to help reviewers come up with
a better description of the intended backwards compatibility.
---
 docs/src/SUMMARY.md                      |  1 +
 docs/src/using-parsers/7-abi-versions.md | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 docs/src/using-parsers/7-abi-versions.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 6e6eed94..231085ae 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -15,6 +15,7 @@
     - [Predicates and Directives](./using-parsers/queries/3-predicates-and-directives.md)
     - [API](./using-parsers/queries/4-api.md)
   - [Static Node Types](./using-parsers/6-static-node-types.md)
+  - [ABI versions](./using-parsers/7-abi-versions.md)
 - [Creating Parsers](./creating-parsers/index.md)
   - [Getting Started](./creating-parsers/1-getting-started.md)
   - [The Grammar DSL](./creating-parsers/2-the-grammar-dsl.md)
diff --git a/docs/src/using-parsers/7-abi-versions.md b/docs/src/using-parsers/7-abi-versions.md
new file mode 100644
index 00000000..6845a9c4
--- /dev/null
+++ b/docs/src/using-parsers/7-abi-versions.md
@@ -0,0 +1,19 @@
+# ABI versions
+
+Parsers generated with tree-sitter have an associated ABI version. This version specifies the shape of the C code that they contain, which they expose to applications.
+
+A given version of tree-sitter is only able to load parsers which have certain ABI versions:
+
+| tree-sitter version | Min parser ABI version | Max parser ABI version |
+|---------------------|------------------------|------------------------|
+| 0.14                | 9                      | 9                      |
+| >=0.15.0, <=0.15.7  | 9                      | 10                     |
+| >=0.15.8, <=0.16    | 9                      | 11                     |
+| 0.17, 0.18          | 9                      | 12                     |
+| >=0.19, <=0.20.2    | 13                     | 13                     |
+| >=0.20.3, <=0.24    | 13                     | 14                     |
+| >=0.25              | 13                     | 15                     |
+
+Tree-sitter developers aim to maintain compatibility with the previous ABI version at least.
+
+Parser authors are able to specify the ABI version they want to use by specifying it with the `--abi` option of the `tree-sitter generate` command.