docs: Add information on REST API versioning

This isn't too prescriptive, given that so far we've only dealt with
adding new fields. However, it should serve as a guide to alert devs
that this stuff exists and should be a concern.

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
index 66c2cb9a0adb1039d252927030d0219ad54951aa..c311cfe0b5b49147162288a65d25cb57b76eb81b 100644 (file)
--- a/docs/development/contributing.rst
+++ b/docs/development/contributing.rst
@@ -92,6 +92,20 @@ command:
 Modify the created file, removing any irrelevant sections, and include the
 modified file in your change.
 
+API
+---
+
+As discussed in :doc:`releasing`, the API is versioned differently from
+Patchwork itself. Should you make changes to the API, you need to ensure these
+only affect newer versions of the API. Refer to previous changes in the
+``patchwork/api`` directory and to the `Django REST Framework documentation`_
+for more information.
+
+.. important::
+
+    All API changes should be called out in :ref:`release notes
+    <release-notes>` using the ``api`` section.
+
 Submitting Changes
 ------------------
 
@@ -110,3 +124,4 @@ ensure:
 .. _reno: https://docs.openstack.org/developer/reno/
 .. _mailing list: https://ozlabs.org/mailman/listinfo/patchwork
 .. _QEMU guidelines: http://wiki.qemu.org/Contribute/SubmitAPatch
+.. _Django REST Framework documentation: http://www.django-rest-framework.org/api-guide/versioning/

diff --git a/docs/development/releasing.rst b/docs/development/releasing.rst
index d1584704794bf89485985b4168124af5bd205a67..eb33bbf7f17997d86daf7dd99bdbe83ffc3c0113 100644 (file)
--- a/docs/development/releasing.rst
+++ b/docs/development/releasing.rst
@@ -4,6 +4,13 @@ Release Process
 Versioning
 ----------
 
+There are two types of versioning in play in Patchwork: the version for
+Patchwork itself (i.e. the code or *core*) and the version for the `REST
+API <../api/rest>`.
+
+Patchwork Code
+~~~~~~~~~~~~~~
+
 Since version 1.0, Patchwork has implemented a version of `Semantic
 Versioning`__ . To summarise, releases take the format **MAJOR.MINOR.PATCH**
 (or just **MAJOR.MINOR**). We increment:
@@ -20,6 +27,22 @@ to allow backporting of bugfixes or security updates to older versions.
 
 __ http://semver.org/
 
+REST API
+~~~~~~~~
+
+The REST API also uses a variant of *Semantic Versioning*. To summarise, API
+versions take the format **MAJOR.MINOR**. We increment:
+
+1. **MAJOR** version when we make breaking changes to the API. This generally
+   means removing an API or fields in an API.
+
+2. **MINOR** version when we add functionality in a backwards-compatible
+   manner. This generally means adding new fields and endpoint.
+
+These version numbers are exposed via the API and it's possible to request a
+specific version in the URL. Refer to the `API Guide <../api/rest>` for more
+information.
+
 Release Cycle
 -------------