From d368f3562cb41812e2a506c1032ed9bdd4321a9a Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 14 Feb 2025 13:47:00 +0100 Subject: [PATCH 1/2] Describe publishing process Fixes #3715 --- CONTRIBUTING.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 246fa567bd..94be0a8887 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -177,13 +177,19 @@ Reviews requesting changes should have their changes addressed regardless of how ## Publishing -The specification are published to the [spec site](https://spec.openapis.org) 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`. -The HTML versions of the OAS are automatically generated from the `versions` directory on `main`. +### Specification Versions + +The specification versions are published to the [spec site](https://spec.openapis.org) 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 schemas are published [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). -As part of the publishing process, the `WORK-IN-PROGRESS` placeholders are replaced with dates as appropriate. -Schemas are published/updated independently from the specification releases. +The HTML renderings of the specification versions are automatically generated from the `versions` directory on `main` by 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). + +### Schema Iterations + +The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). +Schemas are updated in and directly published from the `vX.Y-dev` branches. + +As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is done by the `schema-publish` workflow on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). ## Release Process and Scope From d27078e27ea1928c48a00115e03d78ef9e19e9f4 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 20 Feb 2025 17:55:26 +0000 Subject: [PATCH 2/2] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94be0a8887..cf8ec33444 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -189,7 +189,7 @@ The HTML renderings of the specification versions are automatically generated fr The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). Schemas are updated in and directly published from the `vX.Y-dev` branches. -As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is done by the `schema-publish` workflow on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). +As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the `schema-publish` workflow which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required. ## Release Process and Scope