diff mbox series

[1/2] docs: Don't version events

Message ID 20220329185732.401187-1-stephen@that.guru
State Accepted
Headers show
Series [1/2] docs: Don't version events | expand

Commit Message

Stephen Finucane March 29, 2022, 6:57 p.m. UTC 
We don't actually version the types of events we emit. Doing so would be
possible, but this ship has already sailed (with API version 1.2).

We also remove some unnecessary line breaks.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/api/schemas/latest/patchwork.yaml | 21 +++++++------
 docs/api/schemas/patchwork.j2          | 29 +++++++-----------
 docs/api/schemas/v1.0/patchwork.yaml   | 41 ++++++++++++++++++++------
 docs/api/schemas/v1.1/patchwork.yaml   | 41 ++++++++++++++++++++------
 docs/api/schemas/v1.2/patchwork.yaml   | 21 +++++++------
 docs/api/schemas/v1.3/patchwork.yaml   | 21 +++++++------
 6 files changed, 104 insertions(+), 70 deletions(-)

Comments

Stephen Finucane March 29, 2022, 7:06 p.m. UTC | #1 
On Tue, 2022-03-29 at 19:57 +0100, Stephen Finucane wrote:
> We don't actually version the types of events we emit. Doing so would be
> possible, but this ship has already sailed (with API version 1.2).
> 
> We also remove some unnecessary line breaks.
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>

fwiw, I think we should drop this versioning silliness in API v{next} and just
expose the server version as a header. It was a (generally) fun experiment but
it's a pain in the a*** and of questionable benefit. We've got (IMO) excellent
API documentation + release notes so that should do the trick for the few API
clients that exist.

Stephen
diff mbox series

Patch

diff --git docs/api/schemas/latest/patchwork.yaml docs/api/schemas/latest/patchwork.yaml
index 2a98c179..43edfb04 100644
--- docs/api/schemas/latest/patchwork.yaml
+++ docs/api/schemas/latest/patchwork.yaml
@@ -402,7 +402,11 @@  paths:
             type: string
         - in: query
           name: category
-          description: An event category to filter events by.
+          description: >
+            An event category to filter events by. These categories are subject
+            to change depending on the version of Patchwork deployed and are
+            not subject to the versionining constraints present across the rest
+            of the API.
           schema:
             title: ''
             type: string
@@ -460,18 +464,13 @@  paths:
                     mapping:
                       cover-created: '#/components/schemas/EventCoverCreated'
                       patch-created: '#/components/schemas/EventPatchCreated'
-                      patch-completed: >
-                        '#/components/schemas/EventPatchCompleted'
-                      patch-state-changed: >
-                        '#/components/schemas/EventPatchStateChanged'
-                      patch-relation-changed: >
-                        '#/components/schemas/EventPatchRelationChanged'
-                      patch-delegated: >
-                        '#/components/schemas/EventPatchDelegated'
+                      patch-completed: '#/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'
                       series-created: '#/components/schemas/EventSeriesCreated'
-                      series-completed: >
-                        '#/components/schemas/EventSeriesCompleted'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
         - events
   /api/patches/:
diff --git docs/api/schemas/patchwork.j2 docs/api/schemas/patchwork.j2
index 02aa9f72..df72c1ac 100644
--- docs/api/schemas/patchwork.j2
+++ docs/api/schemas/patchwork.j2
@@ -413,7 +413,11 @@  paths:
             type: string
         - in: query
           name: category
-          description: An event category to filter events by.
+          description: >
+            An event category to filter events by. These categories are subject
+            to change depending on the version of Patchwork deployed and are
+            not subject to the versionining constraints present across the rest
+            of the API.
           schema:
             title: ''
             type: string
@@ -422,9 +426,7 @@  paths:
               - patch-created
               - patch-completed
               - patch-state-changed
-{% if version >= (1, 2) %}
               - patch-relation-changed
-{% endif %}
               - patch-delegated
               - check-created
               - series-created
@@ -463,9 +465,7 @@  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'
@@ -475,20 +475,13 @@  paths:
                     mapping:
                       cover-created: '#/components/schemas/EventCoverCreated'
                       patch-created: '#/components/schemas/EventPatchCreated'
-                      patch-completed: >
-                        '#/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'
+                      patch-completed: '#/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'
                       series-created: '#/components/schemas/EventSeriesCreated'
-                      series-completed: >
-                        '#/components/schemas/EventSeriesCompleted'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
         - events
   /api/{{ version_url }}patches/:
@@ -1922,7 +1915,6 @@  components:
                 current_state:
                   title: Current state
                   type: string
-{% if version >= (1, 2) %}
     EventPatchRelationChanged:
       allOf:
         - $ref: '#/components/schemas/EventBase'
@@ -1943,7 +1935,6 @@  components:
                   title: Current relation
                   type: string
                   nullable: true
-{% endif %}
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
diff --git docs/api/schemas/v1.0/patchwork.yaml docs/api/schemas/v1.0/patchwork.yaml
index 23e8930a..e2f1362f 100644
--- docs/api/schemas/v1.0/patchwork.yaml
+++ docs/api/schemas/v1.0/patchwork.yaml
@@ -228,7 +228,11 @@  paths:
             type: string
         - in: query
           name: category
-          description: An event category to filter events by.
+          description: >
+            An event category to filter events by. These categories are subject
+            to change depending on the version of Patchwork deployed and are
+            not subject to the versionining constraints present across the rest
+            of the API.
           schema:
             title: ''
             type: string
@@ -237,6 +241,7 @@  paths:
               - patch-created
               - patch-completed
               - patch-state-changed
