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 <ahassick@iol.unh.edu>
Acked-by: Aaron Conole <aconole@redhat.com>
[stephenfin: Tweak docs]
Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/api/rest/index.rst b/docs/api/rest/index.rst
index 67022e6f3f07734d97512f7a56117bab22a64c28..cdf910444d25964cd3074b1775fa6e9258c92212 100644 (file)
--- 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 17a4421aeedeec44af911004df7fcab9f4ece2b7..6bbf1a560784e87e9c6b416754c8ae28de885ab1 100644 (file)
--- 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 (file)
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 14b741473142284e051204868ad44383c6e299c5..52008dffdcd9bce5fa6c7aa9362c44c4248ad229 100755 (executable)
--- 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 516fbe88d8a24c1707bf38101a998a35c8adec52..f37d3213e33b7c3a8163499bc01d6ea86e5372c1 100644 (file)
--- a/docs/api/schemas/patchwork.j2
+++ b/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

diff --git a/docs/usage/overview.rst b/docs/usage/overview.rst
index 297569ec3404b3506005c55fe066a9bb1a3e46cb..539de9ca3113e144ace1a5f781ce46abb777a47e 100644 (file)
--- a/docs/usage/overview.rst
+++ b/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: <20240726221429.221611-1-user@example.com>
+    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

diff --git a/patchwork/urls.py b/patchwork/urls.py
index ecd3668de84ba279b2e07d3fcf4d7d179e787673..11cd8e7c152ab5d66a1ad4422b40de86d5a210aa 100644 (file)
--- 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/',