fix(release): Add more checks to release scripts

[NickLarsenNZ]

Tip

This PR is intended to be compared with #125 so we can take the best ideas of both.

Summary

Harden the release scripts with shared validation, state assertions, and consistency improvements. The goal is to catch errors early (before mutations), make handover between colleagues safer, and reduce silent misbehavior.

Also incorporates features from #125: reduced duplication via shared helpers, and centralised variable derivation.

What changed

• Created release/common.sh with shared functions sourced by all scripts
• Added BATS tests for all common functions (release/test_common.bats)
• All scripts now validate inputs before any mutations (validate_tag, validate_release_base_version, validate_what)
• All scripts now check common dependencies early (check_common_dependencies)
• Git state is asserted throughout: clean index, correct branch, correct repo, correct remote
• Branch existence checks use exact matching instead of loose grep
• Shallow clones removed (broke downstream tag/cherry-pick operations)
• git commit -sam replaced with explicit git add of known files
• pushd/popd with relative paths instead of cd with absolute paths
• Renamed REPOSITORY to REMOTE for consistency
• Fixed usage messages referencing wrong script names
• Centralised variable derivation (derive_tag_vars, derive_branch_vars)
• Centralised operator iteration (for_each_operator), cloning (ensure_clone), temp folder creation (ensure_temp_folder), and quote stripping (strip_double_quotes)
• Renamed RELEASE to RELEASE_BASE for clarity

Checklist

Phase 1: Shared infrastructure

• 1.1 - common.sh with validate_what, check_common_dependencies, assert_clean_index
• 1.2 - validate_tag (CalVer, --no-rc flag) and validate_release_base_version
• 1.3 - assert_cwd_is_repo
• 1.4 - assert_on_branch
• 1.5 - assert_remote_exists (checks github.com/stackabletech/$repo)

Phase 2: Apply shared functions to each script

• 2.1 - create-release-branch.sh
• 2.2 - create-release-candidate-branch.sh
• 2.3 - merge-release-candidate.sh
• 2.4 - tag-release-candidate.sh
• 2.5 - post-release.sh

Phase 2b: Consolidate push_branch

• 2.6 - Move push_branch to common.sh (deferred - current per-script implementations are short and clear)

Phase 3: Fix git state handling

• 3.1 - Remove --depth 1 from clones
• 3.2 - Replace git commit -sam with explicit git add + git commit -sm
• 3.3 - assert_clean_index after commits
• 3.4 - Subshells () for directory isolation (except release-branch-hygiene.sh which needs parent state)
• 3.5 - Exact branch-existence checks (assert_remote_branch_exists, assert_remote_branch_not_exists, assert_tag_not_exists)
• 3.6 - Commit divergence assertions (TODOs placed in scripts, deferred to future PR)

Phase 4: Improve dry-run and observability

• 4.1 - Verify PR exists in merge-release-candidate.sh push mode (fails if missing). Dry-run skips the check to allow testing before PRs exist.
• 4.2 - Summary output at end of each script (skipped - per-repo output already exists and set -e stops on first failure)
• 4.3 - Document RC rejection in post-release.sh
• 4.4 - Document demos branch-only workflow in README

Phase 5: Future-proofing (optional)

Not doing these now.

• 5.1 - --non-interactive flag for merge-release-candidate.sh (deferred to future PR)
• 5.2 - Progress/state file for handover resumability (deferred to future PR)
• 5.3 - Two-pass operator loop (deferred to future PR)

---

Tip

The phases below incorporate improvements from @adwk67 in #125

Phase A: Reduce duplication

• A.1 - derive_tag_vars (centralised variable derivation from tag)
• A.2 - derive_branch_vars (centralised variable derivation from branch version)
• A.3 - strip_double_quotes (replace inline quote stripping)
• A.4 - for_each_operator (centralised operator iteration)
• A.5 - ensure_clone (centralised clone-if-not-present)
• A.6 - ensure_temp_folder (centralised temp folder creation)

Phase B: Improve existing functions

• B.1 - Switch remote_branch_exists to git ls-remote (avoids modifying local refs)
• B.2 - Switch assert_tag_not_exists to git ls-remote (now takes remote name as argument)
• B.3 - Idempotent update_changelog (skip if tag already present, validate tag, use fixed-string matching)

Phase C: Add new safety checks

• C.1 - No-op commit guard (extracted into commit_and_push_rc function)
• C.2 - verify_release (post-mutation verification of Cargo, Helm, antora, changelog, etc.)
• C.3 - shellcheck source=common.sh directive

Phase D: Bug fixes

• D.1 - LIBGIT2_NO_PKG_CONFIG=1 workaround for non-NixOS users
• D.2 - Add extra/ to git add paths in operator loop

Phase E: Update release-branch-hygiene.sh

• E.1 - Apply all common.sh patterns to release-branch-hygiene.sh

Phase F: Future improvements

• F.1 - Use subshells () instead of pushd/popd where functions don't propagate parent state (all scripts except release-branch-hygiene.sh which needs CREATED_PRS)

[NickLarsenNZ]

Do we consider this a hack? It causes openssl.so.3 issues for some users.
I think the fix is to include pkg-config for the operators.

[NickLarsenNZ]

This prevents resumability. We could maybe follow the same pattern of:

Suggested change

	git switch -c "$PR_BRANCH" "$RELEASE_BRANCH"
	git switch "$PR_BRANCH" "$RELEASE_BRANCH" 2>/dev/null || git switch -c "$PR_BRANCH" "$RELEASE_BRANCH"

[NickLarsenNZ]

Same as other comment...

Suggested change

	git switch -c "$PR_BRANCH" "$RELEASE_BRANCH"
	git switch "$PR_BRANCH" "$RELEASE_BRANCH" 2>/dev/null || git switch -c "$PR_BRANCH" "$RELEASE_BRANCH"

[NickLarsenNZ]

This likely also fails on resume

[adwk67]

If this fails, also echo something to the user (e.g. "It was not possible to verify authentication: please login with e.g. gh auth login") so that it is clear what to do.