Rename staging branch, drop time estimates, add --version override

Author: Joao-Dionisio

RELEASE.md

@@ -15,21 +15,27 @@ On the PR:
 
 ## Releasing PySCIPOpt
 
-Releases run in two phases from `master`, driven by `./release.sh`. The tag and master push only happen in phase 2, so a failed RC leaves no semantic public trace — just a deletable `release-candidate-vX.Y.Z` branch.
+Releases run in two phases from `master`, driven by `./release.sh`. The tag and master push only happen in phase 2, so an aborted release leaves no semantic public trace — just a deletable `staging-vX.Y.Z` branch.
 
 Use `--dry-run` with any command to preview without side effects.
 
-### Phase 1 — start a release candidate
+### Phase 1 — start
 
 ```bash
 ./release.sh
 ```
 
-Prompts for the version bump (patch/minor/major), updates `_version.py`, `setup.py`, and `CHANGELOG.md`, commits **locally**, pushes the commit to `release-candidate-vX.Y.Z` on origin, and triggers the build-wheels workflow on that branch (uploads to test-pypi). **Master is not pushed, no tag is created.** The script exits as soon as the workflow is dispatched — you do not wait.
+Prompts for the version bump (patch/minor/major), updates `_version.py`, `setup.py`, and `CHANGELOG.md`, commits **locally**, pushes the commit to `staging-vX.Y.Z` on origin, and triggers the build-wheels workflow on that branch (uploads to test-pypi). **Master is not pushed, no tag is created.** The script exits as soon as the workflow is dispatched.
+
+To skip the bump prompt (e.g., when test-pypi has already burnt the default next version and you need to jump ahead):
+
+```bash
+./release.sh --version=X.Y.Z
+```
 
 ### Manual verification
 
-Once the RC workflow finishes (~15–30 min), install from test-pypi and smoke-test:
+Once the staging workflow finishes, install from test-pypi and smoke-test:
 
 ```bash
 pip install -i https://test.pypi.org/simple/ PySCIPOpt==X.Y.Z
@@ -43,15 +49,15 @@ If the smoke test **passes**:
 ./release.sh --finalize
 ```
 
-Checks the RC workflow succeeded, then tags `vX.Y.Z`, pushes master, and deletes the RC branch.
+Checks the staging workflow succeeded, then tags `vX.Y.Z`, pushes master, and deletes the staging branch.
 
 If the smoke test **fails** (or you change your mind):
 
 ```bash
 ./release.sh --rollback
 ```
 
-Deletes the RC branch and resets the local release commit. test-pypi keeps the uploaded version string, so the next attempt must use a different bump.
+Deletes the staging branch and resets the local release commit. test-pypi has already burnt the uploaded version string, so the next attempt must use `--version=` to pick a different one.
 
 ### After finalize
 

release.sh

@@ -8,19 +8,25 @@ REPO="scipopt/PySCIPOpt"
 
 DRY_RUN=false
 ACTION=start
+NEW_VERSION_OVERRIDE=""
 for arg in "$@"; do
     case "$arg" in
         --dry-run) DRY_RUN=true ;;
         --finalize) ACTION=finalize ;;
         --rollback) ACTION=rollback ;;
+        --version=*) NEW_VERSION_OVERRIDE="${arg#--version=}" ;;
         -h|--help)
             cat <<USAGE
-Usage: $0 [--dry-run] [--finalize | --rollback]
-
-  (default)    Start a release candidate: bump version, push release-candidate-vX.Y.Z, trigger test-pypi build.
-  --finalize   Promote a successful candidate: tag vX.Y.Z, push master, delete RC branch. Requires the RC workflow to have succeeded.
-  --rollback   Abandon a candidate: delete RC branch, reset local release commit.
-  --dry-run    Preview without side effects. Combinable with --finalize/--rollback.
+Usage: $0 [--dry-run] [--version=X.Y.Z] [--finalize | --rollback]
+
+  (default)        Start a new release: bump version, push the staging branch,
+                   trigger the test-pypi build.
+  --version=X.Y.Z  Use this exact version instead of prompting for patch/minor/major.
+                   Useful if test-pypi has already burnt the default next version.
+  --finalize       Promote: tag vX.Y.Z, push master, delete the staging branch.
+                   Requires the staging workflow to have succeeded.
+  --rollback       Abandon: delete the staging branch and reset the local commit.
+  --dry-run        Preview without side effects. Combinable with the flags above.
 USAGE
             exit 0
             ;;
