dev: update from main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,18 @@
+---
+name: Bug report
+about: Create a report to help us improve the specification
+title: 'vX.Y: ...'
+labels: ''
+assignees: ''
+
+---
+
+**Describe the error in the specification**
+A clear and concise description of
+- what the error is, 
+- which specification versions are affected, 
+- what you would expect the specification to say instead,  and 
+- a link to the corresponding specification section in the "oldest" affected version.
+
+**Additional context**
+Add any other context about the problem here.

.github/workflows/schema-publish.yaml

@@ -4,14 +4,18 @@ name: schema-publish
 # issue: https://github.com/OAI/OpenAPI-Specification/issues/3715
 
 #
-# This workflow copies the 3.x schemas to the gh-pages branch
+# This workflow creates a pull request for publishing schema iterations to the gh-pages branch
 #
 
-# run this on push to main
+# run this on push to vX.Y-dev branches or manually
 on:
   push:
     branches:
-      - main
+      - 'v[0-9].[0-9]-dev'
+    paths:
+      - 'src/schemas/validation/*.yaml'
+      - 'scripts/schema-publish.sh'
+      - '.github/workflows/schema-publish.yaml'
   workflow_dispatch: {}
 
 jobs:
@@ -26,7 +30,7 @@ jobs:
 
     - uses: actions/setup-node@v4 # setup Node.js
       with:
-        node-version: '20.x'
+        node-version: '22.x'
 
     - name: Install dependencies
       run: npm ci
@@ -43,15 +47,15 @@ jobs:
       uses: peter-evans/create-pull-request@v6
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
-        branch: publish-schema-iteration
+        branch: ${{ github.ref_name }}-publish-schema-iteration
         base: gh-pages
         delete-branch: true
         path: deploy
         labels: Housekeeping,Schema
         reviewers: darrelmiller,webron,earth2marsh,webron,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge
-        title: Publish OpenAPI Schema Iterations
+        title: '${{ github.ref_name }}: publish OpenAPI schema iterations'
         commit-message: New OpenAPI schema iterations
         signoff: true
         body: |
-          This pull request is automatically triggered by GitHub action `schema-publish`.
-          The `schemas/**/*.yaml` files have changed and JSON files are automatically generated.
+          This pull request is automatically generated by GitHub action `schema-publish`.
+          The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated.

.github/workflows/validate-markdown.yaml

@@ -28,7 +28,7 @@ jobs:
         node-version: '20.x'
 
     - name: Validate markdown
-      run: npx --yes mdv versions/3.*.md
+      run: npx --yes mdv versions/3.*.md src/oas.md
 
     - name: Lint markdown 3.0.4, 3.1.1, and later
-      run: npx --yes markdownlint-cli --config .markdownlint.yaml versions/3.0.4.md versions/3.1.[^0].md versions/3.[2-9].*.md
+      run: npx --yes markdownlint-cli --config .markdownlint.yaml versions/3.0.4.md versions/3.1.[^0].md versions/3.[2-9].*.md src/oas.md

CONTRIBUTING.md

@@ -165,6 +165,9 @@ Draft pull requests can still be reviewed while in draft state.
 
 ### Preview specification HTML locally
 
+> [!NOTE]
+> `npm run build-src` calls bash scripts. Use [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL).
+
 The markdown source files are converted to HTML before publishing.
 To do this locally, please
 
@@ -199,7 +202,7 @@ The steps for creating a `vX.Y.Z-rel` branch are:
 
 1. Update `EDITORS.md` on `main`
 2. Merge `main` into `dev` and `dev` into `vX.Y-dev` via PRs
-   - Sync PRs are automatically created by workflows `sync-main-to-dev` and `sync-dev-to-vX.Y-dev`
+   - sync PRs are automatically created by workflows `sync-main-to-dev` and `sync-dev-to-vX.Y-dev`
 3. Prepare spec files in `vX.Y-dev`
    - `npm run format-markdown`
    - `npm run build-src`
@@ -211,6 +214,7 @@ The steps for creating a `vX.Y.Z-rel` branch are:
    - copy `EDITORS.md` to `versions/X.Y.Z-editors.md`
    - delete `src/schemas` 
    - delete `tests/schema`
