Update schema-publish.sh

[duncanbeevers]

Fixes#4223

🗣️ Discussion

This PR brings the schema publishing workflow into closer alignment with the specification publishing workflow.

🔧 Under-the-hood changes

• Configure deploydir based on branch name
• Check branch name for conformance to vX.Y-dev structure
  • build to /deploy/oas/$version if branch name is conformant
  • build to /deploy-preview if branch name is non-conformant
• Perform only one traversal of schemas structure
• Remove datesHash data structure
• Accumulate sed sub-commands & invoke with sed single -e argument

🧑 Contributor-facing Changes

• Schema publishing process works out-of-the-box on macOS

  A side-effect of removing intermediate data structures is that we avoid bash-4-isms, enabling out-of-the-box builds on modern macOS versions which ship an old 3.2.57 bash version.
• Schema publishing process from ad-hoc branch names produces sensible artifacts

🚗 Demo

This screenshot demonstrates running the scripts/schema-publish.sh script from different branch names.
It also includes an interrogation of a generated schema file in order to validate that all of its placeholders are replaced correctly. (Thanks @ralfhandl!)

[ralfhandl]

This command seems to have been lost. It is necessary when building to deploy/ for the

• view schema/2024-11-14

links on https://spec.openapis.org to work.

[duncanbeevers]

I saw that command, but couldn't reason what it was doing, since no .md files are generated in /deploy/**.
Running the script with a clean or missing /deploy makes it a no-op.

Can you point to me where the link-updating bit happens, or show me where the .md files make their way to /deploy?

[ralfhandl]

The *.md files only exist in the gh-pages branch, for example in https://github.com/OAI/OpenAPI-Specification/tree/gh-pages/oas/3.1/schema.

The title of each file is specific to that file, and I didn't want to hard-code them in the build script to minimize the differences between the OpenAPI, Overlay, and Arazzo copies of the build script.

[duncanbeevers]

I'll re-add this command, but I think it indicates a weird space in the abstraction. It seems contradictory to me to both mkdir -p deploy/oas/3.1.1and to expect that there are already markdown files present there.

I also think it's a bad pattern to do a mv where the input could be multiple files, but the destination is a single file.

It looks like the file we expect to move is actually named the same as $date. Short of restoring latest, could I just move that one $date.md file?

Alternatively, we could go back to having a latest.md, but on publish, rename it to match the latest iteration of the schema. This would preserve the publishing behavior (not creating a latest link or schema), while still removing step of manually renaming the .md file with each revision and allowing us to reference a stable filename for copying in this script.

[duncanbeevers]

I've pushed a change which replicates the current *.md behavior, as well as introduces some commented-out code probing the pain points mentioned in my comment above.

• 😐 One implementation supposes the .md file's name always matches the iteration date, which matches the current setup, and is still simpler than globbing files.

• 😄 One implementation supposes the .md file is always latest.md. This used to be the setup, but it was abandoned. I think this approach is best. See below for more articulation.

• 😞 One implementation mirrors the current behavior, but selects only the "first" markdown file encountered. This aligns better with the sentiment A mv command whose destination is a file should have a file as its first argument, but in a kind of nonsense way.

• 😞 The actual implementation mirrors the current behavior, attempting to copy all the markdown files in the deploy directory to $target.md. If there are multiple markdown files present this results in an error later in the script. The actual implementation mirrors the previous one with the head -n 1 removed, to highlight its similarities to that approach.

😄 latest.md is my favorite

The implementation which supposes a markdown file latest.md will be present is my favored approach.
🌿 indicates a benefit to the current process
🌐 indicates a benefit we already have, first gained by abandoning latest

• 🌿 Minimizes the steps necessary to begin iterating on a new version of the schemas
• 🌿 Minimizes the use of variables in build scripts. Not a big deal, but I love a static value when I can use one.
• 🌐 https://spec.openapis.org/oas/3.1/schema-base/latest continues to 404
• 🌐 https://spec.openapis.org/oas/3.1/schema-base/latest.html continues to 404
• 🌐 https://spec.openapis.org/oas/3.1/schema/2024-11-14.html continues to 200

[ralfhandl]

Good discussion, please move it over to

• Make the "latest" schema accessible programmatically #4152

[ralfhandl]

Almost there 😎

Could you extend the build-src npm script in

OpenAPI-Specification/package.json

Line 17 in 92e5fc9

"build-src": "npm run validate-markdown && bash ./scripts/md2html/build.sh src",

to also call this script?

"build-src": "npm run validate-markdown && bash ./scripts/md2html/build.sh src && bash ./scripts/schema-publish.sh",

[ralfhandl]

Good discussion, please move it over to

• Make the "latest" schema accessible programmatically #4152

[ralfhandl]

Almost there. And please trust me, I've tested it on a v9.9-dev branch 😄

[ralfhandl]

Thanks!

[duncanbeevers]

I'm going squash this to a single commit to avoid another fixup! commit hitting main.