From 934517abafdd0ec236011d352fa6cab1e5024415 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Sat, 20 Jul 2024 20:52:14 +0100
Subject: [PATCH] docs: Initial `versioning.rst` draft

Based on discussions in https://github.com/vega/altair/issues/3454#issuecomment-2201979525 and https://github.com/vega/altair/issues/3454#issuecomment-2232623054

https://github.com/vega/altair/issues/3454
---
 doc/about/versioning.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/about/versioning.rst b/doc/about/versioning.rst
index e69de29bb..2ad27070c 100644
--- a/doc/about/versioning.rst
+++ b/doc/about/versioning.rst
@@ -0,0 +1,19 @@
+Versioning
+==========
+Vega-Altair has historically released major versions that coincide with those of Vega-Lite_.
+
+As the projects have matured, and major versions become less frequent, there has been a growing need to introduce breaking changes between these major versions.
+Such changes would allow Vega-Altair to address technical debt and improve upon API ergonomics.
+
+To ensure future releases clearly communicate changes, Vega-Altair will be working towards adopting SemVer_.
+
+A Vega-Altair release number is composed of ``MAJOR.MINOR.PATCH``.
+
+* Backward incompatible API changes increment **MAJOR** version (`4.2.2` - `5.0.0`)
+* New backward compatible functionality increment **MINOR** version (`5.2.0` - `5.3.0`)
+* Backward compatible bug fixes increment **PATCH** version (`5.1.1` - `5.1.2`)
+
+**MAJOR** versions will *likely* continue to increase with a **MAJOR** increment to Vega-Lite_.
+
+.. _Vega-Lite: https://github.com/vega/vega-lite
+.. _SemVer: https://semver.org/
\ No newline at end of file