@@ -68,24 +74,24 @@ validate_version() {
     fi
 }
 
-# Promote a successful release candidate: tag, push master, clean up RC branch.
+# Promote a successful pending release: tag, push master, clean up staging branch.
 finalize_release() {
     local version="$1"
-    local rc_branch="release-candidate-v${version}"
+    local staging_branch="staging-v${version}"
 
-    echo "Pending release candidate: v${version}"
-    echo "Checking workflow status on ${rc_branch}..."
+    echo "Pending release: v${version}"
+    echo "Checking workflow status on ${staging_branch}..."
 
     local run_data run_count status conclusion url run_id
     run_data=$(gh run list --workflow=build_wheels.yml --repo "$REPO" \
-        --branch "$rc_branch" --limit 1 \
+        --branch "$staging_branch" --limit 1 \
         --json databaseId,status,conclusion,url 2>/dev/null || echo "[]")
     run_count=$(echo "$run_data" | jq 'length')
 
     if [[ "$run_count" == "0" ]]; then
-        echo "Error: no workflow run found for branch '${rc_branch}'."
+        echo "Error: no workflow run found for branch '${staging_branch}'."
         echo "Either wait a moment and try again, or clean up manually:"
-        echo "  git push ${PUSH_REMOTE} --delete ${rc_branch}"
+        echo "  git push ${PUSH_REMOTE} --delete ${staging_branch}"
         echo "  git reset --hard HEAD~1"
         exit 1
     fi
@@ -107,12 +113,12 @@ finalize_release() {
         echo "URL: ${url}"
         echo ""
         if [[ "$DRY_RUN" == true ]]; then
-            echo "DRY RUN: would prompt to roll back (delete ${rc_branch} + reset local commit)."
+            echo "DRY RUN: would prompt to roll back (delete ${staging_branch} + reset local commit)."
             exit 0
         fi
-        read -rp "Roll back (delete ${rc_branch} and reset local release commit)? [Y/n] " confirm
+        read -rp "Roll back (delete ${staging_branch} and reset local release commit)? [Y/n] " confirm
         if [[ ! "${confirm:-Y}" =~ ^[Nn] ]]; then
-            git push "$PUSH_REMOTE" --delete "$rc_branch" || echo "(note: remote RC delete failed; clean up manually)"
+            git push "$PUSH_REMOTE" --delete "$staging_branch" || echo "(note: remote staging branch delete failed; clean up manually)"
             git reset --hard HEAD~1
             echo "Rolled back. Repo is at pre-release state."
         fi
@@ -125,15 +131,15 @@ finalize_release() {
         echo "  git tag v${version}"
         echo "  git push ${PUSH_REMOTE} ${CURRENT_BRANCH}"
         echo "  git push ${PUSH_REMOTE} v${version}"
-        echo "  git push ${PUSH_REMOTE} --delete ${rc_branch}"
+        echo "  git push ${PUSH_REMOTE} --delete ${staging_branch}"
         exit 0
     fi
 
     echo "Workflow succeeded. Promoting release v${version}..."
     git tag "v${version}"
     git push "$PUSH_REMOTE" "$CURRENT_BRANCH"
     git push "$PUSH_REMOTE" "v${version}"
-    git push "$PUSH_REMOTE" --delete "$rc_branch"
+    git push "$PUSH_REMOTE" --delete "$staging_branch"
 
     echo ""
     echo "Done! v${version} is now tagged on ${PUSH_REMOTE}."
@@ -148,23 +154,23 @@ finalize_release() {
     echo "  4. Update readthedocs: Builds -> Build version (latest and stable)"
 }
 
-# Abandon a release candidate: delete RC branch, reset local release commit.
+# Abandon a pending release: delete staging branch, reset local release commit.
 rollback_release() {
     local version="$1"
-    local rc_branch="release-candidate-v${version}"
+    local staging_branch="staging-v${version}"
 
-    echo "Rolling back release candidate v${version}..."
+    echo "Rolling back pending release v${version}..."
     if [[ "$DRY_RUN" == true ]]; then
         echo "DRY RUN: would have run:"
-        echo "  git push ${PUSH_REMOTE} --delete ${rc_branch}"
+        echo "  git push ${PUSH_REMOTE} --delete ${staging_branch}"
         echo "  git reset --hard HEAD~1"
         exit 0
     fi
 
-    if git ls-remote --heads --exit-code "$PUSH_REMOTE" "$rc_branch" &>/dev/null; then
-        git push "$PUSH_REMOTE" --delete "$rc_branch"
+    if git ls-remote --heads --exit-code "$PUSH_REMOTE" "$staging_branch" &>/dev/null; then
+        git push "$PUSH_REMOTE" --delete "$staging_branch"
     else
-        echo "(note: ${rc_branch} already absent from ${PUSH_REMOTE})"
+        echo "(note: ${staging_branch} already absent from ${PUSH_REMOTE})"
     fi
     git reset --hard HEAD~1
     echo "Rolled back. Repo is at pre-release state."
@@ -199,10 +205,10 @@ fi
 # Start path: if HEAD is already a release commit, the user probably forgot a flag.
 HEAD_MSG=$(git log -1 --format=%s)
 if [[ "$HEAD_MSG" =~ ^release\ v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
-    echo "Error: HEAD is already 'release v${BASH_REMATCH[1]}' — a release candidate is pending."
+    echo "Error: HEAD is already 'release v${BASH_REMATCH[1]}' — a pending release exists."
     echo "Use:"
-    echo "  ./release.sh --finalize   # promote (requires the RC workflow to have succeeded)"
-    echo "  ./release.sh --rollback   # abandon (delete RC branch, reset local commit)"
+    echo "  ./release.sh --finalize   # promote (requires the staging workflow to have succeeded)"
+    echo "  ./release.sh --rollback   # abandon (delete staging branch, reset local commit)"
     exit 1
 fi
 
@@ -216,22 +222,28 @@ PATCH=$(echo "$CURRENT_VERSION" | cut -d. -f3)
 
 echo "Current version: ${CURRENT_VERSION}"
 
-# --- Prompt for bump type ---
+# --- Determine new version (prompt, or use --version=X.Y.Z override) ---
 
-echo ""
-echo "Release type:"
-echo "  1) patch  -> $((MAJOR)).$((MINOR)).$((PATCH + 1))"
-echo "  2) minor  -> $((MAJOR)).$((MINOR + 1)).0"
-echo "  3) major  -> $((MAJOR + 1)).0.0"
-echo ""
-read -rp "Select [1/2/3]: " bump_type
+if [[ -n "$NEW_VERSION_OVERRIDE" ]]; then
+    validate_version "$NEW_VERSION_OVERRIDE"
+    NEW_VERSION="$NEW_VERSION_OVERRIDE"
+    echo "Using version (from --version): ${NEW_VERSION}"
+else
+    echo ""
+    echo "Release type:"
+    echo "  1) patch  -> $((MAJOR)).$((MINOR)).$((PATCH + 1))"
+    echo "  2) minor  -> $((MAJOR)).$((MINOR + 1)).0"
+    echo "  3) major  -> $((MAJOR + 1)).0.0"
+    echo ""
+    read -rp "Select [1/2/3]: " bump_type
 
-case "$bump_type" in
-    1|patch) NEW_VERSION="$((MAJOR)).$((MINOR)).$((PATCH + 1))" ;;
-    2|minor) NEW_VERSION="$((MAJOR)).$((MINOR + 1)).0" ;;
-    3|major) NEW_VERSION="$((MAJOR + 1)).0.0" ;;
-    *) echo "Error: invalid selection '${bump_type}'"; exit 1 ;;
-esac
+    case "$bump_type" in
+        1|patch) NEW_VERSION="$((MAJOR)).$((MINOR)).$((PATCH + 1))" ;;
+        2|minor) NEW_VERSION="$((MAJOR)).$((MINOR + 1)).0" ;;
+        3|major) NEW_VERSION="$((MAJOR + 1)).0.0" ;;
+        *) echo "Error: invalid selection '${bump_type}'"; exit 1 ;;
+    esac
+fi
 
 # --- Check tag doesn't already exist ---
 
