Add manual chapter "Versioning and compatibility"

README.md

@@ -15,9 +15,6 @@ To install the latest release of Hy, just use the command `pip3 install
 --user hy`. Then you can start an interactive read-eval-print loop (REPL) with
 the command `hy`, or run a Hy program with `hy myprogram.hy`.
 
-Hy is tested on all released and currently maintained versions of CPython (on
-Linux, Windows, and Mac OS), and on recent versions of PyPy and Pyodide.
-
 * [The Hy homepage](http://hylang.org)
 * [Try Hy with a web console](http://hylang.org/try-hy)
 

docs/index.rst

@@ -14,20 +14,18 @@ Hy is a Lisp dialect that's embedded in Python. Since Hy transforms its Lisp
 code into Python abstract syntax tree (AST) objects, you have the whole
 beautiful world of Python at your fingertips, in Lisp form.
 
-.. Changes to the below paragraphs should be mirrored on Hy's homepage
+.. Changes to the below paragraph should be mirrored on Hy's homepage
    and the README.
 
 To install the latest release of Hy, just use the command ``pip3 install
 --user hy``. Then you can start an interactive read-eval-print loop (REPL) with
 the command ``hy``, or run a Hy program with ``hy myprogram.hy``.
 
-Hy is tested on all released and currently maintained versions of CPython (on
-Linux, Windows, and Mac OS), and on recent versions of PyPy and Pyodide.
-
 .. toctree::
    :maxdepth: 3
 
    whyhy
+   versioning
    tutorial
    syntax
    semantics

docs/tutorial.rst

@@ -401,14 +401,6 @@ you have no interest in writing your own Python code, because it will introduce
 you to the semantics, and you'll need a reading knowledge of Python syntax to
 understand example code for Python libraries.
 
-Refer to the rest of this manual for Hy-specific features. Like Hy itself, the
-manual is incomplete, but :ref:`contributions <hacking>` are always welcome.
-See `the wiki <https://github.com/hylang/hy/wiki/Compatibility-tips>`_ for tips
+Refer to the rest of this manual for Hy-specific features. See `the wiki <https://github.com/hylang/hy/wiki/Compatibility-tips>`_ for tips
 on getting Hy to work with other software. For an official full-blown example
 Hy program, see `Infinitesimal Quest 2 + ε <http://hylang.org/simalq>`_.
-
-Bear in mind that Hy is still unstable, and with each release along the
-way to Hy 1.0, there are new breaking changes. Refer to `the NEWS file
-<https://github.com/hylang/hy/blob/master/NEWS.rst>`_ for how to update your
-code when you upgrade Hy, and be sure you're reading the version of this manual
-(shown at the top of each page) that matches the version of Hy you're running.

docs/versioning.rst

@@ -0,0 +1,9 @@
+============================
+Versioning and compatibility
+============================
+
+Starting with Hy 1.0.0, Hy is `semantically versioned <https://semver.org>`_. Refer to `the NEWS file <https://github.com/hylang/hy/blob/master/NEWS.rst>`_ for a summary of user-visible changes brought on by each version, and how to update your code in case of breaking changes. Be sure you're reading the version of this manual (shown at the top of each page) that matches the version of Hy you're running.
+
+Hy is tested on `all released and currently maintained versions of CPython <https://devguide.python.org/versions>`_ (on Linux, Windows, and Mac OS), and on recent versions of PyPy and Pyodide. We usually find that for Hy, unlike most Python packages, we need to change things to fully support each new 3.x release of Python. We may drop compatibility with a version of Python after the CPython guys cease maintaining it, and note that we construe such a change as non-breaking, so we won't bump Hy's major version for it. But we will at least bump the minor version, and ``python_requires`` in Hy's ``setup.py`` should prevent you from installing a Hy version that won't work with your Python version.
+
+Starting with Hy 1.0.0, each version of Hy also has a nickname, such as "Afternoon Review". Nicknames are used in alphabetical order, with a nickname starting with "Z" then wrapping around to "A". Nicknames are provided mostly for the amusement of the maintainer, but can be useful as a conspicuous sign that you're not using the version you expected.