dev: update from main

.github/templates/agenda.md

@@ -20,7 +20,7 @@ Meetings take place over Zoom: [https://zoom.us/j/975841675](https://zoom.us/j/9
 
 | Blur My Background | Raise Hand |
 |-|-|
-| <img width="323" alt="Screenshot of Zoom UI showing the 'Stop Video' and 'Blur My Background' control" src="https://github.com/OAI/OpenAPI-Specification/assets/7367/7e43dbbb-6529-46e6-8b04-4c1aa852d9dd"> | <img width="323" alt="Screenshot of Zoom UI showing the 'Reaction' and 'Raise Hand' control" src="https://github.com/OAI/OpenAPI-Specification/assets/7367/f991722f-4651-40aa-9bc4-7e9a2a165a6a"> |
+| <img width="323" alt="Screenshot of Zoom UI showing the 'Stop Video' and 'Blur My Background' control" src="https://github.com/OAI/OpenAPI-Specification/assets/7367/7e43dbbb-6529-46e6-8b04-4c1aa852d9dd"> | <img width="323" alt="Screenshot of Zoom UI showing the 'Reaction' and 'Raise Hand' control" src="https://github.com/user-attachments/assets/bf19ee70-59b1-410e-b893-645f26c2c96e"> |
 
 ### Agenda Structure
 

CONTRIBUTING.md

@@ -177,13 +177,19 @@ Reviews requesting changes should have their changes addressed regardless of how
 
 ## Publishing
 
-The specification are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`.
-The HTML versions of the OAS are automatically generated from the `versions` directory on `main`.
+### Specification Versions
+
+The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`.
 This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files).
 
-The schemas are published [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas).
-As part of the publishing process, the `WORK-IN-PROGRESS` placeholders are replaced with dates as appropriate.
-Schemas are published/updated independently from the specification releases.
+The HTML renderings of the specification versions are automatically generated from the `versions` directory on `main` by the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml), which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org).
+
+### Schema Iterations
+
+The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas).
+Schemas are updated in and directly published from the `vX.Y-dev` branches.
+
+As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the `schema-publish` workflow which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required.
 
 ## Release Process and Scope
 

package.json

@@ -33,7 +33,7 @@
     "c8": "^10.1.3",
     "markdownlint-cli": "^0.44.0",
     "mdv": "^1.3.4",
-    "vitest": "^3.0.5",
+    "vitest": "^3.0.7",
     "yaml": "^2.7.0"
   },
   "keywords": [

scripts/md2html/build.sh

@@ -24,8 +24,10 @@ cp -p node_modules/respec/builds/respec-w3c.* $deploydir/js/
 
 latest=$(git describe --abbrev=0 --tags)
 
+allVersions=$(ls -1 versions/[23456789].*.md | grep -v -e "\-editors" | sort -r)
+
 if [ -z "$1" ]; then
-  specifications=$(ls -1 versions/[23456789].*.md | grep -v -e "\-editors" | sort -r)
+  specifications=$allVersions
 elif [ "$1" = "latest" ]; then
   specifications=$(ls -1 versions/$latest.md)
 elif [ "$1" = "src" ]; then
@@ -53,8 +55,8 @@ for specification in $specifications; do
 
   echo === Building $version to $destination
 
-  node scripts/md2html/md2html.js --maintainers $maintainers $specification > $tempfile
-  npx respec --use-local --src $tempfile --out $destination
+  node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile
+  npx respec --no-sandbox --use-local --src $tempfile --out $destination
   rm $tempfile
 
   echo === Built $destination

scripts/md2html/md2html.js

@@ -77,6 +77,7 @@ const md = require('markdown-it')({
 });
 
 function preface(title,options) {
+    const otherVersions = options._[1].split("\n").map(v => path.basename(v,'.md')).filter(v => v !== options.subtitle);
     const respec = {
         specStatus: "base",
         latestVersion: "https://spec.openapis.org/oas/latest.html",
@@ -96,6 +97,14 @@ function preface(title,options) {
             height: 48,
             url: "https://openapis.org/"}],
         otherLinks: [
+            {
+                key: "Other versions:",
+                data: otherVersions.map(v => {
+                    return {
+                        href: `https://spec.openapis.org/oas/v${v}.html`
+                    }
+                })
+            },
             {
                 key: "Participate",
                 data: [

style-guide.md

@@ -21,6 +21,7 @@ The following additional rules should be followed but currently are not enforced
 9. Use [Oxford commas](https://en.wikipedia.org/wiki/Serial_comma), avoid [Shatner commas](https://www.latimes.com/archives/blogs/jacket-copy/story/2011-06-30/goodbye-oxford-comma-hello-shatner-comma).
 10. Use `<span id="thing"></span>` for link anchors. The `<a name="thing"></a>` format has been deprecated.
 11. Headings use [title case](https://en.wikipedia.org/wiki/Title_case) and are followed by a blank line.
+12. Do not use [RFC2119 key words (MUST, MAY, ...)](https://datatracker.ietf.org/doc/html/rfc2119) in "Examples" sections or when explaining examples, and state requirements only in sections that are clearly normative.
 
 Plus some suggestions, rather than rules:
 
@@ -35,4 +36,7 @@ Plus some suggestions, rather than rules:
 * property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property"
 * "attribute" is only used in the XML context and means "XML attribute"
 
+### Field Names and Values in YAML comments
 
+Field names and keywords should be in backticks.
+Values like "Dog" should be double quoted.

tests/md2html/fixtures/basic-new.html

@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"John Doe "},{"name":"Jane Doe "}],"formerEditors":[{"name":"Foo Bar "}],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
+<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"John Doe "},{"name":"Jane Doe "}],"formerEditors":[{"name":"Foo Bar "}],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Other versions:","data":[{"href":"https://spec.openapis.org/oas/v31.0.0.html"},{"href":"https://spec.openapis.org/oas/v30.0.0.html"}]},{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
 <script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
 <script>
  window.dataLayer = window.dataLayer || [];

tests/md2html/fixtures/basic-old.html

@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"Foo Bar "}],"formerEditors":[],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
+<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"Foo Bar "}],"formerEditors":[],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Other versions:","data":[{"href":"https://spec.openapis.org/oas/v31.0.0.html"},{"href":"https://spec.openapis.org/oas/v30.0.0.html"}]},{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
 <script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
 <script>
  window.dataLayer = window.dataLayer || [];

tests/md2html/md2html.test.mjs

@@ -1,5 +1,5 @@
 import { readdirSync, readFileSync } from "node:fs";
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import { resolve } from "node:path";
 import { describe, test, expect } from "vitest";
 import assert from "node:assert";
@@ -13,12 +13,13 @@ describe("md2html", async () => {
         const expected = readFileSync(
           folder + entry.name.replace(".md", ".html"),
           "utf8",
-        );
+        ); 
         const output = await md2html(
           [
             "--maintainers",
             entry.name.replace(".md", ".maintainers"),
             entry.name,
+            "path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md",
           ],
           folder,
         );
@@ -29,8 +30,9 @@ describe("md2html", async () => {
 
 function md2html(args, cwd) {
   return new Promise((res) => {
-    exec(
-      `node ${resolve("./scripts/md2html/md2html.js")} ${args.join(" ")}`,
+    execFile(
+      "node",
+      [`${resolve("./scripts/md2html/md2html.js")}`, ...args],
       { cwd },
       (error, stdout, stderr) => {
         res({