Merge bb54e7d303 into 0e280ed014

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 name: "Spec"
 
 env:
-  HUGO_VERSION: 0.139.0
+  HUGO_VERSION: 0.147.8
   PYTHON_VERSION: 3.13
 
 on:

README.md

@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.123.1 is required.
+   v0.146.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required

changelogs/client_server/newsfragments/2177.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification.

changelogs/internal/newsfragments/2157.feature

@@ -0,0 +1 @@
+Add "placeholder MSC" process definition.

changelogs/internal/newsfragments/2160.clarification

@@ -0,0 +1 @@
+Upgrade the docsy theme to version 0.12.0.

config/_default/hugo.toml

@@ -8,7 +8,7 @@ enableRobotsTXT = true
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
 # links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
 # contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
-disableKinds = ["taxonomy", "RSS"]
+disableKinds = ["taxonomy", "rss"]
 
 [languages]
 [languages.en]
@@ -134,7 +134,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.123.1"
+    min = "0.146.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false

content/changelog/_index.md

@@ -1,6 +1,7 @@
 ---
 title: Changelog
 type: docs
+layout: changelog-index
 weight: 1000
 ---
 

content/proposals.md

@@ -497,6 +497,42 @@ In summary:
     a small table at the bottom mapping the various values from stable
     to unstable.
 
+### Placeholder MSCs
+
+Some proposals may contain security-sensitive or private context which can't be
+publicly disclosed until a later stage in the idea or solution process. Typically,
+the initial idea is validated using some amount of implementation or experimentation
+and may require an MSC number to make that implementation easier.
+
+Placeholder MSCs are used to represent proposals in a state where implementation
+is ongoing, but the MSC details can't yet be disclosed. Authors which feel as
+though their MSC could be highly sensitive MUST get in contact with the Spec Core
+Team or [Security Team](https://matrix.org/security-disclosure-policy/) prior to
+opening their MSC. If either team determines that a placeholder MSC is required,
+it may be opened as such.
+
+There are a few expectations attached to placeholder MSCs:
+
+* They have a title which marks them WIP, and are in the "draft" state.
+* They have the following labels: `[proposal-placeholder, action-required, needs-implementation]`.
+  * Notably, *not* `proposal`.
+* They are relatively short-lived (ideally less than 6-12 months in placeholder).
+* They propose solutions which are reasonably likely to be accepted. If a placeholder
+  needs to be closed because the idea won't work, isn't needed, etc, then the MSC's
+  content MUST be published ahead of that closure.
+  * Note: the MSC's publication (and therefore closure) may be delayed until an
+    appropriate point in the security disclosure cycle. For example, an alternative
+    MSC being published, or a stream of work being completed.
+* When they are updated to receive real content, the following happens:
+  1. The Spec Core Team or the author leaves a comment to cause a notification
+     that the MSC has been replaced with real content.
+  2. The `proposal` label (or its equivalent) is added to trigger chat notifications
+     in the public Matrix rooms. The `proposal-placeholder` and `action-required`
+     labels should be removed at this stage as well. Other labels are removed/applied
+     per normal process.
+* The Spec Core Team is aware of the intended MSC's title and purpose. This is
+  especially important if the Security Team approved the use of a placeholder MSC.
+
 ## Proposal Tracking
 
 This is a living document generated from the list of proposals on the

data/api/client-server/logout.yaml

@@ -47,7 +47,7 @@ paths:
         deleted alongside the device.
 
         This endpoint does not use the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) because
-        User-Interactive Authentication is designed to protect against attacks where the
+        User-Interactive Authentication is designed to protect against attacks where
         someone gets hold of a single access token then takes over the account. This
         endpoint invalidates all access tokens for the user, including the token used in
         the request, and therefore the attacker is unable to take over the account in

go.mod

@@ -3,3 +3,5 @@ module github.com/matrix-org/matrix-spec
 go 1.12
 
 require github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014 // indirect
+
+replace github.com/matrix-org/docsy => github.com/zecakeh/matrix-org-docsy v0.0.0-20250609083047-3b5e81464c1d

go.sum

