[PATCH 3/5] docs: Add information on REST API versioning
stephen at that.guru
Mon Mar 26 05:28:21 AEDT 2018
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 at that.guru>
docs/development/contributing.rst | 15 +++++++++++++++
docs/development/releasing.rst | 23 +++++++++++++++++++++++
2 files changed, 38 insertions(+)
diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
index e6c06630..76fc1ef0 100644
@@ -92,6 +92,20 @@ command:
Modify the created file, removing any irrelevant sections, and include the
modified file in your change.
+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.
+ All API changes should be called out in :ref:`release notes
+ <release-notes>` using the ``api`` section.
@@ -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 d1584704..eb33bbf7 100644
@@ -4,6 +4,13 @@ Release Process
+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
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.
+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
More information about the Patchwork