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 <ahass...@iol.unh.edu>
Fine by me. Reviewed-by: Stephen Finucane <step...@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 <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 may be included in the > +cover letter or any patch file: > + > +``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
