From 9206d41ccc24103ec5e4e4dd67a888010b894ae5 Mon Sep 17 00:00:00 2001
From: Igor Sirotin <sirotin@status.im>
Date: Mon, 18 May 2026 20:59:44 +0100
Subject: [PATCH] docs: add versioning policy (#25)

Documents the MAJOR.MINOR.PATCH scheme: MAJOR fixed at 0 (pre-stable),
MINOR tracks the Logos testnet number, PATCH for module releases within
a testnet.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/versioning.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 docs/versioning.md

diff --git a/docs/versioning.md b/docs/versioning.md
new file mode 100644
index 0000000..8cc98f1
--- /dev/null
+++ b/docs/versioning.md
@@ -0,0 +1,43 @@
+# Versioning
+
+This module uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) with the following conventions.
+
+## Scheme
+
+```
+0 . <testnet> . <patch>
+│        │           └── module release within a testnet
+│        └────────────── tracks the Logos testnet number
+└─────────────────────── fixed at 0; breaking changes are expected
+```
+
+### MAJOR — fixed at `0`
+
+The major version is kept at `0` for the foreseeable future. A value of `0` signals that the API is **not yet stable**: breaking changes may be introduced in any release. Once the API stabilises across testnets this policy will be revisited.
+
+### MINOR — Logos testnet number
+
+The minor version is incremented to match the Logos testnet with which this module is compatible. Bumping MINOR resets PATCH to `0`.
+
+Example: `0.2.0` targets Logos Testnet 2.
+
+### PATCH — module release within a testnet
+
+The patch version is incremented for every module release made against the same testnet: bug fixes, dependency updates, performance improvements, or any other change that does not change the target testnet.
+
+Example: `0.2.3` is the fourth release of the module targeting Logos Testnet 2.
+
+## Examples
+
+| Version | Meaning |
+|---------|---------|
+| `0.1.0` | First release for Testnet 1 |
+| `0.1.1` | Bug-fix release, still targets Testnet 1 |
+| `0.2.0` | First release for Testnet 2 |
+| `0.2.1` | Patch release for Testnet 2 |
+
+## Releasing
+
+1. Update `"version"` in [`metadata.json`](../metadata.json).
+2. Tag the commit: `git tag v<version>`.
+3. Push the tag: `git push origin v<version>`.