Release steps

Author: ralfhandl

CONTRIBUTING.md

@@ -42,7 +42,7 @@ The `main` branch holds
 - sources for work-in-progress schema versions in `schemas/vX.Y-dev` folders and their tests in `tests/vX.Y-dev` folders,
 - utility scripts and supporting documentation.
 
-Other branches are usually short-lived, for example and for maintaining utility scripts.
+Other branches are usually short-lived, for example for maintaining utility scripts.
 
 ### Reviewers
 
@@ -75,6 +75,62 @@ Produce stand-alone HTML files for all work-in-progress specifications in the lo
 npm run build-dev
 ```
 
+## Publishing
+
+### Specification Versions
+
+The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `versions/X.Y.Z-dev.md` is renamed to `versions/X.Y.Z.md` and then merged to `main`.
+This renaming preserves the commit history when using `git log --follow`.
+
+The steps for creating a `vX.Y.Z-rel` branch are:
+
+1. Update `EDITORS.md` in a temporary branch and merge changes back into `main` via pull request
+2. Prepare spec files in a temporary branch:
+   - `npm run format-markdown`
+   - `npm run build-dev`
+   - open `deploy-preview/X.Y.Z-dev.html` in browser and verify correct formatting
+   - adjust and repeat until done
+   - merge changes back into `main` via pull request
+3. Create branch `vX.Y.Z-rel` from `main` in the OAI/Overlay-Specification repo and adjust it
+   - the bash script `scripts/adjust-release-branch.sh` does this:
+     - move file `versions/X.Y.Z-dev.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`
+     - for an X.Y.0 release
+       - move folder `schemas/vX.Y-dev` to `schemas/vX.Y`
+       - move folder `tests/vX.Y-dev` to `tests/vX.Y`
+4. Merge `vX.Y.Z-rel` into `main` via pull request
+5. Archive branch `vX.Y.Z-rel`
+
+HTML renderings of the specification versions are generated from the `versions` folder on `main` by the `respec` workflow on changes to files in that folder, which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org/overlay). The workflow can be run manually if required.
+
+Schema iterations are generated from the YAML source files in `schemas/vX.Y` by converting them to JSON, renaming to the relevant last-changed dates, and replacing the `WORK-IN-PROGRESS` placeholders with these dates. This is done by the `schema-publish` workflow on changes to files in these folders, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org/overlay). The workflow can be run manually if required.
+
+<!-- #### Start Next Patch Version
+
+Once the released specification version is published, the next patch version X.Y.(Z+1) can be started:
+
+1. Run bash script `scripts/start-release.sh` in branch `main` to
+   - create branch `vX.Y-dev-start-X.Y.(Z+1)`
+   - initialize `src/oas.md` with empty history and content from `versions/X.Y.Z.md`
+   - change version heading to X.Y.(Z+1) and add a new line to the version history table in Appendix A of `src/oas.md`
+   - commit and push changes
+2. Merge changes into `main` via pull request
+
+#### Start New Minor or Major Version
+
+A new minor version X.(Y+1).0 or major version (X+1).0.0 is started similarly:
+
+1. Create branch `vX'.Y'-dev` from `vX.Y-dev`
+2. Run bash script `scripts/start-release.sh` in the new branch to
+   - create branch `vX'.Y'-dev-start-X'.Y'.0`
+   - initialize `src/oas.md` with empty history and content from `versions/X.Y.Z.md`
+   - change version heading to X'.Y'.0 and add a new line to the version history table in Appendix A of `src/oas.md`
+   - change version in all schema files `src/schemas/validation/.yaml`
+   - change version in schema test script `tests/schema/schema.test.mjs`
+   - change version in schema test fixtures in folders `tests/schema/pass` and `tests/schema/fail`
+   - commit and push changes
+3. Merge `vX'.Y'-dev-start-X'.Y'.0` into `vX'.Y'-dev` via pull request -->
+
 ## Style guide for Overlay Specification
 
 Some terminology and when to use it:

package.json

@@ -41,7 +41,7 @@
   "scripts": {
     "build": "bash ./scripts/md2html/build.sh",
     "build-dev": "npm run validate-markdown && bash ./scripts/md2html/build.sh dev && bash ./scripts/schema-publish.sh dev",
-    "format-markdown": "bash ./scripts/format-markdown.sh *.md schemas/**/*.md versions/*.md",
+    "format-markdown": "npx markdownlint-cli2 --fix *.md schemas/**/*.md versions/*-dev.md",
     "validate-markdown": "markdownlint-cli2 *.md schemas/**/*.md versions/*.md && linkspector check",
     "test": "c8 --100 vitest run --coverage"
   }

scripts/adjust-release-branch.sh

@@ -0,0 +1,37 @@
+#!/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)
+today=$(date +%Y-%m-%d)
+
+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. v1.1.0-rel"
+  exit 1
+fi
+
+vVersion=$(basename "$branch" "-rel")
+version=${vVersion:1}
+echo Prepare release of $version
+
+# create snapshot of current editors
+cp EDITORS.md versions/$version-editors.md
+
+# "move" dev version of spec to release version - git will treat this as a rename
+# Replace release date placeholder with current date - should only appear in the history table
+sed "s/| TBD |/| $today |/g" versions/$version-dev.md > versions/$version.md
+# show what changed in the spec - should only be the history table line for the current release
+diff -Z versions/$version-dev.md versions/$version.md
+# remove dev version of spec
+rm versions/$version-dev.md
+
+# rename schemas dev folder and tests folder if present
+vMinor=$(echo $vVersion | cut -d. -f1,2)
+if [ -d "schemas/$vMinor-dev" ]; then
+  mv "schemas/$vMinor-dev" "schemas/$vMinor"
+fi
+if [ -d "tests/$vMinor-dev" ]; then
+  mv "tests/$vMinor-dev" "tests/$vMinor"
+fi