| Message ID | 20250130195643.757559-6-ahassick@iol.unh.edu |
|---|---|
| State | Accepted |
| Headers | show |
| Series | Add support for series dependencies | expand |
Adam Hassick <ahassick@iol.unh.edu> writes: > 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> > 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@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@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/',
On Fri, 2025-02-07 at 09:59 -0500, Aaron Conole wrote: > Adam Hassick <ahassick@iol.unh.edu> writes: > > > 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> I've some tweaks made here to handle the parse_dependencies -> show_dependencies change, but otherwise LGTM. Reviewed-by: Stephen Finucane <stephen@that.guru> > > --- > > Acked-by: Aaron Conole <aconole@redhat.com> > > > 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@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@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/', > > _______________________________________________ > Patchwork mailing list > Patchwork@lists.ozlabs.org > https://lists.ozlabs.org/listinfo/patchwork
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@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@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/',
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> --- 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