@@ -262,7 +274,7 @@ if [[ "$UNRELEASED_BULLETS" == "0" ]]; then
 fi
 
 TODAY=$(date +%Y.%m.%d)
-RC_BRANCH="release-candidate-v${NEW_VERSION}"
+STAGING_BRANCH="staging-v${NEW_VERSION}"
 echo ""
 if [[ "$DRY_RUN" == true ]]; then
     echo "DRY RUN: This script would:"
@@ -271,13 +283,13 @@ else
 fi
 echo "  1. Update version ${CURRENT_VERSION} -> ${NEW_VERSION} in _version.py and setup.py"
 echo "  2. Update CHANGELOG.md (${NEW_VERSION} - ${TODAY})"
-echo "  3. Commit locally, push commit to branch '${RC_BRANCH}' on ${PUSH_REMOTE}"
+echo "  3. Commit locally, push commit to branch '${STAGING_BRANCH}' on ${PUSH_REMOTE}"
 echo "     (master is NOT pushed; no tag is created yet)"
 echo "  4. Trigger the build wheels workflow on that branch (test-pypi)"
 echo ""
 echo "Once the workflow finishes, re-run this script:"
-echo "  - success -> tag v${NEW_VERSION}, push master, delete RC branch"
-echo "  - failure -> prompt to roll back (delete RC branch + reset local commit)"
+echo "  - success -> tag v${NEW_VERSION}, push master, delete staging branch"
+echo "  - failure -> prompt to roll back (delete staging branch + reset local commit)"
 echo ""
 if [[ "$DRY_RUN" == false ]]; then
     read -rp "Proceed? [Y/n] " confirm
