Better release docs. (#3)

* Better release docs.

* Add note to PR not to squash merge a release.

* Document when changes are not pushed to origin.

Author: razvan

release/README.md

@@ -2,18 +2,54 @@
 
 ## Install requirements
 
-Install Python 3 and required packages:
+### Python 3
+
+A working python 3 installation is required by the cargo-version.py script.
+
+Install required packages:
 
     pip install -r release/requirements.txt
 
+### Update PATH
+
 Add the `release` folder to your `PATH`.
 
+### Optional: GitHub CLI
+
+Optionally, if you want to have a GitHub Pull-Request automatically created, you need the GitHib command line tools installed and properly configured. See https://cli.github.com/.
+
 ## Usage
 
 Go to the folder containing a Cargo workspace or crate and run:
 
-    release.sh [major|minor|patch]
+    release.sh [major|minor|patch] [false]
 
 This pushes two commits in a newly created release branch. When merging, __do not squash them__.
 
+Examples:
+
+    # Perform release raise the minor version
+    $ release.sh
+
+    # Perform a release but do not push anything to origin
+    $ release.sh minor false
+
+    # Perform a release and raise the major version
+    $ release.sh major
+
+## Description
+
+The release process performs the following steps:
+0. Create a release branch from `main`.
+1. Update the release version in the cargo workspace by dropping the "-nightly" token.
+2. Update `Cargo.lock` with the new version.
+3. Commit and tag the release.
+4. Set the version to the next development version by increasing the 'minor' (by default) part and adding the '-nightly' prerelease token.
+5. Update `Cargo.lock` with the new version.
+6. Commit the next release.
+7. Push the two commits. This is skipped if the second argument was `false`.
+8. __Optional__: if the GitHub cli is installed, a PR is created.  This is also skipped if the second argument was `false`.
+
+## Future development
 
+Automatically update the change log and readme files.

release/release.sh

@@ -25,7 +25,7 @@ maybe_create_github_pr() {
   local TAG=$1
   GH_COMMAND=$(which gh)
   if [ "$GH_COMMAND" != "" ]; then
-    gh pr create --base $BASE_BRANCH --head $RELEASE_BRANCH --reviewer "@stackabletech/rust-developers" --title "Release $TAG" --body "Release $TAG"
+    gh pr create --base $BASE_BRANCH --head $RELEASE_BRANCH --reviewer "@stackabletech/rust-developers" --title "Release $TAG" --body "Release $TAG. DO NOT SQUASH MERGE!"
   fi
 }
 
@@ -50,13 +50,13 @@ main() {
   #
   cargo-version.py --next ${NEXT_LEVEL}
   cargo update --workspace
-  TAG=$(cargo-version.py --show)
-  git commit -am "bump version $TAG"
+  local NEXT_TAG=$(cargo-version.py --show)
+  git commit -am "bump version $NEXT_TAG"
 
   if [ "$PUSH" = "true" ]; then
     git push ${REPOSITORY} ${RELEASE_BRANCH} 
     git push --tags
-    maybe_create_github_pr $TAG_NAME
+    maybe_create_github_pr $TAG
   fi
 }