diff mbox series

[v2,5/7] docs: Increment API version

Message ID 20240730210523.313101-6-ahassick@iol.unh.edu
State New
Headers show
Series Add support for series dependencies | expand

Commit Message

Adam Hassick July 30, 2024, 9:05 p.m. UTC 
* Increment the API version from v1.3 to v1.4.
* Update schema documentation to reflect the version change.
* Add blurb documenting the "Depends-on" tag to the usage overview.

Signed-off-by: Adam Hassick <ahassick@iol.unh.edu>
---
 docs/api/rest/index.rst              | 42 +++++++++++++++-------------
 docs/api/rest/schemas/v1.3.rst       |  4 +--
 docs/api/rest/schemas/v1.4.rst       |  5 ++++
 docs/api/schemas/generate-schemas.py |  4 +--
 docs/api/schemas/patchwork.j2        | 18 ++++++++++++
 docs/usage/overview.rst              | 11 ++++++++
 patchwork/urls.py                    | 10 +++++--
 7 files changed, 67 insertions(+), 27 deletions(-)
 create mode 100644 docs/api/rest/schemas/v1.4.rst
diff mbox series

Patch

diff --git a/docs/api/rest/index.rst b/docs/api/rest/index.rst
index 67022e6..cdf9104 100644
--- a/docs/api/rest/index.rst
+++ b/docs/api/rest/index.rst
@@ -8,7 +8,7 @@  This guide provides an overview of how one can interact with the REST API. For
 detailed information on type and response format of the various resources
 exposed by the API, refer to the web browsable API. This can be found at:
 
-    https://patchwork.example.com/api/1.3/
+    https://patchwork.example.com/api/1.4/
 
 where `patchwork.example.com` refers to the URL of your Patchwork instance.
 
@@ -57,16 +57,16 @@  Patchwork instance hosted at `patchwork.example.com`, run:
 
 .. code-block:: shell
 
-    $ curl -s 'https://patchwork.example.com/api/1.3/' | python -m json.tool
+    $ curl -s 'https://patchwork.example.com/api/1.4/' | python -m json.tool
     {
-        "bundles": "https://patchwork.example.com/api/1.3/bundles/",
-        "covers": "https://patchwork.example.com/api/1.3/covers/",
-        "events": "https://patchwork.example.com/api/1.3/events/",
-        "patches": "https://patchwork.example.com/api/1.3/patches/",
-        "people": "https://patchwork.example.com/api/1.3/people/",
-        "projects": "https://patchwork.example.com/api/1.3/projects/",
-        "series": "https://patchwork.example.com/api/1.3/series/",
-        "users": "https://patchwork.example.com/api/1.3/users/"
+        "bundles": "https://patchwork.example.com/api/1.4/bundles/",
+        "covers": "https://patchwork.example.com/api/1.4/covers/",
+        "events": "https://patchwork.example.com/api/1.4/events/",
+        "patches": "https://patchwork.example.com/api/1.4/patches/",
+        "people": "https://patchwork.example.com/api/1.4/people/",
+        "projects": "https://patchwork.example.com/api/1.4/projects/",
+        "series": "https://patchwork.example.com/api/1.4/series/",
+        "users": "https://patchwork.example.com/api/1.4/users/"
     }
 
 
@@ -82,14 +82,14 @@  well-supported. To repeat the above example using `requests`:, run
     >>> r = requests.get('https://patchwork.example.com/api/1.3/')
     >>> print(json.dumps(r.json(), indent=2))
     {
-        "bundles": "https://patchwork.example.com/api/1.3/bundles/",
-        "covers": "https://patchwork.example.com/api/1.3/covers/",
-        "events": "https://patchwork.example.com/api/1.3/events/",
-        "patches": "https://patchwork.example.com/api/1.3/patches/",
-        "people": "https://patchwork.example.com/api/1.3/people/",
-        "projects": "https://patchwork.example.com/api/1.3/projects/",
-        "series": "https://patchwork.example.com/api/1.3/series/",
-        "users": "https://patchwork.example.com/api/1.3/users/"
+        "bundles": "https://patchwork.example.com/api/1.4/bundles/",
+        "covers": "https://patchwork.example.com/api/1.4/covers/",
+        "events": "https://patchwork.example.com/api/1.4/events/",
+        "patches": "https://patchwork.example.com/api/1.4/patches/",
+        "people": "https://patchwork.example.com/api/1.4/people/",
+        "projects": "https://patchwork.example.com/api/1.4/projects/",
+        "series": "https://patchwork.example.com/api/1.4/series/",
+        "users": "https://patchwork.example.com/api/1.4/users/"
     }
 
 Tools like `curl` and libraries like `requests` can be used to build anything
@@ -108,7 +108,7 @@  Versioning
 ----------
 
 By default, all requests will receive the latest version of the API: currently
-``1.3``:
+``1.4``:
 
 .. code-block:: http
 
@@ -119,7 +119,7 @@  changes breaking your application:
 
 .. code-block:: http
 
-    GET /api/1.3 HTTP/1.1
+    GET /api/1.4 HTTP/1.1
 
 Older API versions will be deprecated and removed over time. For more
 information, refer to :ref:`rest-api-versions`.