@@ -347,27 +359,27 @@ if [[ "$DRY_RUN" == true ]]; then
     echo ""
     echo "DRY RUN: would have run:"
     echo "  git commit -m 'release v${NEW_VERSION}'"
-    echo "  git push ${PUSH_REMOTE} HEAD:refs/heads/${RC_BRANCH}"
-    echo "  gh workflow run build_wheels.yml --repo ${REPO} --ref ${RC_BRANCH} -f upload_to_pypi=true -f test_pypi=true"
+    echo "  git push ${PUSH_REMOTE} HEAD:refs/heads/${STAGING_BRANCH}"
+    echo "  gh workflow run build_wheels.yml --repo ${REPO} --ref ${STAGING_BRANCH} -f upload_to_pypi=true -f test_pypi=true"
     exit 0
 fi
 
-# --- Commit locally and push RC branch (no tag, no master push yet) ---
+# --- Commit locally and push staging branch (no tag, no master push yet) ---
 
 git add "$VERSION_FILE" "$SETUP_FILE" "$CHANGELOG"
 git commit -m "release v${NEW_VERSION}"
-git push "$PUSH_REMOTE" "HEAD:refs/heads/${RC_BRANCH}"
+git push "$PUSH_REMOTE" "HEAD:refs/heads/${STAGING_BRANCH}"
 
-# --- Trigger test-pypi build against the RC branch ---
+# --- Trigger test-pypi build against the staging branch ---
 
-gh workflow run build_wheels.yml --repo "$REPO" --ref "$RC_BRANCH" -f upload_to_pypi=true -f test_pypi=true
+gh workflow run build_wheels.yml --repo "$REPO" --ref "$STAGING_BRANCH" -f upload_to_pypi=true -f test_pypi=true
 
 echo ""
 echo "Release candidate v${NEW_VERSION} started (phase 1 of 2):"
 echo "  - Local:  release commit on ${CURRENT_BRANCH}, NOT pushed"
-echo "  - Remote: branch '${RC_BRANCH}' has the release commit"
-echo "  - Workflow: https://github.com/${REPO}/actions?query=branch%3A${RC_BRANCH}"
+echo "  - Remote: branch '${STAGING_BRANCH}' has the release commit"
+echo "  - Workflow: https://github.com/${REPO}/actions?query=branch%3A${STAGING_BRANCH}"
 echo ""
 echo "Re-run this script after the workflow finishes to finalize:"
-echo "  - success -> tag v${NEW_VERSION}, push ${CURRENT_BRANCH}, delete ${RC_BRANCH}"
+echo "  - success -> tag v${NEW_VERSION}, push ${CURRENT_BRANCH}, delete ${STAGING_BRANCH}"
 echo "  - failure -> prompt to roll back"