Comment adjustment steps and describe them

Author: ralfhandl

CONTRIBUTING.md

@@ -211,9 +211,9 @@ The steps for creating a `vX.Y.Z-rel` branch are:
    - merge changes to `src/oas.md` back into `vX.Y-dev` via PR
 4. Create `vX.Y.Z-rel` from `vX.Y-dev` and adjust it
    - the bash script `scripts/adjust-release-branch.sh` does this:
-     - move file `src/oas.md` to `versions/X.Y.Z.md`
+     - copy file `src/oas.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`
-     - delete folder `src/schemas`
+     - delete folder `src`
      - delete version-specific files and folders from `tests/schema`
        - file `schema.test.mjs`
        - folders `pass` and `fail`

scripts/adjust-release-branch.sh

@@ -16,9 +16,13 @@ vVersion=$(basename "$branch" "-rel")
 version=${vVersion:1}
 echo Prepare release of $version
 
+# create snapshot of current editors
 cp EDITORS.md versions/$version-editors.md
+# Replace release date placeholder with current date - should only appear in the history table
 sed "s/| TBD |/| $today |/g" src/oas.md > versions/$version.md
+# show what changed in the spec - should only be the history table line for the current release
 diff -w src/oas.md versions/$version.md
+# remove files that only exist in development branches and not on main
 rm -r src
 rm -r tests/schema/pass tests/schema/fail
 rm tests/schema/schema.test.mjs