Skip to content

Commit

Permalink
docs: Versioning policy (#3488)
Browse files Browse the repository at this point in the history
* docs: create `versioning.rst` placeholder

* docs: add link to `roadmap.rst`

* docs: Initial `versioning.rst` draft

Based on discussions in #3454 (comment) and #3454 (comment)

#3454

* docs: fix version number in italics

* docs: add `Version numbers` heading

* docs: add `Deprecation` section

* docs: Clarify upstream breaking -> warning option

#3488 (comment)

* docs: add undoc statement

#3488 (comment)

* docs: Clearly define **Public API**

Intentionally simple, see linked thread for discussion

#3478 (comment)

* docs: Tweak formatting of deprecation section
  • Loading branch information
dangotbanned authored Aug 4, 2024
1 parent 15f1151 commit 95f654f
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 0 deletions.
1 change: 1 addition & 0 deletions doc/about/roadmap.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ The roadmap for Vega-Altair and related projects can be found in
code_of_conduct
governance
citing
versioning
46 changes: 46 additions & 0 deletions doc/about/versioning.rst
Original file line number Diff line number Diff line change
@@ -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/

0 comments on commit 95f654f

Please sign in to comment.