1.2-dev refresh from dev

.github/dependabot.yml

@@ -5,12 +5,3 @@ updates:
     schedule:
       interval: daily
     open-pull-requests-limit: 10
-  - package-ecosystem: npm
-    directory: "/"
-    schedule:
-      interval: daily
-    open-pull-requests-limit: 10
-    groups:
-      vitest:
-        patterns:
-          - "*vitest*"

.github/workflows/respec.yaml

@@ -42,8 +42,11 @@ jobs:
         with:
           node-version: "24.x"
 
+      - name: Enable corepack
+        run: corepack enable
+
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --immutable
 
       - uses: actions/checkout@v7 # checkout main branch of website repo
         with:
@@ -53,7 +56,7 @@ jobs:
           path: deploy
 
       - name: run main script
-        run: scripts/md2html/build.sh
+        run: yarn build
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v8

.github/workflows/schema-publish.yaml

@@ -38,8 +38,11 @@ jobs:
         with:
           node-version: "24.x"
 
+      - name: Enable corepack
+        run: corepack enable
+
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --immutable
 
       - uses: actions/checkout@v7 # checkout main branch of website repo
         with:
@@ -49,7 +52,7 @@ jobs:
           path: deploy
 
       - name: run main script
-        run: scripts/schema-publish.sh
+        run: yarn publish-schemas
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v8

.github/workflows/schema-tests.yaml

@@ -26,10 +26,13 @@ jobs:
         with:
           node-version: "24.x"
 
+      - name: Enable corepack
+        run: corepack enable
+
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --immutable
 
       - name: Run tests
-        run: npm test
+        run: yarn test
         env:
           BASE: ${{ github.event.pull_request.base.ref }}

.github/workflows/validate-markdown.yaml

@@ -25,21 +25,11 @@ jobs:
         with:
           node-version: "24.x"
 
-      - name: Lint markdown
-        run: npx --yes markdownlint-cli2 --config .markdownlint.yaml npx markdownlint-cli2 *.md schemas/**/*.md versions/*.md
-
-      # workaround for https://github.com/UmbrellaDocs/action-linkspector/issues/62
-      - name: Install Chrome
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y google-chrome-stable
-          echo "PUPPETEER_SKIP_DOWNLOAD=true" >> $GITHUB_ENV
-          echo "PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome" >> $GITHUB_ENV
-
-      - name: Check links in markdown files
-        uses: umbrelladocs/action-linkspector@v1.5.5
-        with:
-          config_file: .linkspector.yml
-          reporter: github-check
-          fail_level: any
-          filter_mode: file
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Validate Markdown
+        run: yarn validate-markdown

.gitignore

@@ -5,6 +5,7 @@
 target
 atlassian-ide-plugin.xml
 node_modules/
+.yarn/
 deploy/
 deploy-preview/
 coverage/

.linkspector.yml

@@ -1,3 +1,5 @@
 dirs:
   - ./
 useGitIgnore: true
+ignorePatterns:
+  - pattern: 'stackoverflow.com' # has bot protection

.nvmrc

@@ -0,0 +1 @@
+24

.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+approvedGitRepositories:
+  - https://github.com/OAI/build-infra.git

CONTRIBUTING.md

@@ -24,6 +24,23 @@ The [spec site](https://spec.openapis.org) is the source of truth for the OpenAP
 The OpenAPI project is almost entirely staffed by volunteers.
 Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world.
 
+## Shared infrastructure
+
+This repository uses the shared OpenAPI Initiative infrastructure package
+[`@oai/build-infra`](https://github.com/OAI/build-infra) for Markdown
+validation, HTML builds, schema publication, schema tests, and release helper
+commands. The Yarn scripts in this repository are intentionally thin wrappers
+around that package.
+
+The shared infrastructure docs explain how the tooling works and how to maintain
+it:
+
+- [build-infra README](https://github.com/OAI/build-infra/blob/main/README.md)
+- [build-infra CONTRIBUTING](https://github.com/OAI/build-infra/blob/main/CONTRIBUTING.md)
+
+Most contributors only need the commands shown below. Maintainers changing the
+tooling itself should read the build-infra docs first.
+
 ## Pull Requests
 
 Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start.
@@ -55,24 +72,25 @@ Additionally, all pull requests that change specification files in the `versions
 We use ReSpec to render the markdown specification as HTML for publishing and easier reading.
 These instructions explain how you can build the HTML locally.
 
-You will need NodeJS 18 or later.
+You will need Node.js 24 and Yarn 4.18 (via Corepack).
 
 Install dependencies:
 
 ```sh
-npm install
+corepack enable
+yarn install
 ```
 
 Produce stand-alone HTML files for all final specifications in the local `deploy/overlay` folder:
 
 ```sh
-npm run build
+yarn build
 ```
 
 Produce stand-alone HTML files for all work-in-progress specifications in the local `deploy-preview` folder:
 
 ```sh
-npm run build-dev
+yarn build-src
 ```
 
 ## Publishing
@@ -86,13 +104,13 @@ The steps for creating a `vX.Y.Z-rel` branch are:
 
 1. Update `EDITORS.md` in a temporary branch and merge changes back into `main` via pull request
 2. Prepare spec files in a temporary branch:
-   - `npm run format-markdown`
-   - `npm run build-dev`
+   - `yarn format-markdown`
+   - `yarn build-src`
    - open `deploy-preview/X.Y.Z-dev.html` in browser and verify correct formatting
    - adjust and repeat until done
    - merge changes back into `main` via pull request
 3. Create branch `vX.Y.Z-rel` from `main` in the OAI/Overlay-Specification repo and adjust it
-   - the bash script `scripts/adjust-release-branch.sh` does this:
+   - `yarn adjust-release-branch` does this:
      - move file `versions/X.Y.Z-dev.md` to `versions/X.Y.Z.md` and replace the release date placeholder `| TBD |` in the history table of Appendix A with the current date
      - copy file `EDITORS.md` to `versions/X.Y.Z-editors.md`
      - for an X.Y.0 release
@@ -109,7 +127,7 @@ Schema iterations are generated from the YAML source files in `schemas/vX.Y` by
 
 Once the released specification version is published, the next patch version X.Y.(Z+1) can be started:
 
-1. Run bash script `scripts/start-release.sh X.Y.(Z+1)` in branch `main` to
+1. Run `yarn start-release X.Y.(Z+1)` in branch `main` to
    - create branch `start-X.Y.(Z+1)`
    - initialize `versions/X.Y.(Z+1)-dev.md` with empty history and content from `versions/X.Y.Z.md`
    - change version heading to X.Y.(Z+1) and add a new line to the version history table in Appendix A
@@ -120,7 +138,7 @@ Once the released specification version is published, the next patch version X.Y
 
 A new minor version X.(Y+1).0 or major version (X+1).0.0 is started similarly:
 
-1. Run bash script `scripts/start-release.sh X'.Y'.0` in branch `main` to
+1. Run `yarn start-release X'.Y'.0` in branch `main` to
    - create branch `start-X'.Y'.0`
    - initialize `versions/X'.Y'.0-dev.md` with empty history and content from `versions/X.Y.Z.md`
    - change version heading to X'.Y'.0 and add a new line to the version history table in Appendix A
@@ -134,7 +152,7 @@ A new minor version X.(Y+1).0 or major version (X+1).0.0 is started similarly:
 If you are running those scripts using Windows Subsystems for Linux (WSL), and cloned the repository under windows, you'll need to make a few adjustments before you can run these procedures:
 
 1. Save the scripts using LF, not CRLF to avoid parsing issues. You can use VSCode or any other editor to do that. Alternatively, you may clone the repository again from WSL to workaround the line return issue.
-1. Make sure you run the npm install from WSL and not from windows.
+1. Make sure you run the yarn install from WSL and not from windows.
 1. If you run into issues launching chrome, [review this StackOverflow answer](https://stackoverflow.com/a/78776116/3808675).
 
 ## Style guide for Overlay Specification

README.md

@@ -4,6 +4,13 @@ The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defin
 
 This specification is a community-driven, open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
 
+Build, test, schema publication, and release command infrastructure is shared
+with other OpenAPI Initiative specification repositories through
+[OAI/build-infra](https://github.com/OAI/build-infra). See that repository's
+[README](https://github.com/OAI/build-infra/blob/main/README.md) and
+[CONTRIBUTING guide](https://github.com/OAI/build-infra/blob/main/CONTRIBUTING.md)
+for details on the shared tooling.
+
 Overlays support a range of scenarios, including:
 
 - Translating documentation into another language