On Fri, 2025-02-07 at 09:59 -0500, Aaron Conole wrote: > Adam Hassick <ahass...@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 <ahass...@iol.unh.edu>
I've some tweaks made here to handle the parse_dependencies -> show_dependencies change, but otherwise LGTM. Reviewed-by: Stephen Finucane <step...@that.guru> > > --- > > Acked-by: Aaron Conole <acon...@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 <step...@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-u...@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 _______________________________________________ Patchwork mailing list Patchwork@lists.ozlabs.org https://lists.ozlabs.org/listinfo/patchwork
