docs: Add feature info and increment API version

The following patch will add the generated schema files as they are very
large.

* 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 <[email protected]>
Acked-by: Aaron Conole <[email protected]>
[stephenfin: Tweak docs]
Signed-off-by: Stephen Finucane <[email protected]>

Author: loudonlune

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
 

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:

docs/api/rest/schemas/v1.4.rst

@@ -0,0 +1,5 @@
+API v1.4 (latest)
+=================
+
+.. openapi:: ../../schemas/v1.4/patchwork.yaml
+   :examples:

docs/api/schemas/generate-schemas.py

@@ -14,8 +14,8 @@
     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():

docs/api/schemas/patchwork.j2

@@ -2616,6 +2616,11 @@ components:
         commit_url_format:
           title: Web SCM URL format for a particular commit
           type: string
+{% endif %}
+{% if version >= (1, 4) %}
+        show_dependencies:
+          title: Whether the parse dependencies feature is enabled.
+          type: boolean
 {% endif %}
     Series:
       type: object
@@ -2699,6 +2704,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

docs/usage/overview.rst

@@ -144,6 +144,22 @@ project to project and Patchwork instance to Patchwork instance. The `kernel
 project documentation`__ provides an overview of the supported tags for the
 Linux kernel project.
 
+Patchwork also includes support for an additional, Patchwork-specific tag for
+declaring dependencies between series. The tag may be included in the cover
+letter or any patch of a series and should reference the message ID of a patch
+or a cover letter or the web URL to a patch or a series:
+
+``Depends-on:``
+  For example::
+
+    Depends-on: <[email protected]>
+    Depends-on: https://pw.example.com/project/myproject/list?series=1234
+
+.. note::
+
+    Series dependencies are not shown by default. This can be changed by
+    enabling the ``show_dependencies`` flag for each project.
+
 __ https://www.kernel.org/doc/html/latest/process/submitting-patches.html
 
 Checks

patchwork/urls.py

@@ -347,12 +347,16 @@
 
     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/',