Merge pull request #5550 from OAI/dev-sync-with-main

dev: sync with main

Author: handrews

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

@@ -49,6 +49,8 @@ jobs:
             # exclude mjs files because we want to sync from the head
             # neutralizes non-zero exit code because an empty selection result returns 1
             git checkout origin/$BASE -- tests/schema/ ':!*.mjs' || echo ""
+            # Preserve the destination branch's schema test runner.
+            git checkout "origin/$BASE" -- tests/schema/schema.test.mjs
             git commit -m "Restored src/ and tests/schema/" || echo ""
             git push -u origin $SYNC
 

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

@@ -45,6 +45,8 @@ jobs:
           # exclude mjs files because we want to sync from the head
           # neutralizes non-zero exit code because an empty selection result returns 1
           git checkout origin/$BASE -- tests/schema/ ':!*.mjs' || echo ""
+          # Preserve the destination branch's schema test runner.
+          git checkout "origin/$BASE" -- tests/schema/schema.test.mjs
           git commit -m "Restored src/ and tests/schema/" || echo ""
           git push -u origin $SYNC
 

CONTRIBUTING.md

@@ -234,7 +234,12 @@ Reviews requesting changes should have their changes addressed regardless of how
 The specification versions are published to the [spec site](https://spec.openapis.org/oas) 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 steps for creating a `vX.Y.Z-rel` branch are:
+Before you start check that you have:
+
+- release notes
+- approval by TSC vote for the content you are releasing
+
+The steps for publishing a new specification version are:
 
 1. Update `EDITORS.md` on `main`
 2. Merge `main` into `dev` and `dev` into `vX.Y-dev` via PRs
@@ -245,18 +250,24 @@ The steps for creating a `vX.Y.Z-rel` branch are:
    - 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
-   - `yarn adjust-release-branch` does this:
+4. Create a branch `vX.Y.Z-rel` from `vX.Y-dev` and use `yarn adjust-release-branch` to adjust it.
+   - `yarn adjust-release-branch` does the following:
      - copy file `src/oas.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`
      - delete folder `src`
      - delete version-specific files and folders from `tests/schema`
        - file `schema.test.mjs`
        - folders `pass` and `fail`
+   - the changes are now staged; use `git diff --cached` to review them (it is expected that a lot of files show as deleted)
+   - commit the changes
 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`
+6. Tag a release using GitHub's Releases feature; add the release notes as the description (don't autogenerate release notes).
+7. Manually trigger the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml). This workflow:
+   - generates HTML renderings of the files in the `versions/` directory of the main branch on this repository
+   - opens a pull request on the [repository for the spec site](https://github.com/OAI/spec.openapis.org)
 
-The HTML renderings of the specification versions are generated from the `versions` directory on `main` by manually triggering 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).
+   When that pull request is merged, the specification is included on the [spec site](https://spec.openapis.org)
 
 The release commands are implemented in
 [`OAI/build-infra`](https://github.com/OAI/build-infra). If a command behaves

spec.config.json

@@ -26,7 +26,7 @@
     },
     {
       "value": "Commit history",
-      "href": "https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"
+      "href": "https://github.com/OAI/OpenAPI-Specification/commits/main/versions/{version}.md"
     },
     {
       "value": "Pull requests",

versions/3.2.1-editors.md

@@ -0,0 +1,22 @@
+# OpenAPI Specification Editors
+
+## Active
+
+* Henry Andrews [@handrews](https://github.com/handrews)
+* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
+* Karen Etheridge [@karenetheridge](https://github.com/karenetheridge)
+* Lorna Mitchell [@lornajane](https://github.com/lornajane)
+* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
+* Miguel Quintero [@miqui](https://github.com/miqui)
+* Mike Kistler [@mikekistler](https://github.com/mikekistler)
+* Ralf Handl [@ralfhandl](https://github.com/ralfhandl)
+* Vincent Biret [@baywet](https://github.com/baywet)
+
+## Emeritus
+
+* Ron Ratovsky [@webron](https://github.com/webron)
+* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
+* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
+* Uri Sarid [@usarid](https://github.com/usarid)
+* Jason Harmon [@jharmn](https://github.com/jharmn)
+* Tony Tam [@fehguy](https://github.com/fehguy)