Start annotating which version of the spec added a thing (#3425)

* Introduce a new "added-in" template and use it on endpoints

* Use "added-in" on schema properties too

* Annotate sections of the spec with their added versions

* Demo of "added-in" on a room version (to be fleshed out)

* Use clearer versioning semantics

* Update and fix validator for Swagger custom properties

* Fix docs

layouts/partials/added-in.html

@@ -0,0 +1,13 @@
+{{ $ver := .v }}
+{{ $this := .this }}
+
+{{/*
+    This differs from the shortcode added-in by wanting to be a block instead of inline
+    and by slightly altering the rendered text as a result.
+*/}}
+
+{{ if $this }}
+  **New in this version.**
+{{ else }}
+  **Added in `v{{ $ver }}`**
+{{ end }}

layouts/partials/events/render-event.html

@@ -25,6 +25,10 @@
 
   <hr/>
 
+{{ if (index $event_data "x-addedInMatrixVersion") }}
+  {{ partial "added-in" (dict "v" (index $event_data "x-addedInMatrixVersion")) }}
+{{ end }}
+
 {{ $event_data.description | markdownify }}
 
 </summary>

layouts/partials/openapi/render-object-table.html

@@ -82,7 +82,7 @@
  <tr>
   <td><code>{{ $property_name }}</code></td>
   <td><code>{{ $type }}</code></td>
-  <td>{{ if $required }}<strong>Required: </strong>{{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}<p>One of: <code>{{ $property.enum }}</code>.</p>{{ end }}</td>
+  <td>{{ if $required }}<strong>Required: </strong>{{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}<p>One of: <code>{{ $property.enum }}</code>.</p>{{ end }}{{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end }}</td>
  </tr>
 
     {{ end }}

layouts/partials/openapi/render-operation.html

@@ -39,6 +39,10 @@
     {{ partial "alert" (dict "type" "warning" "omit_title" "true" "content" "This API is deprecated and will be removed from a future release.") }}
 {{ end }}
 
+{{ if (index $operation_data "x-addedInMatrixVersion") }}
+  {{ partial "added-in" (dict "v" (index $operation_data "x-addedInMatrixVersion")) }}
+{{ end }}
+
 <p>{{ $operation_data.description | markdownify }}</p>
 
 </summary>

layouts/shortcodes/added-in.html

@@ -0,0 +1,8 @@
+{{ $ver := .Params.v }}
+{{ $this := .Params.this }}
+
+{{ if $this }}
+  <span>**[New in this version]**</span>
+{{ else }}
+  <span>**[Added in `v{{ $ver }}`]**</span>
+{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}}

layouts/shortcodes/definition.html

@@ -37,6 +37,10 @@
 
 <hr/>
 
+{{ if (index $definition "x-addedInMatrixVersion") }}
+  {{ partial "added-in" (dict "v" (index $definition "x-addedInMatrixVersion")) }}
+{{ end }}
+
 {{ $definition.description | markdownify }}
 
 </summary>