[PATCH v2 5/7] docs: Increment API version
Stephen Finucane
stephen at that.guru
Fri Nov 1 09:36:22 AEDT 2024
On Tue, 2024-07-30 at 17:05 -0400, Adam Hassick wrote:
> * 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>
Fine by me.
Reviewed-by: Stephen Finucane <stephen at that.guru>
> ---
> 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/',
More information about the Patchwork
mailing list