[pull] main from OAI:main

.gitattributes

@@ -0,0 +1 @@
+*.md linguist-detectable

.github/ISSUE_TEMPLATE/config.yml

@@ -1,17 +1,28 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
+
+# The local issue filing links are included in "contact_links" because
+# GitHub's regular issue template mechanism forces the local issue
+# links to be first in the list, when we want them to be last so 
+# visitors can be routed to other repos when appropriate.
 contact_links:
-  - name: OpenAPI Specification
-    url: https://spec.openapis.org/oas/latest.html
-    about: View the latest version of the specification
-  - name: Getting started documentation
-    url: https://learn.openapis.org
-    about: Learn about the OpenAPI Specification
-  - name: OpenAPI Tooling
-    url: https://tools.openapis.org
-    about: Open-source and commercial tools for OpenAPI
-  - name: OpenAPI Initiative Registry
-    url: https://spec.openapis.org/registry/index.html
-    about: Registry of formats, extension namespaces etc.
-  - name: OpenAPI Initiative Slack
+  - name: Have a question about using OpenAPI?
     url: https://communityinviter.com/apps/open-api/openapi
-    about: Join our online community.
+    about: Ask us on our Slack!
+  - name: Have a question about OpenAPI Tooling?
+    url: https://tools.openapis.org/
+    about: Please ask your tooling vendor!
+  - name: Want to add to our list of OpenAPI Tools?
+    url: https://tools.openapis.org/
+    about: Please take a look at our tooling site's instructions!
+  - name: Want to suggest more how-to documentation and examples?
+    url: https://github.com/OAI/learn.openapis.org/issues/new
+    about: Please open an issue on our learning site!
+  - name: Want to add to the registries at spec.openapis.org/registry ?
+    url: https://github.com/OAI/OpenAPI-Specification/issues/new
+    about: Please open an issue in this repository!
+  - name: Want to report an error in the specification?
+    url: https://github.com/OAI/OpenAPI-Specification/issues/new
+    about: Please open an issue in this repository!
+  - name: Want to request a new feature in the specification?
+    url: https://github.com/OAI/OpenAPI-Specification/discussions/new?category=enhancements
+    about: Please start a discussion in this repository!

.github/pull_request_template.md

@@ -2,15 +2,20 @@
 Thank you for contributing to the OpenAPI Specification!
 
 Please make certain you are submitting your PR on the correct
-branch and file:
+branch, to the files under the "src/" directory (which is not
+present on the main branch, only on the development branches).
 
-* 3.0.x spec: v3.0.4-dev branch, versions/3.0.4.md
-* 3.1.x spec: v3.1.1-dev branch, versions/3.1.1.md
-* 3.2.0 spec: v3.2.0-dev branch, versions/3.2.0.md
-* 3.0 schema: main branch, schemas/v3.0/...
-* 3.1 schema: main branch, schemas/v3.1/...
+* 3.1.x spec and schemas: v3.1-dev branch
+* 3.2.x spec and schemas: v3.2-dev branch
 * registry templates: gh-pages branch, registry/...
 * registry contents: gh-pages branch, registries/...
+* process documentation and build infrastructure: main
 
 Note that we do not accept changes to published specifications.
 -->
+
+Tick one of the following options:
+
+- [ ] schema changes are included in this pull request
+- [ ] schema changes are needed for this pull request but not done yet
+- [ ] no schema changes are needed for this pull request

.github/templates/agenda.md

@@ -1,22 +1,36 @@
-**NOTE: weekly meetings happen on Thursdays at 9am - 10am Pacific.**
+## Weekly meetings happen on Thursdays at 9am - 10am Pacific
 
 This agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. 
 
 Whether attending or not, **anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals**.
 
