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
 

.github/workflows/check-restricted-files.yaml

@@ -0,0 +1,44 @@
+name: check-restricted-files
+
+# Author: @ralfhandl
+# Issue: https://github.com/OAI/OpenAPI-Specification/issues/3432
+
+# This workflow fails if restricted files are changed in a pull request
+
+on:
+  pull_request:
+    paths:
+      - 'schemas/**/*.yaml'
+      - 'versions/*.md'
+
+jobs:
+  check-files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check changed files
+        shell: bash
+        run: |
+          if [[ "${{ github.event.pull_request.head.repo.full_name }}" == "OAI/OpenAPI-Specification" ]] && \
+             [[ "${{ github.event.pull_request.base.repo.full_name }}" == "OAI/OpenAPI-Specification" ]]; then
+
+            if [[ "${{ github.event.pull_request.head.ref }}" == "main" ]] && \
+               [[ "${{ github.event.pull_request.base.ref }}" == "dev" ]]; then
+              echo Sync from main to dev
+              exit 0
+            fi
+
+            if [[ "${{ github.event.pull_request.head.ref }}" == "dev" ]] && \
+               [[ "${{ github.event.pull_request.base.ref }}" =~ ^v[0-9]+\.[0-9]+-dev$ ]]; then
+              echo Sync from dev to ${{ github.event.pull_request.base.ref }}
+              exit 0
+            fi
+
+            if [[ "${{ github.event.pull_request.head.ref }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]] && \
+               [[ "${{ github.event.pull_request.base.ref }}" == "main" ]]; then
+              echo Release from ${{ github.event.pull_request.head.ref }} to main
+              exit 0
+            fi
+          fi
+
+          echo This PR contains changes to files that should not be changed
+          exit 1

.github/workflows/sync-dev-to-vX.Y-dev.yaml

@@ -0,0 +1,45 @@
+name: sync-dev-to-vX.Y-dev
+
+# author: @ralfhandl
+
+#
+# This workflow creates PRs to update the vX.Y-dev branch with the latest changes from dev
+#
+
+# run this on push to dev
+on:
+  push:
+    branches:
+      - dev
+
+jobs:
+  sync-branches:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create pull requests
+        id: pull_requests
+        shell: bash
+        run: |
+          DEV_BRANCHES=$(git branch -r --list origin/v?.?-dev)
+          for DEV_BRANCH in $DEV_BRANCHES; do
+            BASE=${DEV_BRANCH:7}
+            EXISTS=$(gh pr list --base $BASE --head $HEAD \
+              --json number --jq '.[] | .number')
+            if [ ! -z "$EXISTS" ]; then
+              echo "PR #$EXISTS already wants to merge $HEAD into $BASE"
+              continue
+            fi
+
+            gh pr create --base $BASE --head $HEAD \
+              --label "Housekeeping" \
+              --title "$BASE: update from $HEAD" \
+              --body "Merge \`$HEAD\` into \`$BASE\`."
+          done
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD: dev

.github/workflows/sync-main-to-dev.yaml

@@ -0,0 +1,40 @@
+name: sync-main-to-dev
+
+# author: @ralfhandl
+
+#
+# This workflow creates PRs to update the dev branch with the latest changes from main
+#
+
+# run this on push to main
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  sync-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Create pull request
+        id: pull_request
+        shell: bash
+        run: |
+          EXISTS=$(gh pr list --base $BASE --head $HEAD \
+            --json number --jq '.[] | .number')
+          if [ ! -z "$EXISTS" ]; then
+            echo "PR #$EXISTS already wants to merge $HEAD into $BASE"
+            exit 0
+          fi
+
+          gh pr create --base $BASE --head $HEAD \
+            --label "Housekeeping" \
+            --title "$BASE: update from $HEAD" \
+            --body "Merge \`$HEAD\` into \`$BASE\`."
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD: main
+          BASE: dev

CONTRIBUTING.md

@@ -163,6 +163,19 @@ This might apply to, for example, Markdown files, automation, and scripts.
 For all pull requests, if they should not be merged yet for any reason (they depend on something else, you would like feedback from a specific reviewer), mark them as draft and they will not be merged while in that state.
 Draft pull requests can still be reviewed while in draft state.
 
+### Preview specification HTML locally
+
+The markdown source files are converted to HTML before publishing.
+To do this locally, please
+
+1. Install [Node.js](https://nodejs.org/)
+2. Check out this repo, go to the repo root, and switch to a development branch
+3. Execute `npm install` (once, repeat after merging upstream changes)
+4. Execute `npm run build-src` after changing `src/oas.md` (this first executes `npm run validate-markdown`, which can also be run separately)
+5. Open output file `deploy-preview/oas.html` with a browser and check your changes
+
+Please make sure the markdown validates and builds using the above steps before creating a pull request or marking a draft pull request as ready for review.
+
 ## Reviewers
 
 > [!NOTE]
@@ -177,13 +190,38 @@ 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 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`
+3. Prepare spec files in `vX.Y-dev`
+   - `npm run format-markdown`
+   - `npm run build-src`
+   - open `deploy-preview/oas.html` in browser and verify correct formatting
+   - adjust and repeat until done
+   - merge changes to `src/oas.md` back into `vX.Y-dev` via PR
+4. Create `vX.Y.Z-rel` from `vX.Y-dev` and adjust it
+   - move `src/oas.md` to `versions/X.Y.Z.md`
+   - copy `EDITORS.md` to `versions/X.Y.Z-editors.md`
+   - delete `src/schemas` 
+   - delete `tests/schema`
+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`
+
+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
 
@@ -299,6 +337,7 @@ For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and e
 
 * `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed.  The `src` tree is ***not*** present on `main`.
 * `dev` is the primary branch for working with the `src` tree, which is kept up-to-date with the most recent release on the most recent minor (X.Y) release line, and serves as the base for each new minor release line.  Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed.
+  Changes on `main` are automatically included in a pull request to `dev` (see the (section on [branch sync](#branch-sync-automation)).
 * `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions.  All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document.
 * `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0).  It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links.
 
@@ -417,6 +456,17 @@ gitGraph TB:
   commit id:"3.3 work"
 ```
 
+### Branch sync automation
+
+To keep changes in sync, we have some GitHub actions that open pull requests to take changes from `main` onto the `dev` branch, and from `dev` to each active version branch.
+
+- `sync-main-to-dev` opens a pull request with all the changes from the `main` branch that aren't yet included on `dev`.
+- `sync-dev-to-vX.Y-dev` opens pull requests with all the changes from `dev` that aren't yet included on the corresponding `vX.Y-dev` branch.
+
+These need a single approval from either maintainers or TSC and can be merged.
+The aim is to bring build script and repository documentation changes to the other branches.
+Published versions of the specifications and schemas will also move across branches with this approach.
+
 ## Appendix: Issue Automation
 
 ### Automated closure of issues Process