@@ -1,4 +1,4 @@
-github.com/FortAwesome/Font-Awesome v0.0.0-20240716171331-37eff7fa00de/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014 h1:CNvxuuURuxkEjA0QN+lRKELc7PRDsX270e8v4GDF3II=
-github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014/go.mod h1:4Ek1bcdbfU/j8hIatEjNhIs1Yua85FtQf3kLvoYZ0bQ=
-github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
+github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/twbs/bootstrap v5.3.6+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
+github.com/zecakeh/matrix-org-docsy v0.0.0-20250609083047-3b5e81464c1d h1:yO1JdmvpuDBWHxYVDhRZeKElcEWyzW5VmR1p6vcjQPA=
+github.com/zecakeh/matrix-org-docsy v0.0.0-20250609083047-3b5e81464c1d/go.mod h1:4/t21g/nPraob/DVMm3jrk26k0CDL5I7Mxf+ar0IAgs=

layouts/_default/_markup/td-heading-self-link.html

@@ -1,11 +0,0 @@
-{{- /*
-
-    A simplified copy of the inlined "_default/_markup/_td-heading-self-link.html"
-    template in Docsy's "_default/_markup/td-render-heading.html" template to be
-    able to reuse it when the heading has custom markup.
-
-    Takes a string which is the ID of the heading.
-
-*/ -}}
-
-<a class="td-heading-self-link" href="#{{ . | safeURL }}" aria-label="Heading self-link"></a>

layouts/_markup/render-heading.html

@@ -8,4 +8,4 @@
     heading.
 
 */ -}}
-{{ template "_default/_markup/td-render-heading.html" . }}
+{{ partial "td/render-heading.html" . }}

layouts/_partials/events/render-event.html

@@ -24,7 +24,7 @@
 
   <h1 id="{{ $anchor }}">
    {{ with .title }}{{ . | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
-   {{ template "_default/_markup/td-heading-self-link.html" $anchor }}
+   {{ partial "td/heading-self-link.html" (dict "Anchor" $anchor) }}
   </h1>
 
 </summary>

layouts/_partials/json-schema/resolve-additional-types.html

@@ -66,7 +66,7 @@
  *     If the input `schema` was itself an object that we should create a table for,
  *     this will be the same as the first entry in `objects`.
  */
-{{ define "partials/resolve-additional-types-inner" }}
+{{ define "_partials/resolve-additional-types-inner" }}
     {{ $this_object := .schema }}
     {{ $anchor_base := .anchor_base }}
     {{ $name := .name }}
@@ -222,7 +222,7 @@
  *   * `objects`: The array of object schema definitions.
  *   * `schema`: An updated copy of the `schema` input (eg, an `anchor` may be added).
  */
-{{ define "partials/get-additional-objects" }}
+{{ define "_partials/get-additional-objects" }}
     /* .name is the name of the object for logging purposes */
     {{ $name := .name }}
 
@@ -246,6 +246,6 @@
  * This is needed for uniqify to work - otherwise objects that are the same
  * but with (for example) different examples will be considered different.
  */
-{{ define "partials/clean-object" }}
+{{ define "_partials/clean-object" }}
     {{ return (dict "title" .title "properties" .properties "additionalProperties" .additionalProperties "patternProperties" .patternProperties "required" .required "enum" .enum "anchor" .anchor) }}
 {{ end }}

layouts/_partials/navbar.html

@@ -80,7 +80,7 @@
 </div>
 </nav>
 
-{{ define "partials/version-string" }}
+{{ define "_partials/version-string" }}
     {{ $ret := "unstable version"}}
 
     {{ $status := .Site.Params.version.status }}

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

@@ -47,8 +47,8 @@
 
  <tr>
   <td><code>{{ $property_name }}</code></td>
-  <td><code>{{ partial "partials/property-type" $property | safeHTML }}</code></td>
-  <td>{{ partial "partials/property-description" (dict "property" $property "required" $required) }}</td>
+  <td><code>{{ partial "property-type" $property | safeHTML }}</code></td>
+  <td>{{ partial "property-description" (dict "property" $property "required" $required) }}</td>
  </tr>
 
     {{ end }}
@@ -71,8 +71,8 @@
 
  <tr>
   <td>&lt;Other properties&gt;</td>
-  <td><code>{{ partial "partials/property-type" .additionalProperties | safeHTML }}</code></td>
-  <td>{{ partial "partials/property-description" (dict "property" .additionalProperties) }}</td>
+  <td><code>{{ partial "property-type" .additionalProperties | safeHTML }}</code></td>
+  <td>{{ partial "property-description" (dict "property" .additionalProperties) }}</td>
  </tr>
     {{ end }}
 </table>
@@ -101,8 +101,8 @@ resolve-additional-types.)
  {{ $property := . }}
 
  <tr>
-  <td><code>{{ partial "partials/property-type" $property | safeHTML }}</code></td>
-  <td>{{ partial "partials/property-description" (dict "property" $property) }}</td>
+  <td><code>{{ partial "property-type" $property | safeHTML }}</code></td>
+  <td>{{ partial "property-description" (dict "property" $property) }}</td>
  </tr>
 </table>
 
@@ -138,7 +138,7 @@ resolve-additional-types.)
     * `format`: optional string for the format of the type, used for strings.
 
 */}}