+   - bash script `scripts/adjust-release-branch.sh` performs these steps
 5. Merge `vX.Y.Z-rel` into `main` via PR
    - this PR should only add files `versions/X.Y.Z.md` and `versions/X.Y.Z-editors.md`
 

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "oas-schemas",
-  "version": "2.0.0",
-  "description": "OpenAPI Specification JSON schemas",
+  "name": "oas-infra",
+  "version": "0.0.0",
+  "description": "OpenAPI Specification Automation & Infrastructure",
   "author": {
     "name": "OpenAPI Initiative TSC",
     "email": "[email protected]",
@@ -14,18 +14,16 @@
   "license": "Apache-2.0",
   "scripts": {
     "build": "bash ./scripts/md2html/build.sh",
-    "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh"
+    "build-src": "npm run validate-markdown && bash ./scripts/md2html/build.sh src && bash ./scripts/schema-publish.sh src",
+    "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh",
+    "format-markdown": "bash ./scripts/format-markdown.sh ./src/oas.md",
+    "validate-markdown": "npx mdv src/oas.md && npx markdownlint-cli src/oas.md"
   },
-  "readmeFilename": "README.md",
-  "files": [
-    "README.md",
-    "schemas/*"
-  ],
   "dependencies": {
     "cheerio": "^1.0.0-rc.5",
     "highlight.js": "^11.11.1",
     "markdown-it": "^14.1.0",
-    "respec": "35.2.3",
+    "respec": "35.3.0",
     "yargs": "^17.7.2"
   },
   "devDependencies": {

scripts/adjust-release-branch.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+# Author: @ralfhandl
+
+# Run this script from the root of the repo. It is designed to be run manually in a release branch.
+
+branch=$(git branch --show-current)
+
+if [[ ! $branch =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]]; then
+  echo "This script is intended to be run from a release branch, e.g. v3.1.2-rel"
+  exit 1
+fi
+
+vVersion=$(basename "$branch" "-rel")
+version=${vVersion:1}
+echo Prepare release of $version
+
+cp EDITORS.md versions/$version-editors.md
+mv src/oas.md versions/$version.md
+rm -r src/schemas
+rm -r tests/schema

scripts/schema-publish.sh

@@ -4,51 +4,75 @@
 
 # Run this script from the root of the repo. It is designed to be run by a GitHub workflow.
 
-for schemaDir in schemas/v3* ; do
-  vVersion=$(basename "$schemaDir")
-  version=${vVersion:1}
-  echo $version
-
-  # list of schemas to process, dependent schemas come first
-  schemas=(meta.yaml dialect.yaml schema.yaml schema-base.yaml)
-
-  # find the newest commit date for each schema
-  maxDate=""
-  declare -A datesHash
-  for schema in "${schemas[@]}"; do
-    if [ -f  "$schemaDir/$schema" ]; then
-      newestCommitDate=$(git log -1 --format="%ad" --date=short "$schemaDir/$schema")
-
-      # the newest date across a schema and all its dependencies is its date stamp
-      if [ "$newestCommitDate" \> "$maxDate" ]; then
-        maxDate=$newestCommitDate
-      fi
-      datesHash["$schema"]=$maxDate
-      echo $schema changed at $newestCommitDate
-    fi
-  done
+schemaDir="src/schemas/validation"
+branch=$(git branch --show-current)
+
+
+if [ -z "$1" ]; then
+  if [[ $branch =~ ^v([0-9]+\.[0-9]+)-dev$ ]]; then
+    deploydir="./deploy/oas/${BASH_REMATCH[1]}"
+  else
+    echo "Unable to determine version from branch name; should be vX.Y-dev"
+    exit 1
+  fi
+elif [ $1 = "src" ]; then
+  deploydir="./deploy-preview"
+else
+  echo "Unrecognized argument"
+  exit 1
+fi
+
+# create the date-stamped schemas
+publish_schema() {
+  local schema="$1"
+  local date="$2"
+  local sedCmd="$3"
+
+  local base=$(basename $schema '.yaml')
+  local target=$deploydir/$base/$date
+
+  mkdir -p $deploydir/$base
 
-  # construct sed command
-  sedCmd=()
-  for schema in "${!datesHash[@]}"; do
-    base=$(basename "$schema" .yaml)
-    sedCmd+=("-e s/$base\/WORK-IN-PROGRESS/$base\/${datesHash[$schema]}/g")
-  done
+  # replace the WORK-IN-PROGRESS placeholders
+  sed ${sedCmd[@]} $schemaDir/$schema | npx yaml --json --indent 2 --single > $target
 
-  # create the date-stamped schemas
-  for schema in "${!datesHash[@]}"; do
-    base=$(basename "$schema" .yaml)
-    target=deploy/oas/$version/$base/${datesHash[$schema]}
+  # Find the jekyll lander markdown file for this iteration.
+  local jekyllLander=$(find "$deploydir/$base" -maxdepth 1 -name "*.md")
 
-    mkdir -p "deploy/oas/$version/$base"
+  # Move the jekyll lander markdown for this iteration to the deploy destination.
+  # The lander files only exist in the gh-pages branch.
+  if [ ! -z "$jekyllLander" ]; then
+    mv $jekyllLander $target.md
+    echo " * $newestCommitDate: $schema & jekyll lander $(basename $jekyllLander)"
+  else
+    echo " * $newestCommitDate: $schema"
+  fi
 
-    sed ${sedCmd[@]} $schemaDir/$schema > $target.yaml
-    node scripts/yaml2json/yaml2json.js $target.yaml
-    rm $target.yaml
-    mv $target.json $target
+}
 
-    mv deploy/oas/$version/$base/*.md $target.md
-  done
+echo === Building schemas into $deploydir
 
-  echo ""
+# list of schemas to process, dependent schemas come first
+schemas=(meta.yaml dialect.yaml schema.yaml schema-base.yaml)
+
+# publish each schema using its or any of its dependencies newest commit date.
+maxDate=""
+sedCmds=()
+for schema in "${schemas[@]}"; do
+  if [ -f  "$schemaDir/$schema" ]; then
+    newestCommitDate=$(git log -1 --format="%ad" --date=short "$schemaDir/$schema")
+
+    # the newest date across a schema and all its dependencies is its date stamp
+    if [ "$newestCommitDate" \> "$maxDate" ]; then
+      maxDate=$newestCommitDate
+    fi
+
+    base=$(basename $schema '.yaml')
+    # Add the replacement for this schema's placeholder to list of sed commands.
+    sedCmds+=("s/${base}\/WORK-IN-PROGRESS/${base}\/${maxDate}/g")
+
+    publish_schema "$schema" "$maxDate" $(printf '%s;' "${sedCmds[@]}")
+  fi
 done
+
+echo === Built