[Issue #506] Allow linking between series

docs/api/rest/index.rst

@@ -43,6 +43,11 @@ If all you want is reference guides, skip straight to :ref:`rest-api-schemas`.
    The API version was bumped to v1.3 in Patchwork v3.1. The older APIs are
    still supported. For more information, refer to :ref:`rest-api-versions`.
 
+.. versionchanged:: 3.2
+
+   The API version was bumped to v1.4 in Patchwork v3.2. The older APIs are
+   still supported. For more information, refer to :ref:`rest-api-versions`.
+
 Getting Started
 ---------------
 
@@ -79,7 +84,7 @@ well-supported. To repeat the above example using `requests`:, run
     $ python
     >>> import json
     >>> import requests
-    >>> r = requests.get('https://patchwork.example.com/api/1.3/')
+    >>> r = requests.get('https://patchwork.example.com/api/1.4/')
     >>> print(json.dumps(r.json(), indent=2))
     {
         "bundles": "https://patchwork.example.com/api/1.4/bundles/",

docs/api/schemas/latest/patchwork.yaml

@@ -1203,7 +1203,7 @@ paths:
           title: ID
           type: integer
     get:
-      summary: Show a series.
+      summary: Return the details of a series.
       description: |
         Retrieve a series by its ID.
         A series is a collection of patches with an optional cover letter.
@@ -1223,6 +1223,128 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
         - series
+    patch:
+      summary: Partially update a series.
+      description: |
+        Only updates the 'supersedes' field of a series. Replaces the whole set
+        of superseded series.
+
+        ::
+
+          Instance:
+              instance.supersedes = [
+                  'http://example.com/api/series/1/',
+                  'http://example.com/api/series/2/',
+                  'http://example.com/api/series/5/'
+              ]
+
+          Request:
+              PATCH {
+                  "supersedes": [
+                      'http://example.com/api/series/1/',
+                      'http://example.com/api/series/8/'
+                  ]
+              }
+
+          Result:
+              instance.supersedes = [
+                  'http://example.com/api/series/1/',
+                  'http://example.com/api/series/8/'
+              ]
+      security:
+        - basicAuth: []
+        - apiKeyAuth: []
+      requestBody:
+        $ref: '#/components/requestBodies/SeriesUpdate'
+      operationId: series_partial_update
+      responses:
+        '200':
+          description: 'Updated series'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Series'
+        '400':
+          description: 'Bad request'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: 'Forbidden'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: 'Not found'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      tags:
+        - series
+    put:
+      summary: Update a series.
+      description: |
+        Only updates the 'supersedes' field of a series. Replaces the whole set
+        of superseded series.
+
+        ::
+
+          Instance:
+              instance.supersedes = [
+                  'http://example.com/api/series/1/',
+                  'http://example.com/api/series/2/',
+                  'http://example.com/api/series/5/'
+              ]
+
+          Request:
+              PUT {
+                  "supersedes": [
+                      'http://example.com/api/series/1/',
+                      'http://example.com/api/series/8/'
+                  ]
+              }
+
+          Result:
+              instance.supersedes = [
+                  'http://example.com/api/series/1/',
+                  'http://example.com/api/series/8/'
+              ]
+      security:
+        - basicAuth: []
+        - apiKeyAuth: []
+      requestBody:
+        $ref: '#/components/requestBodies/SeriesUpdate'
+      operationId: series_update
+      responses:
+        '200':
+          description: 'Updated series'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Series'
+        '400':
+          description: 'Bad request'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: 'Forbidden'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: 'Not found'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      tags:
+        - series
   /api/users:
     get:
       summary: List users.
@@ -1506,6 +1628,14 @@ components:
         application/x-www-form-urlencoded:
           schema:
             $ref: '#/components/schemas/Project'
+    SeriesUpdate:
+      required: true
+      description: |
+        A series.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/SeriesUpdate'
     User:
       required: true
       description: |
@@ -2528,6 +2658,24 @@ components:
         show_dependencies:
           title: Whether the parse dependencies feature is enabled.
           type: boolean
+        show_series_versions:
+          title: Whether series versioning is enabled.
+          type: boolean
+    SeriesUpdate:
+      type: object
+      title: SeriesUpdate
+      description: |
+        Updatable fields af a series.
+      properties:
+        supersedes:
+          type: array
+          items:
+            oneOf:
+              - type: string
+                format: uri
+              - type: string
+                format: uri-reference
+          description: Series deprecated by the current series
     Series:
       type: object
       title: Series
@@ -2613,15 +2761,30 @@ components:
           type: array
           items:
             type: string
-            format: url
+            format: uri
           readOnly: true
           uniqueItems: true
         dependents:
           title: Dependents
           type: array
           items:
             type: string
-            format: url
+            format: uri
+          readOnly: true
+          uniqueItems: true
+        supersedes:
+          title: Series deprecated by this series
+          type: array
+          items:
+            type: string
+            format: uri
+          uniqueItems: true
+        superseded:
+          title: Series that superseded this series
+          type: array
+          items:
+            type: string
+            format: uri
           readOnly: true
           uniqueItems: true
     User: