From d14327b9062b0adbfe8d26c937845efdb2a9b39d Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 18 Mar 2025 09:22:02 +0100 Subject: [PATCH 01/10] Update package.json --- package.json | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/package.json b/package.json index 92b537ad2a..99c702f24d 100644 --- a/package.json +++ b/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": "tsc@openapis.org", @@ -16,11 +16,6 @@ "build": "bash ./scripts/md2html/build.sh", "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh" }, - "readmeFilename": "README.md", - "files": [ - "README.md", - "schemas/*" - ], "dependencies": { "cheerio": "^1.0.0-rc.5", "highlight.js": "^11.11.1", From 7a4a5d5aff89cc4a3b2222b4b2ca435fe6b2e67c Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 18 Mar 2025 11:00:59 +0100 Subject: [PATCH 02/10] Create adjust-release-branch.sh --- scripts/adjust-release-branch.sh | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 scripts/adjust-release-branch.sh diff --git a/scripts/adjust-release-branch.sh b/scripts/adjust-release-branch.sh new file mode 100644 index 0000000000..bbf0288602 --- /dev/null +++ b/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 From 9ba315de2aa291c44d23e323085721f2f36fe60b Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 18 Mar 2025 11:15:08 +0100 Subject: [PATCH 03/10] Make executable --- scripts/adjust-release-branch.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 scripts/adjust-release-branch.sh diff --git a/scripts/adjust-release-branch.sh b/scripts/adjust-release-branch.sh old mode 100644 new mode 100755 From b1f703ff6526caa8ad9250ef02bc5d037e6d3c5e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 19 Mar 2025 09:41:28 +0100 Subject: [PATCH 04/10] Mention in CONTRIBUTING.md --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fe1da2283..b21a477ab1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -199,7 +199,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 +211,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` From ac7946e573edaa765496af4e69a2eb3fa611db4a Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 19 Mar 2025 10:00:21 +0100 Subject: [PATCH 05/10] Hint for Windows users --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4e9a54a4f..1a952cf4f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -172,6 +172,8 @@ To do this locally, please 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) + > [!NOTE] Use Git Bash on Windows + > This npm script calls bash scripts. Run it from [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL). 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. From d53c93ca16b8ef9cd7f52c1cc86846d264ca58ff Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 20 Mar 2025 18:48:37 +0100 Subject: [PATCH 06/10] Port from dev --- .github/workflows/schema-publish.yaml | 20 +++-- .github/workflows/validate-markdown.yaml | 4 +- package.json | 5 +- scripts/schema-publish.sh | 106 ++++++++++++++--------- scripts/yaml2json/yaml2json.js | 30 ------- 5 files changed, 83 insertions(+), 82 deletions(-) delete mode 100755 scripts/yaml2json/yaml2json.js diff --git a/.github/workflows/schema-publish.yaml b/.github/workflows/schema-publish.yaml index 0206ef56fa..568990ea6e 100644 --- a/.github/workflows/schema-publish.yaml +++ b/.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. diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml index 54a847d69f..ec7d69d10f 100644 --- a/.github/workflows/validate-markdown.yaml +++ b/.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 diff --git a/package.json b/package.json index 92b537ad2a..b355a048ef 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,10 @@ "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": [ diff --git a/scripts/schema-publish.sh b/scripts/schema-publish.sh index d1a7f822bd..54d55fc80f 100755 --- a/scripts/schema-publish.sh +++ b/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 diff --git a/scripts/yaml2json/yaml2json.js b/scripts/yaml2json/yaml2json.js deleted file mode 100755 index decb075cc7..0000000000 --- a/scripts/yaml2json/yaml2json.js +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env node - -'use strict'; - -const fs = require('fs'); -const yaml = require('yaml'); - -function convert(filename) { - // console.log(filename); - const s = fs.readFileSync(filename,'utf8'); - let obj; - try { - obj = yaml.parse(s, {prettyErrors: true}); - fs.writeFileSync(filename.replace('.yaml','.json'),JSON.stringify(obj,null,2),'utf8'); - } - catch (ex) { - console.warn(' ',ex.message); - process.exitCode = 1; - } -} - -if (process.argv.length<3) { - console.warn('Usage: yaml2json {infiles}'); -} -else { - for (let i=2;i Date: Fri, 21 Mar 2025 16:23:33 +0100 Subject: [PATCH 07/10] Update issue templates Pressing the "New issue" button leads to an endless loop: - It shows a "Create new issue popup" with many options, the second and third to last are "Please open an issue in this repository!". - Pressing one of these redirects to https://github.com/OAI/OpenAPI-Specification/issues/new/choose, which is a full-page version of the popup, and in turn only opens additional tabs with the same page. I hope that adding a "Bug report" template will break that loop. --- .github/ISSUE_TEMPLATE/bug_report.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000..3095d2e7bb --- /dev/null +++ b/.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. From d49cb6f3f78dce100150b3e88ce15c777bc74ae7 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 24 Mar 2025 07:40:34 +0000 Subject: [PATCH 08/10] Bump respec from 35.2.3 to 35.3.0 Bumps [respec](https://github.com/speced/respec) from 35.2.3 to 35.3.0. - [Release notes](https://github.com/speced/respec/releases) - [Changelog](https://github.com/speced/respec/blob/main/CHANGELOG.md) - [Commits](https://github.com/speced/respec/compare/v35.2.3...v35.3.0) --- updated-dependencies: - dependency-name: respec dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- package-lock.json | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index 6c13e2e748..9f426c8a0d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,18 +1,18 @@ { "name": "oas-schemas", - "version": "2.0.0", + "version": "0.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "oas-schemas", - "version": "2.0.0", + "version": "0.0.0", "license": "Apache-2.0", "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": { @@ -4280,9 +4280,9 @@ } }, "node_modules/respec": { - "version": "35.2.3", - "resolved": "https://registry.npmjs.org/respec/-/respec-35.2.3.tgz", - "integrity": "sha512-/nu8qOLdHUzKNMUKM9YgTFK+AW0M1qYZxGlqqIHgm4OlpPpCXqPvAcI/RrGjJohXZc67Hz6qXFZ0rEiPvvwFIg==", + "version": "35.3.0", + "resolved": "https://registry.npmjs.org/respec/-/respec-35.3.0.tgz", + "integrity": "sha512-O5yFnTyFHUH7BwfhvEIPUiFEHUP+qrf3lcOaRSw33jF2+gJ6bUeXUpVEnfGdHbi6tmIQUnX3qnYDddIQHjsU2Q==", "license": "W3C", "dependencies": { "colors": "1.4.0", diff --git a/package.json b/package.json index aff5195087..3d8f11d40f 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,7 @@ "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": { From bbafa53287d3f15de7f0953cc7d0d9e5f7cd137b Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 24 Mar 2025 11:30:59 +0100 Subject: [PATCH 09/10] Update CONTRIBUTING.md Note callouts apparently can't be below bullet list items. Moving it to the end of the section. --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b39ab0ae0..cd9d824e80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -172,12 +172,13 @@ To do this locally, please 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) - > [!NOTE] Use Git Bash on Windows - > This npm script calls bash scripts. Run it from [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL). 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. +> [!NOTE] +> `npm run build-src` calls bash scripts. Use [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL). + ## Reviewers > [!NOTE] From 8be81a50c9619c14e8da65ede1022e6e17b23c8e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 24 Mar 2025 11:41:35 +0100 Subject: [PATCH 10/10] @lornajane's proposal --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd9d824e80..af61e86267 100644 --- a/CONTRIBUTING.md +++ b/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 @@ -176,9 +179,6 @@ To do this locally, please 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. -> [!NOTE] -> `npm run build-src` calls bash scripts. Use [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL). - ## Reviewers > [!NOTE]