@@ -275,6 +275,7 @@  Supported Versions
    1.1, 2.1, ✓
    1.2, 2.2, ✓
    1.3, 3.1, ✓
+   1.4, unreleased, ✓
 
 Further information about this and more can typically be found in
 :doc:`the release notes </releases/index>`.
@@ -292,6 +293,7 @@  Auto-generated schema documentation is provided below.
    /api/rest/schemas/v1.1
    /api/rest/schemas/v1.2
    /api/rest/schemas/v1.3
+   /api/rest/schemas/v1.4
 
 .. Links
 
diff --git a/docs/api/rest/schemas/v1.3.rst b/docs/api/rest/schemas/v1.3.rst
index 17a4421..6bbf1a5 100644
--- a/docs/api/rest/schemas/v1.3.rst
+++ b/docs/api/rest/schemas/v1.3.rst
@@ -1,5 +1,5 @@ 
-API v1.3 (latest)
-=================
+API v1.3
+========
 
 .. openapi:: ../../schemas/v1.3/patchwork.yaml
    :examples:
diff --git a/docs/api/rest/schemas/v1.4.rst b/docs/api/rest/schemas/v1.4.rst
new file mode 100644
index 0000000..11e34f6
--- /dev/null
+++ b/docs/api/rest/schemas/v1.4.rst
@@ -0,0 +1,5 @@ 
+API v1.4 (latest)
+=================
+
+.. openapi:: ../../schemas/v1.4/patchwork.yaml
+   :examples:
diff --git a/docs/api/schemas/generate-schemas.py b/docs/api/schemas/generate-schemas.py
index 14b7414..52008df 100755
--- a/docs/api/schemas/generate-schemas.py
+++ b/docs/api/schemas/generate-schemas.py
@@ -14,8 +14,8 @@  except ImportError:
     yaml = None
 
 ROOT_DIR = os.path.dirname(os.path.realpath(__file__))
-VERSIONS = [(1, 0), (1, 1), (1, 2), (1, 3), None]
-LATEST_VERSION = (1, 3)
+VERSIONS = [(1, 0), (1, 1), (1, 2), (1, 3), (1, 4), None]
+LATEST_VERSION = (1, 4)
 
 
 def generate_schemas():
diff --git a/docs/api/schemas/patchwork.j2 b/docs/api/schemas/patchwork.j2
index 516fbe8..67e9253 100644
--- a/docs/api/schemas/patchwork.j2
+++ b/docs/api/schemas/patchwork.j2
@@ -2699,6 +2699,24 @@  components:
             $ref: '#/components/schemas/PatchEmbedded'
           readOnly: true
           uniqueItems: true
+{% if version >= (1, 4) %}
+        dependencies:
+          title: Dependencies
+          type: array
+          items:
+            type: string
+            format: url
+          readOnly: true
+          uniqueItems: true
+        dependents:
+          title: Dependents
+          type: array
+          items:
+            type: string
+            format: url
+          readOnly: true
+          uniqueItems: true
+{% endif %}
     User:
       type: object
       title: User
diff --git a/docs/usage/overview.rst b/docs/usage/overview.rst
index 297569e..a6aa653 100644
--- a/docs/usage/overview.rst
+++ b/docs/usage/overview.rst
@@ -139,6 +139,17 @@  the email. The following tags are available on a standard Patchwork install:
 
       Reviewed-by: Stephen Finucane <stephen@that.guru>
 
+Patchwork includes an optional built-in tag for declaring dependencies between
+series. The message ID of a patch or a cover letter, or the web URL to a patch
+or a series may be used to indicate a dependency. This may be included in the
+cover letter or any patch file:
+
+``Depends-on:``
+  For example::
+
+    Depends-on: <20240726221429.221611-1-user@example.com>
+    Depends-on: https://pw.example.com/project/myproject/list?series=1234
+
 The available tags, along with the significance of said tags, varies from
 project to project and Patchwork instance to Patchwork instance. The `kernel
 project documentation`__ provides an overview of the supported tags for the
diff --git a/patchwork/urls.py b/patchwork/urls.py
index ecd3668..11cd8e7 100644
--- a/patchwork/urls.py
+++ b/patchwork/urls.py
@@ -347,12 +347,16 @@  if settings.ENABLE_REST_API:
 
     urlpatterns += [
         re_path(
-            r'^api/(?:(?P<version>(1.0|1.1|1.2|1.3))/)?', include(api_patterns)
+            r'^api/(?:(?P<version>(1.0|1.1|1.2|1.3|1.4))/)?',
+            include(api_patterns),
         ),
         re_path(
-            r'^api/(?:(?P<version>(1.1|1.2|1.3))/)?', include(api_1_1_patterns)
+            r'^api/(?:(?P<version>(1.1|1.2|1.3|1.4))/)?',
+            include(api_1_1_patterns),
+        ),
+        re_path(
+            r'^api/(?:(?P<version>(1.3|1.4))/)?', include(api_1_3_patterns)
         ),
-        re_path(r'^api/(?:(?P<version>(1.3))/)?', include(api_1_3_patterns)),
         # token change
         path(
             'user/generate-token/',