Merge pull request #4392 from OAI/main

dev: update from main

Author: ralfhandl

.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,22 @@
+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: |
+          echo This PR contains changes to files that should not be changed
+          exit 1

.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

@@ -190,13 +190,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
 
@@ -312,6 +318,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.
 
@@ -430,6 +437,15 @@ 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`.
+  This needs 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