From 95f654fcd036069e1101883d176ec67c6f13fa25 Mon Sep 17 00:00:00 2001
From: Dan Redding <125183946+dangotbanned@users.noreply.github.com>
Date: Sun, 4 Aug 2024 15:10:47 +0100
Subject: [PATCH] docs: Versioning policy (#3488)

* docs: create `versioning.rst` placeholder

* docs: add link to `roadmap.rst`

* 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

* docs: fix version number in italics

* docs: add `Version numbers` heading

* docs: add `Deprecation` section

* docs: Clarify upstream breaking -> warning option

https://github.com/vega/altair/pull/3488#issuecomment-2259015194

* docs: add undoc statement

https://github.com/vega/altair/pull/3488#issuecomment-2258742629

* docs: Clearly define **Public API**

Intentionally simple, see linked thread for discussion

https://github.com/vega/altair/discussions/3478#discussioncomment-10059436

* docs: Tweak formatting of deprecation section
---
 doc/about/roadmap.rst    |  1 +
 doc/about/versioning.rst | 46 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 doc/about/versioning.rst

diff --git a/doc/about/roadmap.rst b/doc/about/roadmap.rst
index 50dd29feb..1916cd9a6 100644
--- a/doc/about/roadmap.rst
+++ b/doc/about/roadmap.rst
@@ -13,3 +13,4 @@ The roadmap for Vega-Altair and related projects can be found in
    code_of_conduct
    governance
    citing
+   versioning
diff --git a/doc/about/versioning.rst b/doc/about/versioning.rst
new file mode 100644
index 000000000..f4855ed78
--- /dev/null
+++ b/doc/about/versioning.rst
@@ -0,0 +1,46 @@
+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_.
+
+Public API
+----------
+Functionality documented in :ref:`api` defines the Vega-Altair public API.
+
+Version numbers
+---------------
+
+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_.
+
+Deprecation
+-----------
+Deprecation warnings may be introduced in **MAJOR** and **MINOR** versions, 
+but the removal of deprecated functionality will not occur until *at least* the next **MAJOR** version.
+
+For upstream breaking changes that trigger a **MAJOR** version, 
+we *may* provide a deprecation warning if we consider the change especially disruptive.
+
+Starting in version ``5.4.0``, all deprecation warnings *must* specify:
+
+* the version number they were introduced
+
+Where possible, deprecation warnings *may* specify:
+
+* an alternative function/method/parameter/class to use instead
+* an explanation for why this change had to be made
+
+Deprecated functionality *may* be removed from the Vega-Altair documentation, if there is a 
+suitable replacement and we believe inclusion of both could confuse new users.
+
+.. _Vega-Lite: https://github.com/vega/vega-lite
+.. _SemVer: https://semver.org/
\ No newline at end of file