REST: Add patch relations

View relations and add/update/delete them as a maintainer. Maintainers
can only create relations of patches which are part of a project they
maintain. Because this is a writable many-many nested relationship, it
behaves a little unusually. In short:

- All operations use PATCH to the 'related' field of a patch

- To relate a patch to another patch, say 7 to 19, either:

    PATCH /api/patch/7  related := [19]
    PATCH /api/patch/19 related := [7]

- To delete a patch from a relation, say 1, 21 and 42 are related but we
  only want it to be 1 and 42:

    PATCH /api/patch/21 related := []

  * You _cannot_ remove a patch from a relation by patching another
    patch in the relation: I'm trying to avoid read-modify-write loops.

  * Relations that would be left with just 1 patch are deleted. This is
    only ensured in the API - the admin interface will let you do this.

- Break-before-make: if you have [1, 12, 24] and [7, 15, 42] and you want
  to end up with [1, 12, 15, 42], you have to remove 15 from the second
  relation first:

    PATCH /api/patch/1 related := [15] will fail with 409 Conflict.

  Instead do:

    PATCH /api/patch/15 related := []
    PATCH /api/patch/1  related := [15]
       -> 200 OK, [1, 12, 15, 42] and [7, 42] are the resulting relations

Signed-off-by: Mete Polat <metepolat2000@gmail.com>
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Daniel Axtens <dja@axtens.net>

4 files changed, 166 insertions, 0 deletions

diff --git a/docs/api/schemas/latest/patchwork.yaml b/docs/api/schemas/latest/patchwork.yaml
index 4cee151..13cdc9c 100644
--- a/docs/api/schemas/latest/patchwork.yaml
+++ b/docs/api/schemas/latest/patchwork.yaml
@@ -352,6 +352,7 @@ paths:
               - patch-created
               - patch-completed
               - patch-state-changed
+              - patch-relation-changed
               - patch-delegated
               - check-created
               - series-created
@@ -390,6 +391,7 @@ paths:
                     - $ref: '#/components/schemas/EventPatchCreated'
                     - $ref: '#/components/schemas/EventPatchCompleted'
                     - $ref: '#/components/schemas/EventPatchStateChanged'
+                    - $ref: '#/components/schemas/EventPatchRelationChanged'
                     - $ref: '#/components/schemas/EventPatchDelegated'
                     - $ref: '#/components/schemas/EventCheckCreated'
                     - $ref: '#/components/schemas/EventSeriesCreated'
@@ -403,6 +405,8 @@ paths:
                         '#/components/schemas/EventPatchCompleted'
                       patch-state-changed: >
                         '#/components/schemas/EventPatchStateChanged'
+                      patch-relation-changed: >
+                        '#/components/schemas/EventPatchRelationChanged'
                       patch-delegated: >
                         '#/components/schemas/EventPatchDelegated'
                       check-created: '#/components/schemas/EventCheckCreated'
@@ -552,6 +556,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
       tags:
         - patches
     put:
@@ -595,6 +605,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
       tags:
         - patches
   /api/patches/{id}/comments/:
@@ -1721,6 +1737,24 @@ components:
                 current_state:
                   title: Current state
                   type: string
+    EventPatchRelationChanged:
+      allOf:
+        - $ref: '#/components/schemas/EventBase'
+        - type: object
+          properties:
+            category:
+              enum:
+                - patch-relation-changed
+            payload:
+              properties:
+                patch:
+                  $ref: '#/components/schemas/PatchEmbedded'
+                previous_relation:
+                  title: Previous relation
+                  type: string
+                current_relation:
+                  title: Current relation
+                  type: string
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
@@ -1893,6 +1927,11 @@ components:
           items:
             type: string
           readOnly: true
+        related:
+          title: Relations
+          type: array
+          items:
+            type: string
     PatchDetail:
       allOf:
         - $ref: '#/components/schemas/PatchList'
@@ -1943,6 +1982,11 @@ components:
           title: Delegate
           type: integer
           nullable: true
+        related:
+          title: Relations
+          type: array
+          items:
+            type: string
     Person:
       type: object
       properties:
diff --git a/docs/api/schemas/patchwork.j2 b/docs/api/schemas/patchwork.j2
index c2f5ea6..bd714d5 100644
--- a/docs/api/schemas/patchwork.j2
+++ b/docs/api/schemas/patchwork.j2
@@ -359,6 +359,9 @@ paths:
               - patch-created
               - patch-completed
               - patch-state-changed
+{% if version >= (1, 2) %}
+              - patch-relation-changed
+{% endif %}
               - patch-delegated
               - check-created
               - series-created
@@ -397,6 +400,9 @@ paths:
                     - $ref: '#/components/schemas/EventPatchCreated'
                     - $ref: '#/components/schemas/EventPatchCompleted'
                     - $ref: '#/components/schemas/EventPatchStateChanged'
+{% if version >= (1, 2) %}
+                    - $ref: '#/components/schemas/EventPatchRelationChanged'
+{% endif %}
                     - $ref: '#/components/schemas/EventPatchDelegated'
                     - $ref: '#/components/schemas/EventCheckCreated'
                     - $ref: '#/components/schemas/EventSeriesCreated'
@@ -410,6 +416,10 @@ paths:
                         '#/components/schemas/EventPatchCompleted'
                       patch-state-changed: >
                         '#/components/schemas/EventPatchStateChanged'
