From 4c58fc54688f5d12a909d00b93f04666e148f33e Mon Sep 17 00:00:00 2001 From: Adam Hassick Date: Thu, 30 Jan 2025 14:56:40 -0500 Subject: [PATCH] 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 Acked-by: Aaron Conole [stephenfin: Tweak docs] Signed-off-by: Stephen Finucane --- 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 | 16 +++++++++++ patchwork/urls.py | 10 +++++-- 7 files changed, 77 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 67022e6f..cdf91044 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 `. @@ -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 17a4421a..6bbf1a56 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 00000000..11e34f6a --- /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 14b74147..52008dff 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 516fbe88..f37d3213 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) %} + 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 297569ec..539de9ca 100644 --- 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 ecd3668d..11cd8e7c 100644 --- a/patchwork/urls.py +++ b/patchwork/urls.py @@ -347,12 +347,16 @@ if settings.ENABLE_REST_API: urlpatterns += [ re_path( - r'^api/(?:(?P(1.0|1.1|1.2|1.3))/)?', include(api_patterns) + r'^api/(?:(?P(1.0|1.1|1.2|1.3|1.4))/)?', + include(api_patterns), ), re_path( - r'^api/(?:(?P(1.1|1.2|1.3))/)?', include(api_1_1_patterns) + r'^api/(?:(?P(1.1|1.2|1.3|1.4))/)?', + include(api_1_1_patterns), + ), + re_path( + r'^api/(?:(?P(1.3|1.4))/)?', include(api_1_3_patterns) ), - re_path(r'^api/(?:(?P(1.3))/)?', include(api_1_3_patterns)), # token change path( 'user/generate-token/', -- 2.47.3