[PATCH v3 5/7] docs: Increment API version
Adam Hassick
ahassick at iol.unh.edu
Sat Nov 16 07:40:12 AEDT 2024
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 at 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 --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 at 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 at 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/',
--
2.47.0
More information about the Patchwork
mailing list