Describe steps for publishing a release and starting a new release

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,60 @@ 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 into `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. Commit, push, and 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 X.Y.(Z+1)` in branch `main` to
+   - create branch `start-X.Y.(Z+1)`
+   - initialize `versions/X.Y.(Z+1)-dev.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
+   - commit changes
+2. Push branch `start-X.Y.(Z+1)` and merge 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. Run bash script `scripts/start-release.sh X'.Y'.0` in branch `main` to
+   - create branch `start-X'.Y'.0`
+   - initialize `versions/X'.Y'.0-dev.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
+   - copy schema files `schemas/vX.Y` to `schemas/vX'.YY'-dev` and change version in all schema files
+   - copy schema tests `tests/vX.Y` to `tests/vX'.YY'-dev` and change version in all test files
+   - commit changes
+2. Push branch `start-X'.Y'.0` and merge into `main` 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

scripts/start-release.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+
+# Author: @ralfhandl
+
+# Run this script from the root of the repo. It is designed to be run manually in the main branch.
+
+if [[ ! $1 =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Usage: $0 <nextVersion>"
+  echo "Example: $0 1.1.1"
+  exit 1
+fi
+
+nextVersion=$1
+minor=$(echo $nextVersion | cut -d. -f1,2)
+nextPatch=$(echo $nextVersion | cut -d. -f3)
+
+# Find last published spec version for this minor version
+lastSpec=$(ls -1 versions/*.md | grep -E "/$minor\.[0-9].md" | tail -1)
+
+if [ -z "$lastSpec" ]; then
+  # Find last published spec version
+  lastSpec=$(ls -1 versions/*.md | grep -E "/.+\.[0-9].md" | tail -1)
+  releaseType="Release"
+else
+  lastPatch=$(basename "$lastSpec" ".md" | cut --delimiter=. --fields=3)
+  releaseType="Patch release"
+fi
+
+if [ -z "$lastSpec" ]; then
+  echo "Could not find any published specification version"
+  exit 1
+fi
+
+lastVersion=$(basename "$lastSpec" ".md")
+echo === Initialize src/oas.md for $nextVersion from $lastVersion
+
+# Create PR branch from development branch
+branch=$(git branch --show-current)
+prBranch="start-$nextVersion"
+if ! git checkout -b "$prBranch"; then
+  echo "=== Failed: PR branch $prBranch already exists locally, please delete it and try again"
+  exit 1  
+fi
+
+# create dev version of spec from last published spec
+temp=$(mktemp)
+
+# bump version headline, add line to history table
+historyTableHeader="\n| Version | Date | Notes |\n| ---- | ---- | ---- |\n"
+sed -z -e "s/\n## Version $lastVersion\n/\n## Version $nextVersion\n/" \
+    -z -e "s/$historyTableHeader/$historyTableHeader| $nextVersion | TBD | $releaseType of the Overlay Specification $nextVersion |\n/" \
+    "$lastSpec" > versions/$nextVersion-dev.md
+
+git add versions/$nextVersion-dev.md
+git commit -m "initialize $nextVersion from $lastVersion"
+
+echo === Initialized versions/$nextVersion-dev.md 
+
+# when starting a new major or minor version
+if [ "$nextPatch" == "0" ]; then
+  lastMinor=$(echo "$lastVersion" | cut -d . -f 1,2)
+
+  echo === Initialize schemas for new version $minor
+  cp -r "schemas/v$lastMinor" "schemas/v$minor-dev"
+
+  minorRegex=$(echo "$minor" | sed 's/\./\\\\\\./')
+  lastMinorRegex=$(echo "$lastMinor" | sed 's/\./\\\\\\./')
+
+  for file in schemas/v$minor-dev/*.yaml; do
+    sed -e "s/$lastMinor/$minor/g" \
+        -e "s/\^$lastMinorRegex\\\./\^$minorRegex\\\./g" \
+        "$file" > "$temp"
+    mv -f "$temp" "$file"
+  done
+
+  for file in schemas/v$minor-dev/*.md; do
+    sed -e "s/$lastMinor/$minor/g" \
+        "$file" > "$temp"
+    mv -f "$temp" "$file"
+  done
+
+  echo === Initialize tests for new version $minor
+  cp -r "tests/v$lastMinor" "tests/v$minor-dev"
+
+  for file in tests/v$minor-dev/{pass,fail}/*.yaml; do
+    sed -e "s/$lastMinor/$minor/g" "$file" > "$temp"
+    mv -f "$temp" "$file"
+  done
+
+  git add schemas/v$minor-dev tests/v$minor-dev
+  git commit -m "adjust schemas, test script, and test data"
+
+  echo === Adjusted schemas and tests
+fi
+
+# Clean up
+git switch "$branch"
+echo === Done