-{{ define "partials/property-type" }}
+{{ define "_partials/property-type" }}
     {{ $type := "" }}
 
     {{ if eq .type "object" }}
@@ -215,7 +215,7 @@ resolve-additional-types.)
 
     * `anchor`: optional HTML element id for the target type, which will be used to link to it.
 */}}
-{{ define "partials/object-type-or-title" }}
+{{ define "_partials/object-type-or-title" }}
     {{ $type := "object" }}
     {{ if .properties }}
         {{/*
@@ -306,7 +306,7 @@ resolve-additional-types.)
       * `x-changedInMatrixVersion`: optional string indicating in which Matrix
         spec version this property was last changed.
 */}}
-{{ define "partials/property-description" -}}
+{{ define "_partials/property-description" -}}
     {{ $description := .property.description -}}
     {{ if .required -}}
         {{/*
@@ -331,7 +331,7 @@ resolve-additional-types.)
     Computes the type to display for a string format, given the identifier of
     the format as a string.
 */}} 
-{{ define "partials/string-format" }}
+{{ define "_partials/string-format" }}
   {{ $stringFormat := "" }}
 
   {{ with index site.Data "string-formats" . }}

layouts/_partials/openapi/render-operation.html

@@ -37,7 +37,7 @@
   <h1 id="{{ $anchor }}">
    <span class="http-api-method">{{ $method }}</span>
    <span class="endpoint{{ if $operation_data.deprecated }} deprecated-inline{{ end }}">{{ $endpoint }}</span>
-   {{ template "_default/_markup/td-heading-self-link.html" $anchor }}
+   {{ partial "td/heading-self-link.html" (dict "Anchor" $anchor) }}
   </h1>
 </summary>
 

layouts/docs/baseof.html

@@ -25,7 +25,9 @@
           </aside>
           <main class="col-12 col-md-9 col-xl-8 ps-md-5" role="main">
             {{ partial "version-banner.html" . }}
-            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
+            {{ if not (.Param "ui.breadcrumb_disable") -}}
+              {{ partial "breadcrumb.html" . -}}
+            {{ end -}}
             {{ block "main" . }}{{ end }}
           </main>
         </div>

layouts/docs/changelog-index.html

@@ -0,0 +1,13 @@
+{{- /*
+
+    Template to the `changelog` section page.
+
+    This redirects the page to the latest version's changelog page.
+
+*/ -}}
+
+{{ define "main" }}
+    {{ with index .RegularPages.ByDate.Reverse 0 -}}
+    <meta http-equiv="refresh" content="0; url={{ .RelPermalink }}">
+    {{ end -}}
+{{ end }}

layouts/docs/changelog.html

@@ -1,14 +1,8 @@
 {{- /*
 
-    Template to render a page with a `changelog` layout or the `changelog`
-    section page. This conflation seems to be a limitation of Hugo currently, it
-    uses this template for both cases.
+    Template to render a page with a `changelog` layout.
 
-    For the `changelog` section page, this redirects the page to the latest
-    version's changelog page.
-
-    For a page with a `changelog` layout, this adds a table at the top of the
-    page with information about the release:
+    This adds a table at the top of the page with information about the release:
 
     * A link to the matrix-spec repository at the time of the release, with the
       version taken from the `linkTitle` in the frontmatter of the page, unless
@@ -21,11 +15,6 @@
 */ -}}
 
 {{ define "main" }}
-{{ if .IsSection -}}
-    {{ with index .RegularPages.ByDate.Reverse 0 -}}
-    <meta http-equiv="refresh" content="0; url={{ .RelPermalink }}">
-    {{ end -}}
-{{ else -}}
     {{ $version := lower .LinkTitle -}}
 <div class="td-content">
     <h1>{{ .Title }}</h1>
@@ -50,5 +39,4 @@
 
     {{ .Content }}
 </div>
-{{ end -}}
 {{ end }}