docs: Add VERSIONING.md documentation (#1735)

# Add VERSIONING.md documentation

This PR adds a new `VERSIONING.md` file to the root directory of the
OpenVM repository to document our semantic versioning principles and
backward compatibility guarantees.

## Changes
- Created `VERSIONING.md` with comprehensive documentation of:
  - Semantic versioning approach (major.minor.patch)
  - Core principle: "Patch upgrade should be backward compatible"
  - Backward compatibility guarantees for patch versions
  - Exceptions for purely additive changes
  - Guidelines for patch-level changes

## Ticket
- Linear ticket: **INT-4159**

## Link to Devin run
https://app.devin.ai/sessions/ba99b2c95a5e4506b1d1ed5f42fe570c

## Testing
This is a documentation-only change with no code modifications required.

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>
Co-authored-by: Jonathan Wang <[email protected]>

Author: 3 people

VERSIONING.md

@@ -0,0 +1,57 @@
+# OpenVM Versioning
+
+OpenVM follows the naming convention of [semantic versioning](https://semver.org/) (semver) but with different principles:
+
+* `major`: Only changes upon significant proof system or ISA updates
+* `minor`: Breaking changes where the vkey (`MultiStarkVerifyingKey`) changes
+* `patch`: Backward-compatible changes that preserve vkey compatibility
+
+Due to the security critical nature of the OpenVM codebase, we do _not_ follow semver precisely in the sense that breaking code-level API changes will not always result in a major version upgrade. However we follow the principles of semver where we treat the true API of the codebase to be the verification of the proofs generated by the OpenVM framework.
+
+## Versioning Principles
+
+The core principle of OpenVM versioning is: **"Patch upgrade should be backward compatible"**.
+
+This means if we upgrade from v1.0.0 to v1.0.1, the old verifier of v1.0.0 should be able to verify the new proof generated by v1.0.1. **Crucially, this means the vkey (`MultiStarkVerifyingKey`) does not change across patch versions.**
+
+## Backward Compatibility Guarantees
+
+The following properties must remain fixed across patch versions (changing these requires a minor version upgrade):
+
+1. **vkey (`MultiStarkVerifyingKey` struct)**
+   - This ensures that a patch-upgraded prover (v1.x.y) can generate proofs that the original verifier (v1.x.0) can verify
+
+2. **Commit structures**
+   - `app_vm_commit`, `leaf_vm_commit`, `internal_vm_commit`
+   - This includes both the VM itself and the serialization (how the commit is computed)
+
+3. **`VmConfig` format**
+
+4. **Build toolchain**
+   - RISC-V custom instructions
+   - Transpiler
+   - ISA
+   - And thus the resulting `VmExe`
+
+5. **Output of the `prove` command (CLI+SDK)**
+   - The proof format (struct itself and the content)
+
+## Exceptions
+
+Changes that are purely additive without modifying existing objects are exceptions to the above rules and can be included in patch versions. Examples include:
+
+- Adding a new instruction
+- Adding a new prove type (STARK)
+- Adding a new extension (new `StarkVerifyingKey` for a new circuit)
+
+While rare and ideally avoided, we reserve the option to change formatting of certain outputs or structs (e.g., `VmConfig` or `VmExe`) in a patch version if the change is purely cosmetic and a migration tool is provided to easily convert from the old format to the new format.
+
+## Patch-level Changes
+
+Other changes that aren't security critical and don't modify any of the above components can be included in patch upgrades:
+
+- Prover improvements
+- VirtualMachine optimizations
+- Executor enhancements
+- SDK and CLI updates
+- Guest library changes