diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1f29b0..d46c0b8 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/package.json b/package.json index e9f5892..6a321d4 100644 --- a/package.json +++ b/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" } diff --git a/scripts/adjust-release-branch.sh b/scripts/adjust-release-branch.sh new file mode 100644 index 0000000..28ecc1a --- /dev/null +++ b/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 diff --git a/scripts/format-markdown.sh b/scripts/format-markdown.sh deleted file mode 100755 index 18a4d2a..0000000 --- a/scripts/format-markdown.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/bin/bash - -SRCDIR="$(dirname "${BASH_SOURCE[0]}")" # check on Windows - -for filename in $*; do - # mostly to format code blocks with examples, unfortunately messes up bullet lists and tables - npx prettier --write --single-quote $filename - - # repair the tables: remove superfluos spaces and dashes that make diffing revisions harder - # and sed -i is not portable, so we need to use a temporary file - sed -E -e "s/ +\|/ |/g" -e "s/\| +/| /g" -e "s/-----+/----/g" $filename > $filename.tmp && mv $filename.tmp $filename - - # repair the bullet lists and various other markdown formatting issues - npx --yes markdownlint-cli2 --fix --config $SRCDIR/../.markdownlint.yaml $filename -done diff --git a/scripts/start-release.sh b/scripts/start-release.sh new file mode 100644 index 0000000..04a93c2 --- /dev/null +++ b/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 " + 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