[PATCH v4 5/7] docs: Add feature info and increment API version
Adam Hassick
ahassick at iol.unh.edu
Fri Jan 31 06:56:40 AEDT 2025
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 | 23 +++++++++++++++
docs/usage/overview.rst | 13 +++++++++
patchwork/urls.py | 10 +++++--
7 files changed, 74 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..1ce1c6a 100644
--- 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) %}
+ parse_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 297569e..8a81692 100644
--- a/docs/usage/overview.rst
+++ b/docs/usage/overview.rst
@@ -139,6 +139,19 @@ 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 tag is disabled for
+projects by default, and may be enabled by setting the ``parse_dependencies``
+flag to ``True``. When enabled, this may be included in the cover letter or any
+patch file of a series to declare a dependency:
+
+``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.48.1
More information about the Patchwork
mailing list