+{% if version >= (1, 2) %}
+                      patch-relation-changed: >
+                        '#/components/schemas/EventPatchRelationChanged'
+{% endif %}
                       patch-delegated: >
                         '#/components/schemas/EventPatchDelegated'
                       check-created: '#/components/schemas/EventCheckCreated'
@@ -561,6 +571,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+{% if version >= (1, 2) %}
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+{% endif %}
       tags:
         - patches
     put:
@@ -604,6 +622,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+{% if version >= (1, 2) %}
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+{% endif %}
       tags:
         - patches
   /api/{{ version_url }}patches/{id}/comments/:
@@ -1777,6 +1803,26 @@ components:
                 current_state:
                   title: Current state
                   type: string
+{% if version >= (1, 1) %}
+    EventPatchRelationChanged:
+      allOf:
+        - $ref: '#/components/schemas/EventBase'
+        - type: object
+          properties:
+            category:
+              enum:
+                - patch-relation-changed
+            payload:
+              properties:
+                patch:
+                  $ref: '#/components/schemas/PatchEmbedded'
+                previous_relation:
+                  title: Previous relation
+                  type: string
+                current_relation:
+                  title: Current relation
+                  type: string
+{% endif %}
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
@@ -1955,6 +2001,13 @@ components:
           items:
             type: string
           readOnly: true
+{% if version >= (1, 2) %}
+        related:
+          title: Relations
+          type: array
+          items:
+            type: string
+{% endif %}
     PatchDetail:
       allOf:
         - $ref: '#/components/schemas/PatchList'
@@ -2005,6 +2058,13 @@ components:
           title: Delegate
           type: integer
           nullable: true
+{% if version >= (1, 2) %}
+        related:
+          title: Relations
+          type: array
+          items:
+            type: string
+{% endif %}
     Person:
       type: object
       properties:
diff --git a/docs/api/schemas/v1.1/patchwork.yaml b/docs/api/schemas/v1.1/patchwork.yaml
index babc972..6b497ab 100644
--- a/docs/api/schemas/v1.1/patchwork.yaml
+++ b/docs/api/schemas/v1.1/patchwork.yaml
@@ -1551,6 +1551,24 @@ components:
                 current_state:
                   title: Current state
                   type: string
+    EventPatchRelationChanged:
+      allOf:
+        - $ref: '#/components/schemas/EventBase'
+        - type: object
+          properties:
+            category:
+              enum:
+                - patch-relation-changed
+            payload:
+              properties:
+                patch:
+                  $ref: '#/components/schemas/PatchEmbedded'
+                previous_relation:
+                  title: Previous relation
+                  type: string
+                current_relation:
+                  title: Current relation
+                  type: string
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
diff --git a/docs/api/schemas/v1.2/patchwork.yaml b/docs/api/schemas/v1.2/patchwork.yaml
index be79e38..db2ed12 100644
--- a/docs/api/schemas/v1.2/patchwork.yaml
+++ b/docs/api/schemas/v1.2/patchwork.yaml
@@ -352,6 +352,7 @@ paths:
               - patch-created
               - patch-completed
               - patch-state-changed
+              - patch-relation-changed
               - patch-delegated
               - check-created
               - series-created
@@ -390,6 +391,7 @@ paths:
                     - $ref: '#/components/schemas/EventPatchCreated'
                     - $ref: '#/components/schemas/EventPatchCompleted'
                     - $ref: '#/components/schemas/EventPatchStateChanged'
+                    - $ref: '#/components/schemas/EventPatchRelationChanged'
                     - $ref: '#/components/schemas/EventPatchDelegated'
                     - $ref: '#/components/schemas/EventCheckCreated'
                     - $ref: '#/components/schemas/EventSeriesCreated'
@@ -403,6 +405,8 @@ paths:
                         '#/components/schemas/EventPatchCompleted'
                       patch-state-changed: >
                         '#/components/schemas/EventPatchStateChanged'
+                      patch-relation-changed: >
+                        '#/components/schemas/EventPatchRelationChanged'
                       patch-delegated: >
                         '#/components/schemas/EventPatchDelegated'
                       check-created: '#/components/schemas/EventCheckCreated'
@@ -552,6 +556,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
       tags:
         - patches
     put:
@@ -595,6 +605,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
       tags:
         - patches
   /api/1.2/patches/{id}/comments/:
@@ -1721,6 +1737,24 @@ components:
                 current_state:
                   title: Current state
                   type: string
+    EventPatchRelationChanged:
+      allOf:
+        - $ref: '#/components/schemas/EventBase'
+        - type: object
+          properties:
+            category:
+              enum:
+                - patch-relation-changed
+            payload:
+              properties:
+                patch:
+                  $ref: '#/components/schemas/PatchEmbedded'
+                previous_relation:
+                  title: Previous relation
+                  type: string
+                current_relation:
+                  title: Current relation
+                  type: string
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
@@ -1893,6 +1927,11 @@ components:
           items:
             type: string
           readOnly: true
+        related:
+          title: Relations
+          type: array
+          items:
+            type: string
     PatchDetail:
       allOf:
         - $ref: '#/components/schemas/PatchList'
@@ -1943,6 +1982,11 @@ components:
           title: Delegate
           type: integer
           nullable: true
+        related:
+          title: Relations
+          type: array
+          items:
+            type: string
     Person:
       type: object
       properties: