Workflow to publish schemas

[ralfhandl]

• GitHub workflow
• bash script called from workflow
• JS script to convert YAML to JSON and patch iteration date
• unit tests for JS script
• Align with outcome of
  • schemas: add WORK-IN-PROGRESS placeholders, don't mention patch numbers, update terminology #4146

Example PR created by this workflow

• https://github.com/ralfhandl/OpenAPI-Specification/pull/26/files

[karenetheridge]

to confirm, these are both edited in the files?

• dates in the $id keywords
• $comment links in each definition, that currently go to the 3.1.0 spec and should go to 3.1.1

[ralfhandl]

• What about the dates in the $ids?

Those are replaced when converting from YAML to JSON, see example PR https://github.com/ralfhandl/OpenAPI-Specification/pull/26/files

[ralfhandl]

• What about the description links in each definition, that currently go to the 3.1.0 spec and should go to 3.1.1?

These need to be adjusted manually. Changing them in main will then trigger the schema-publish workflow.

[handrews]

Thanks for doing this work! To the extend that I understand current JavaScript, this looks great.

However, I'd like to merge #4146 and update this PR accordingly before publishing any new schemas. Let's make sure that when we resume publication after such a long gap, the first newly-published schemas are what we want.

Unfortunately, this does introduce a complexity, which is that the various 3.1 schema resources (of which there are four) can change independently. Ideally, we would only re-publish and update the $id for each when it changes, although it would not be the end of the world to just publish all four at once with the same updated data whenever any of them change. For the first publication, we'll need to do that anyway, so perhaps supporting independent updating can be something for later to keep the immediate work manageable?

I believe that the search-and-replace could just become a global grep for WORK-IN-PROGRESS once #4146 is merged, rather than worrying about parsing anything. We'd have to know not to put "WORK-IN-PROGRESS" anywhere else in the schemas, but that shouldn't be too hard to document.

It's worth noting that there are more places than id, $id, and $ref where the replacement needs to be done, so a global grep for a unique token would be more robust anyway.