From 62c9819c00155439e9e8ccc286c524e6885b66c9 Mon Sep 17 00:00:00 2001
From: Tauan BF <11513929+tauanbinato@users.noreply.github.com>
Date: Fri, 25 Sep 2026 20:01:27 -0300
Subject: [PATCH] Propose what the version number promises

A site page on versions and stability: what semver covers from 1.0 (commands, flags, exit codes, configuration, the JSON report, the baseline and fingerprints, SARIF and GitLab output), what it leaves to each release (findings, agent text, cache, default model), deprecations and batched releases.
---
 site/src/SUMMARY.md   |  1 +
 site/src/stability.md | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 site/src/stability.md

diff --git a/site/src/SUMMARY.md b/site/src/SUMMARY.md
index 881eafb..1d6b3db 100644
--- a/site/src/SUMMARY.md
+++ b/site/src/SUMMARY.md
@@ -22,6 +22,7 @@
 
 - [How it works](how-it-works.md)
 - [Limits](limits.md)
+- [Versions and stability](stability.md)
 - [Changelog](changelog.md)
 
 # Reference
diff --git a/site/src/stability.md b/site/src/stability.md
new file mode 100644
index 0000000..3bbd637
--- /dev/null
+++ b/site/src/stability.md
@@ -0,0 +1,33 @@
+# Versions and stability
+
+JevGate follows [Semantic Versioning](https://semver.org). This page says what the version number promises, so a CI job, a script or an agent knows what an upgrade can change.
+
+## Before 1.0
+
+Until 1.0, a minor release (0.18, 0.19, …) can change commands, flags, configuration and output formats, and a patch release (0.18.1) only fixes. Every change is in the [changelog](changelog.md), with what an upgrade re-asks. Pin a version in CI (`version:` in the action, `--version` for `cargo install`) and upgrade on purpose.
+
+## From 1.0
+
+A major release is needed to remove or change the meaning of:
+
+- **Commands and flags**, and the values they accept.
+- **Exit codes**: 0 gate passed, 1 gate failed, 2 run incomplete or invalid.
+- **`jevgate.toml` keys, levels and rule names.** Unknown keys are errors, so removing a key or a rule name would break configurations.
+- **The JSON report** (`--format json`, `.jevgate/latest.json`): its fields keep their names and meanings, and new fields can be added in any release. `schema_version` changes when a field is removed or changes meaning.
+- **`jevgate-baseline.json`** and finding fingerprints: an upgrade must not make accepted findings new. A release that changes how findings are fingerprinted carries the baseline over.
+- **SARIF, GitLab Code Quality and GitHub annotation output**, within what those formats define.
+
+Deprecated flags and keys keep working for at least one minor release, with a warning on stderr, before a major release removes them.
+
+## Not covered
+
+These are judgments or presentation, and any release can change them; the changelog says how:
+
+- **Which findings a rule reports**, their levels, wording, probabilities and next steps. Findings are model judgments composed by code, and improving them is most of what releases do. A rule's `version` changes when its questions or composition change, and its cached answers are asked again.
+- **The agent text** (`--format agent`): it is written for people and coding agents to read. Scripts should read JSON.
+- **Request bodies and the answer cache**: the cache is safe to delete or restore at any version; unmatched entries are simply not used.
+- **The default model**: a release can pin a newer model version, which re-asks every unit once. Set `model` in `jevgate.toml` to keep one.
+
+## Releases
+
+Releases are batched: a minor release collects features and rule changes, and a patch release ships fixes without waiting. Each release publishes binaries, the crate, the GitHub Action's inputs and the Homebrew formula together, and this site is published from the same tag.