-Zoom: [https://zoom.us/j/975841675](https://zoom.us/j/975841675?pwd=SUh4MjRLaEFKNlI3RElpWTdhRDVVUT09), dial-in passcode: 763054
+Meetings take place over Zoom: [https://zoom.us/j/975841675](https://zoom.us/j/975841675?pwd=SUh4MjRLaEFKNlI3RElpWTdhRDVVUT09), dial-in passcode: 763054
 
-Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification/blob/main/CODE_OF_CONDUCT.md#code-of-conduct).
+### Accessibility & Etiquette
+* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file).
 
-![F10B5460-B4B3-4463-9CDE-C7F782202EA9](https://user-images.githubusercontent.com/21603/121568843-0b260900-ca18-11eb-9362-69fda4162be8.jpeg)
+* Meetings are recorded for future reference, and for those who are not able to attend in-person.
+
+* We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting.
+
+* We look forward to your participation, but please consider these acts of etiquette:
+  * Remain on mute when not speaking to prevent interruptions.
+  * Blur your background to reduce visual distractions.
+  * Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak.
+
+| 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/user-attachments/assets/bf19ee70-59b1-410e-b893-645f26c2c96e"> |
+
+### Agenda Structure
 
 | Topic | Owner | Decision/NextStep |
-|-------|---------|---------|  
-| | | |
+|-|-|-|
 Intros and governance meta-topics (5 mins) | TDC | |
 Reports from Special Interest Groups (5 mins) | SIG members | |
 Any other business (add comments below to suggest topics) | TDC | |
-[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | TDC | |
+[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | |
+[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | |
 [New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage  | |
 
 /cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.

.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/respec.yaml

@@ -21,14 +21,18 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2 # checkout main branch
+    - uses: actions/checkout@v4 # checkout main branch
       with:
         fetch-depth: 0
 
+    - uses: actions/setup-node@v4 # setup Node.js
+      with:
+        node-version: '20.x'
+
     - name: Install dependencies
-      run: npm i
+      run: npm ci
 
-    - uses: actions/checkout@v2 # checkout gh-pages branch
+    - uses: actions/checkout@v4 # checkout gh-pages branch
       with:
         ref: gh-pages
         path: deploy
@@ -37,21 +41,21 @@ jobs:
       run: scripts/md2html/build.sh
 
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v5
+      uses: peter-evans/create-pull-request@v6
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
         branch: update-respec-version
         base: gh-pages
         delete-branch: true
         path: deploy
         labels: Housekeeping
-        reviewers: webron,darrelmiller
-        title: Update ReSpec versions
-        commit-message: Update ReSpec versions
+        reviewers: darrelmiller,webron,earth2marsh,webron,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge
+        title: Update ReSpec-rendered specification versions
+        commit-message: Update ReSpec-rendered specification versions
         signoff: true
         body: |
           This pull request is automatically triggered by GitHub action `respec`.
 
-          The versions/v*.md files have changed, so the HTML files are automatically being regenerated.
+          The `versions/*.md` files have changed, so the HTML files are automatically being regenerated.
 
 

.github/workflows/schema-publish.yaml

@@ -0,0 +1,57 @@
+name: schema-publish
+
+# author: @ralfhandl
+# issue: https://github.com/OAI/OpenAPI-Specification/issues/3715
+
+#
+# This workflow copies the 3.x schemas to the gh-pages branch
+#
+
+# run this on push to main
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4 # checkout main branch
+      with:
+        fetch-depth: 0
+
+    - uses: actions/setup-node@v4 # setup Node.js
+      with:
+        node-version: '20.x'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - uses: actions/checkout@v4 # checkout gh-pages branch
+      with:
+        ref: gh-pages
+        path: deploy
+
+    - name: run main script
+      run: scripts/schema-publish.sh
+
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@v6
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        branch: 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
+        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.

.github/workflows/schema-tests.yaml

@@ -5,7 +5,7 @@ name: schema-test
 
 #
 # This workflow runs the npm test script to validate passing and failing
-# testcases for the metaschema.
+# testcases for the metaschemas
 #
 
 # run this on push to any branch and creation of pull-requests
@@ -23,13 +23,13 @@ jobs:
     - uses: actions/checkout@v4 # checkout repo content
       with:
         fetch-depth: 0
+
     - uses: actions/setup-node@v4 # setup Node.js
       with:
         node-version: '20.x'
-    - name: Install dependencies from main
-      run: |
-        git checkout remotes/origin/main -- package.json
-        npm i
+
+    - name: Install dependencies
+      run: npm ci
+
     - name: Run tests
       run: npm run test
-

.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