+              - patch-relation-changed
               - patch-delegated
               - check-created
               - series-created
@@ -275,6 +280,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'
@@ -284,16 +290,13 @@  paths:
                     mapping:
                       cover-created: '#/components/schemas/EventCoverCreated'
                       patch-created: '#/components/schemas/EventPatchCreated'
-                      patch-completed: >
-                        '#/components/schemas/EventPatchCompleted'
-                      patch-state-changed: >
-                        '#/components/schemas/EventPatchStateChanged'
-                      patch-delegated: >
-                        '#/components/schemas/EventPatchDelegated'
+                      patch-completed: '#/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'
                       series-created: '#/components/schemas/EventSeriesCreated'
-                      series-completed: >
-                        '#/components/schemas/EventSeriesCompleted'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
         - events
   /api/1.0/patches/:
@@ -1485,6 +1488,26 @@  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
+                  nullable: true
+                current_relation:
+                  title: Current relation
+                  type: string
+                  nullable: true
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
diff --git docs/api/schemas/v1.1/patchwork.yaml docs/api/schemas/v1.1/patchwork.yaml
index 3b75c548..cdf8ef29 100644
--- docs/api/schemas/v1.1/patchwork.yaml
+++ docs/api/schemas/v1.1/patchwork.yaml
@@ -228,7 +228,11 @@  paths:
             type: string
         - in: query
           name: category
-          description: An event category to filter events by.
+          description: >
+            An event category to filter events by. These categories are subject
+            to change depending on the version of Patchwork deployed and are
+            not subject to the versionining constraints present across the rest
+            of the API.
           schema:
             title: ''
             type: string
@@ -237,6 +241,7 @@  paths:
               - patch-created
               - patch-completed
               - patch-state-changed
+              - patch-relation-changed
               - patch-delegated
               - check-created
               - series-created
@@ -275,6 +280,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'
@@ -284,16 +290,13 @@  paths:
                     mapping:
                       cover-created: '#/components/schemas/EventCoverCreated'
                       patch-created: '#/components/schemas/EventPatchCreated'
-                      patch-completed: >
-                        '#/components/schemas/EventPatchCompleted'
-                      patch-state-changed: >
-                        '#/components/schemas/EventPatchStateChanged'
-                      patch-delegated: >
-                        '#/components/schemas/EventPatchDelegated'
+                      patch-completed: '#/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'
                       series-created: '#/components/schemas/EventSeriesCreated'
-                      series-completed: >
-                        '#/components/schemas/EventSeriesCompleted'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
         - events
   /api/1.1/patches/:
@@ -1510,6 +1513,26 @@  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
+                  nullable: true
+                current_relation:
+                  title: Current relation
+                  type: string
+                  nullable: true
     EventPatchDelegated:
       allOf:
         - $ref: '#/components/schemas/EventBase'
diff --git docs/api/schemas/v1.2/patchwork.yaml docs/api/schemas/v1.2/patchwork.yaml
index 17d948a2..2a37d81b 100644
--- docs/api/schemas/v1.2/patchwork.yaml
+++ docs/api/schemas/v1.2/patchwork.yaml
@@ -336,7 +336,11 @@  paths:
             type: string
         - in: query
           name: category
-          description: An event category to filter events by.
+          description: >
+            An event category to filter events by. These categories are subject
+            to change depending on the version of Patchwork deployed and are
+            not subject to the versionining constraints present across the rest
+            of the API.
           schema:
             title: ''
             type: string
@@ -394,18 +398,13 @@  paths:
                     mapping:
                       cover-created: '#/components/schemas/EventCoverCreated'
                       patch-created: '#/components/schemas/EventPatchCreated'
-                      patch-completed: >
-                        '#/components/schemas/EventPatchCompleted'
-                      patch-state-changed: >
-                        '#/components/schemas/EventPatchStateChanged'
-                      patch-relation-changed: >
-                        '#/components/schemas/EventPatchRelationChanged'
-                      patch-delegated: >
-                        '#/components/schemas/EventPatchDelegated'
+                      patch-completed: '#/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'
                       series-created: '#/components/schemas/EventSeriesCreated'
-                      series-completed: >
-                        '#/components/schemas/EventSeriesCompleted'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
         - events
   /api/1.2/patches/:
diff --git docs/api/schemas/v1.3/patchwork.yaml docs/api/schemas/v1.3/patchwork.yaml
index 0a9046a5..88c4e355 100644
--- docs/api/schemas/v1.3/patchwork.yaml
+++ docs/api/schemas/v1.3/patchwork.yaml
@@ -402,7 +402,11 @@  paths:
             type: string
         - in: query
           name: category
-          description: An event category to filter events by.
+          description: >
+            An event category to filter events by. These categories are subject
+            to change depending on the version of Patchwork deployed and are
+            not subject to the versionining constraints present across the rest
+            of the API.
           schema:
             title: ''
             type: string
@@ -460,18 +464,13 @@  paths:
                     mapping:
                       cover-created: '#/components/schemas/EventCoverCreated'
                       patch-created: '#/components/schemas/EventPatchCreated'
-                      patch-completed: >
-                        '#/components/schemas/EventPatchCompleted'
-                      patch-state-changed: >
-                        '#/components/schemas/EventPatchStateChanged'
-                      patch-relation-changed: >
-                        '#/components/schemas/EventPatchRelationChanged'
-                      patch-delegated: >
-                        '#/components/schemas/EventPatchDelegated'
+                      patch-completed: '#/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'
                       series-created: '#/components/schemas/EventSeriesCreated'
-                      series-completed: >
-                        '#/components/schemas/EventSeriesCompleted'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
         - events
   /api/1.3/patches/: