finaira-release 0.1.0__tar.gz

finaira_release-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: finaira-release
+Version: 0.1.0
+Summary: Release tooling for trunk-based repositories: RC and final tags, Azure DevOps deploys, release branches and hotfixes. The repositories come from a .env.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# finaira-release
+
+Release tooling for a trunk-based repository (GitHub as the source, Azure DevOps as the deploy target): RC and final tags, deploys to the Azure DevOps
+`dev` and `prod` branches, release branches, fixes, hotfixes and ports. It packages two bash scripts behind one
+command, `fin-release`. The package contains no URLs, hosts or credentials: the repositories come from your `.env`, so it works for any repo set up this way.
+
+## Install
+
+```bash
+pip install finaira-release
+```
+
+Needs WSL (or Linux), `bash`, `git`, `curl` and GNU `sort -V`, plus the VPN if your Azure DevOps needs one.
+Windows PowerShell is not supported.
+
+## Settings
+
+Create a `.env` (never commit it, `chmod 600 .env`) in your repository clone or in any parent folder of where you run
+the command. `fin-release` uses the nearest `.env` going up from the current folder. Variables already set in the shell win.
+
+```
+GITHUB_REPO=git@github.com:<org>/<repo>.git
+AZDO_HOST_PATH=dev.azure.com/<org>/<project>/_git/<repo>
+AZDO_USERNAME=your-azdo-username-or-email
+AZDO_PASSWORD=your-personal-access-token
+AZDO_DEV_BRANCH=dev
+AZDO_PROD_BRANCH=prod
+```
+
+`GITHUB_REPO` can be an SSH or an HTTPS URL, whichever your machine can reach without a prompt. `AZDO_PASSWORD` is your own PAT
+with push permission on `dev` and `prod`. A missing variable stops the command and names it. `AZDO_DEV_BRANCH` and `AZDO_PROD_BRANCH` are optional: they name the Azure branches that deploy to Dev and Prod (defaults `dev` and `prod`). Put values on their own line, without trailing comments. The two branches must differ; `deploy-dev` and `deploy-prod` write only to them, and `mirror` refuses to write to them.
+
+## Use
+
+```bash
+fin-release check                         # settings, PAT, VPN, tools, signing
+fin-release status
+fin-release deploy-dev --new-rc           # cut the next RC and deploy it to Dev
+fin-release deploy-prod --promote         # final tag on the latest RC, deploy to Prod
+fin-release branch 1.5.0                  # release branches and fixes
+fin-release fix PROJ-123 handle-null --release 1.4.0
+fin-release --dry-run deploy-prod --promote
+fin-release sync --help                   # full usage of deploys and tags
+fin-release release --help                # full usage of branches and fixes
+```
+
+The arguments are exactly those of `sync-branch.sh` and `release.sh` in your release runbook.
+Everything runs on remote refs in a temporary repository, so your clone and uncommitted work are never touched.

finaira_release-0.1.0/README.md

@@ -0,0 +1,48 @@
+# finaira-release
+
+Release tooling for a trunk-based repository (GitHub as the source, Azure DevOps as the deploy target): RC and final tags, deploys to the Azure DevOps
+`dev` and `prod` branches, release branches, fixes, hotfixes and ports. It packages two bash scripts behind one
+command, `fin-release`. The package contains no URLs, hosts or credentials: the repositories come from your `.env`, so it works for any repo set up this way.
+
+## Install
+
+```bash
+pip install finaira-release
+```
+
+Needs WSL (or Linux), `bash`, `git`, `curl` and GNU `sort -V`, plus the VPN if your Azure DevOps needs one.
+Windows PowerShell is not supported.
+
+## Settings
+
+Create a `.env` (never commit it, `chmod 600 .env`) in your repository clone or in any parent folder of where you run
+the command. `fin-release` uses the nearest `.env` going up from the current folder. Variables already set in the shell win.
+
+```
+GITHUB_REPO=git@github.com:<org>/<repo>.git
+AZDO_HOST_PATH=dev.azure.com/<org>/<project>/_git/<repo>
+AZDO_USERNAME=your-azdo-username-or-email
+AZDO_PASSWORD=your-personal-access-token
+AZDO_DEV_BRANCH=dev
+AZDO_PROD_BRANCH=prod
+```
+
+`GITHUB_REPO` can be an SSH or an HTTPS URL, whichever your machine can reach without a prompt. `AZDO_PASSWORD` is your own PAT
+with push permission on `dev` and `prod`. A missing variable stops the command and names it. `AZDO_DEV_BRANCH` and `AZDO_PROD_BRANCH` are optional: they name the Azure branches that deploy to Dev and Prod (defaults `dev` and `prod`). Put values on their own line, without trailing comments. The two branches must differ; `deploy-dev` and `deploy-prod` write only to them, and `mirror` refuses to write to them.
+
+## Use
+
+```bash
+fin-release check                         # settings, PAT, VPN, tools, signing
+fin-release status
+fin-release deploy-dev --new-rc           # cut the next RC and deploy it to Dev
+fin-release deploy-prod --promote         # final tag on the latest RC, deploy to Prod
+fin-release branch 1.5.0                  # release branches and fixes
+fin-release fix PROJ-123 handle-null --release 1.4.0
+fin-release --dry-run deploy-prod --promote
+fin-release sync --help                   # full usage of deploys and tags
+fin-release release --help                # full usage of branches and fixes
+```
+
+The arguments are exactly those of `sync-branch.sh` and `release.sh` in your release runbook.
+Everything runs on remote refs in a temporary repository, so your clone and uncommitted work are never touched.

finaira_release-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "finaira-release"
+version = "0.1.0"
+description = "Release tooling for trunk-based repositories: RC and final tags, Azure DevOps deploys, release branches and hotfixes. The repositories come from a .env."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = []
+
+[project.scripts]
+fin-release = "fin_release.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fin_release = ["scripts/*.sh"]

finaira_release-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

finaira_release-0.1.0/src/fin_release/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

finaira_release-0.1.0/src/fin_release/cli.py

@@ -0,0 +1,74 @@
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from fin_release import __version__
+
+SCRIPTS = Path(__file__).resolve().parent / "scripts"
+SYNC_COMMANDS = {"deploy-dev", "deploy-prod", "status", "verify", "mirror", "check"}
+RELEASE_COMMANDS = {"branch", "fix", "hotfix", "port"}
+
+HELP = f"""fin-release {__version__}
+
+Usage: fin-release [--dry-run] [--yes] <command> ...
+
+Deploys and tags (sync-branch.sh):
+  deploy-dev, deploy-prod, status, verify, mirror, check
+Branches and fixes (release.sh):
+  branch, fix, hotfix, port
+
+'fin-release sync <command> --help' and 'fin-release release <command> --help'
+show the full usage of each group.
+
+Settings are read from the nearest .env in the current folder or any parent:
+  GITHUB_REPO, AZDO_HOST_PATH, AZDO_USERNAME, AZDO_PASSWORD
+"""
+
+
+def find_env(start):
+    for folder in [start, *start.parents]:
+        candidate = folder / ".env"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def pick_script(args):
+    if args and args[0] in ("sync", "release"):
+        name = "sync-branch.sh" if args[0] == "sync" else "release.sh"
+        return name, args[1:]
+    for arg in args:
+        if arg in SYNC_COMMANDS:
+            return "sync-branch.sh", args
+        if arg in RELEASE_COMMANDS:
+            return "release.sh", args
+    return None, args
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args == ["-h"] or args == ["--help"]:
+        print(HELP)
+        return 0
+    if args == ["--version"]:
+        print(__version__)
+        return 0
+    script, args = pick_script(args)
+    if script is None:
+        print(f"Unknown command: {' '.join(args)}\n\n{HELP}", file=sys.stderr)
+        return 1
+    bash = shutil.which("bash")
+    if bash is None:
+        print("bash is required. Run fin-release from WSL or Linux.", file=sys.stderr)
+        return 1
+    env = dict(os.environ)
+    env_file = find_env(Path.cwd())
+    if env_file is not None:
+        env.setdefault("FIN_RELEASE_ENV", str(env_file))
+    return subprocess.run([bash, str(SCRIPTS / script), *args], env=env).returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())

finaira_release-0.1.0/src/fin_release/scripts/release.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# GitHub helper for trunk-based development: release branches, fixes, hotfixes and ports.
+# Run it with --help for usage.
+#
+# It only touches GitHub. Release tags and deployments to Azure DevOps are done by
+# scripts/sync-branch.sh (deploy-dev --new-rc and deploy-prod --promote).
+#
+# Everything works on GitHub's remote refs through a temporary repository, so your local
+# branches, working directory and uncommitted work are never touched. Tags are never moved,
+# deleted or reused. Signing is left to your git config (tag.gpgsign and the org rules).
+
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/release_common.sh"
+
+RELEASE=""
+FROM=""
+TO=""
+
+trap cleanup_scratch EXIT
+
+usage() {
+  cat << 'EOF'
+Usage: release.sh [--dry-run] [--yes] <command>
+
+  branch X.Y.Z                        create release/X.Y.Z from main
+  fix TICKET slug --release X.Y.Z     fix/TICKET/slug branch from release/X.Y.Z
+  hotfix --from vX.Y.Z TICKET slug    release/X.Y.(Z+1) from the production tag, plus hotfix/TICKET/slug
+  port <sha> TICKET --to main|X.Y.Z   cherry-pick -x a commit into bug/main|release/TICKET
+
+Every write asks y/N first; --yes answers yes. --dry-run explains each command and what it would do,
+and changes nothing. Release tags and deployments: sync-branch.sh deploy-dev / deploy-prod.
+EOF
+}
+
+create_branch() {
+  step "Create GitHub branch $2" git push "$GITHUB_REPO" "$1:refs/heads/$2"
+}
+
+cmd_branch() {
+  local tip
+  require_version "${1:-}"
+  require_branch_name "release/$1"
+  [[ -z "$(github_branch_sha "release/$1")" ]] || die "release/$1 already exists."
+  fetch_ref refs/heads/main
+  tip=$(git rev-parse refs/heads/main)
+  confirm "Create release/$1 from main @ ${tip:0:7}?"
+  create_branch "$tip" "release/$1"
+}
+
+cmd_fix() {
+  local ticket="${1:-}" slug="${2:-}" name
+  require_ticket "$ticket"
+  require_slug "$slug"
+  require_version "$RELEASE"
+  name="fix/$ticket/$slug"
+  require_branch_name "$name"
+  [[ -n "$(github_branch_sha "release/$RELEASE")" ]] || die "release/$RELEASE does not exist."
+  [[ -z "$(github_branch_sha "$name")" ]] || die "$name already exists."
+  fetch_ref "refs/heads/release/$RELEASE"
+  confirm "Create $name from release/$RELEASE?"
+  create_branch "refs/heads/release/$RELEASE" "$name"
+  echo "Open the PR with: gh pr create --base release/$RELEASE --head $name"
+}
+
+cmd_hotfix() {
+  local ticket="${1:-}" slug="${2:-}" version next base name
+  require_ticket "$ticket"
+  require_slug "$slug"
+  version="${FROM#v}"
+  require_version "$version"
+  github_tags | grep -qx -- "$FROM" || die "Production tag $FROM does not exist on GitHub."
+  next="${version%.*}.$((${version##*.} + 1))"
+  name="hotfix/$ticket/$slug"
+  require_branch_name "release/$next"
+  require_branch_name "$name"
+  [[ -z "$(github_branch_sha "$name")" ]] || die "$name already exists."
+  if [[ -z "$(github_branch_sha "release/$next")" ]]; then
+    base=$(tag_commit "$FROM")
+    confirm "Create release/$next from $FROM and $name from it?"
+    create_branch "$base" "release/$next"
+  else
+    fetch_ref "refs/heads/release/$next"
+    base=$(git rev-parse "refs/heads/release/$next")
+    confirm "Create $name from the existing release/$next?"
+  fi
+  create_branch "$base" "$name"
+  echo "Open the PR with: gh pr create --base release/$next --head $name"
+}
+
+cmd_port() {
+  local sha="${1:-}" ticket="${2:-}" target name worktree
+  [[ "$sha" =~ ^[0-9a-f]{7,40}$ ]] || die "'$sha' is not a commit sha."
+  require_ticket "$ticket"
+  if [[ "$TO" == "main" ]]; then
+    target="main"
+    name="bug/main/$ticket"
+  else
+    require_version "$TO"
+    target="release/$TO"
+    name="bug/release/$ticket"
+  fi
+  require_branch_name "$name"
+  [[ -n "$(github_branch_sha "$target")" ]] || die "$target does not exist."
+  [[ -z "$(github_branch_sha "$name")" ]] || die "$name already exists."
+  git fetch -q --no-tags "$GITHUB_REPO" '+refs/heads/*:refs/remotes/github/*'
+  git cat-file -e "$sha^{commit}" 2> /dev/null || die "Commit $sha is not on any GitHub branch."
+  confirm "Cherry-pick $sha onto $target as $name?"
+  worktree="$SCRATCH/worktree"
+  git worktree add -q -b "$name" "$worktree" "refs/remotes/github/$target"
+  if ! env -u GIT_DIR git -C "$worktree" cherry-pick -x "$sha" > /dev/null; then
+    env -u GIT_DIR git -C "$worktree" cherry-pick --abort || true
+    echo "Cherry-pick conflict: nothing was pushed. Resolve it by hand:" >&2
+    echo "  git switch -c $name origin/$target && git cherry-pick -x $sha" >&2
+    exit 1
+  fi
+  create_branch "refs/heads/$name" "$name"
+  echo "Open the PR with: gh pr create --base $target --head $name"
+}
+
+dispatch() {
+  local command="${1:-}"
+  shift
+  load_github_settings
+  init_scratch
+  case "$command" in
+    branch) cmd_branch "$@" ;;
+    fix) cmd_fix "$@" ;;
+    hotfix) cmd_hotfix "$@" ;;
+    port) cmd_port "$@" ;;
+    *)
+      echo "Unknown command: $command" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+}
+
+ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --yes | -y) ASSUME_YES=1; shift ;;
+    --release | --from | --to)
+      [[ -n "${2:-}" ]] || die "$1 requires a value."
+      case "$1" in
+        --release) RELEASE="$2" ;;
+        --from) FROM="$2" ;;
+        --to) TO="$2" ;;
+      esac
+      shift 2
+      ;;
+    -h | --help) usage; exit 0 ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+
+if [[ ${#ARGS[@]} -eq 0 ]]; then
+  usage >&2
+  exit 1
+fi
+dispatch "${ARGS[@]}"

finaira_release-0.1.0/src/fin_release/scripts/release_common.sh

@@ -0,0 +1,306 @@
+#!/bin/bash
+# Shared helpers for scripts/sync-branch.sh and scripts/release.sh. Source this file, do not run it.
+
+# Settings come from the environment or from a .env file (fin-release finds it and sets FIN_RELEASE_ENV).
+GITHUB_REPO=""
+AZDO_HOST_PATH=""
+AZDO_DEV_BRANCH=""
+AZDO_PROD_BRANCH=""
+ENV_FILE="${FIN_RELEASE_ENV:-$PWD/.env}"
+
+NUMBER='(0|[1-9][0-9]*)'
+VERSION_RE="^${NUMBER}[.]${NUMBER}[.]${NUMBER}$"
+RC_TAG_RE="^v${NUMBER}[.]${NUMBER}[.]${NUMBER}-rc[.][1-9][0-9]*$"
+FINAL_TAG_RE="^v${NUMBER}[.]${NUMBER}[.]${NUMBER}$"
+TICKET_RE='^[A-Z]+-[0-9]+$'
+SLUG_RE='^[a-z0-9-]+$'
+BRANCH_RE='^(main|(feat|fix|hotfix|integration|docs|ci|refactor|chore)/[A-Z]+-[0-9]+/[a-z0-9-]+|dependabot/[a-z0-9_-]+/[A-Za-z0-9._@/-]+|release/[0-9]+[.][0-9]+[.][0-9]+|bug/(main|release)/[A-Za-z]+-[0-9]+)$'
+
+DRY_RUN=0
+ASSUME_YES=0
+SCRATCH=""
+
+# Set by plan_rc_tag / plan_final_tag, read by apply_new_tag and the deploy flow.
+TAG=""
+TAG_COMMIT=""
+TAG_MESSAGE=""
+TAG_PENDING=0
+BRANCH_MISSING=0
+
+log() { echo "==> $*"; }
+die() { echo "$*" >&2; exit 1; }
+
+# ---- Running writes and asking for confirmation ----
+
+mask() {
+  local text="$*"
+  text="${text//${AZDO_REPO:-@@none@@}/azure-devops}"
+  echo "${text//$GITHUB_REPO/github}"
+}
+
+# Runs a write command. With --dry-run it only says what the command would do.
+step() {
+  local what="$1"
+  shift
+  if [[ $DRY_RUN -eq 1 ]]; then
+    echo "[dry-run] $what"
+    echo "          \$ $(mask "$*")"
+  else
+    log "$what"
+    "$@"
+  fi
+}
+
+# Development actions: y/N prompt, answered by --yes, only described by --dry-run.
+confirm() {
+  if [[ $DRY_RUN -eq 1 ]]; then
+    echo "[dry-run] would ask: $1 [y/N]"
+    return 0
+  fi
+  [[ $ASSUME_YES -eq 1 ]] && return 0
+  [[ -t 0 ]] || die "Not an interactive terminal. Re-run with --yes to confirm: $1"
+  read -r -p "$1 [y/N] " answer
+  [[ "$answer" =~ ^[Yy]$ ]] || die "Cancelled."
+}
+
+# Production actions: the tag must be typed. --yes is never accepted.
+confirm_typed() {
+  local expected="$1" message="$2"
+  [[ $ASSUME_YES -eq 0 ]] || die "--yes is not accepted for production actions."
+  if [[ $DRY_RUN -eq 1 ]]; then
+    echo "[dry-run] would ask you to type '$expected': $message"
+    return 0
+  fi
+  [[ -t 0 ]] || die "Production actions need an interactive terminal."
+  echo "$message"
+  read -r -p "Type '$expected' to confirm: " answer
+  [[ "$answer" == "$expected" ]] || die "Cancelled."
+}
+
+# ---- Input checks ----
+
+require_version() { [[ "${1:-}" =~ $VERSION_RE ]] || die "'${1:-}' is not a version like 1.4.0 (no leading zeros)."; }
+require_ticket() { [[ "${1:-}" =~ $TICKET_RE ]] || die "'${1:-}' is not a ticket like CM-123."; }
+require_slug() { [[ "${1:-}" =~ $SLUG_RE ]] || die "'${1:-}' is not a slug (lowercase letters, digits, dashes)."; }
+require_branch_name() { [[ "$1" =~ $BRANCH_RE ]] || die "Branch name '$1' does not match the repository naming rule."; }
+
+# ---- Tag names. Only vX.Y.Z and vX.Y.Z-rc.N are release tags; anything else is ignored. ----
+
+# Reads ls-remote output on stdin, prints canonical release tag names.
+canonical_tags() {
+  awk -v pattern="^refs/tags/v${NUMBER}[.]${NUMBER}[.]${NUMBER}(-rc[.]${NUMBER})?\$" \
+    '$2 ~ pattern {sub("^refs/tags/", "", $2); print $2}'
+}
+
+# Tag filters read tag names on stdin; highest prints the greatest by version.
+highest() { LC_ALL=C sort -V | tail -n1; }
+rc_tags() { grep -E -- '-rc[.]' || true; }
+final_tags() { grep -vE -- '-rc[.]' || true; }
+rc_tags_of() { grep -E -- "^v${1//./[.]}-rc[.][0-9]+\$" || true; }
+
+# The release version a tag belongs to: v1.4.0-rc.2 and v1.4.0 are both 1.4.0.
+tag_version() {
+  local version="${1#v}"
+  echo "${version%-rc.*}"
+}
+
+# ---- Azure DevOps access ----
+
+env_value() {
+  local value="${!1:-}"
+  if [[ -z "$value" && -f "$ENV_FILE" ]]; then
+    value=$(grep -E "^$1=" "$ENV_FILE" | tail -n1 | cut -d '=' -f2- || true)
+    value="${value%\"}"; value="${value#\"}"
+    value="${value%\'}"; value="${value#\'}"
+  fi
+  echo "$value"
+}
+
+require_setting() {
+  local value
+  value=$(env_value "$1")
+  [[ -n "$value" ]] || die "$1 is missing. Add $1=... to $ENV_FILE (see the fin-release README)."
+  printf -v "$1" '%s' "$value"
+}
+
+load_github_settings() {
+  require_setting GITHUB_REPO
+}
+
+load_azdo_credentials() {
+  load_github_settings
+  require_setting AZDO_HOST_PATH
+  require_setting AZDO_USERNAME
+  require_setting AZDO_PASSWORD
+  AZDO_DEV_BRANCH=$(env_value AZDO_DEV_BRANCH); AZDO_DEV_BRANCH="${AZDO_DEV_BRANCH:-dev}"
+  AZDO_PROD_BRANCH=$(env_value AZDO_PROD_BRANCH); AZDO_PROD_BRANCH="${AZDO_PROD_BRANCH:-prod}"
+  git check-ref-format "refs/heads/$AZDO_DEV_BRANCH" || die "AZDO_DEV_BRANCH '$AZDO_DEV_BRANCH' is not a valid branch name."
+  git check-ref-format "refs/heads/$AZDO_PROD_BRANCH" || die "AZDO_PROD_BRANCH '$AZDO_PROD_BRANCH' is not a valid branch name."
+  [[ "$AZDO_DEV_BRANCH" != "$AZDO_PROD_BRANCH" ]] || die "AZDO_DEV_BRANCH and AZDO_PROD_BRANCH must be different branches."
+  AZDO_REPO="https://${AZDO_USERNAME}:${AZDO_PASSWORD}@${AZDO_HOST_PATH}"
+}
+
+check_vpn() {
+  log "Checking Azure DevOps reachability (VPN check)..."
+  local host="${AZDO_HOST_PATH%%/*}"
+  if ! curl -s --max-time 5 -o /dev/null -w "%{http_code}" "https://$host" | grep -qE "^(200|203|30[0-9])$"; then
+    die "Cannot reach $host. Are you connected to the VPN?"
+  fi
+  echo "Azure DevOps is reachable."
+}
+
+# ---- Remote reads. Everything works on a temporary bare repository, never on your clone. ----
+
+init_scratch() {
+  SCRATCH=$(mktemp -d)
+  git init -q --bare "$SCRATCH/repo.git"
+  export GIT_DIR="$SCRATCH/repo.git"
+}
+
+cleanup_scratch() {
+  [[ -z "$SCRATCH" ]] && return 0
+  git -C "$SCRATCH/repo.git" worktree prune 2> /dev/null || true
+  rm -rf "$SCRATCH"
+}
+
+# Prints the sha of a ref on a remote, empty when the ref does not exist.
+remote_sha() {
+  local refs
+  refs=$(git ls-remote --refs "$1" "$2") || die "Could not read '$2' from the remote. Check your credentials and the VPN."
+  awk -v ref="$2" '$2 == ref {print $1}' <<< "$refs"
+}
+
+github_tags() { git ls-remote --tags --refs "$GITHUB_REPO" | canonical_tags; }
+azure_tags() { git ls-remote --tags --refs "$AZDO_REPO" | canonical_tags; }
+github_branch_sha() { remote_sha "$GITHUB_REPO" "refs/heads/$1"; }
+azure_branch() {
+  case "$1" in
+    dev) echo "$AZDO_DEV_BRANCH" ;;
+    prod) echo "$AZDO_PROD_BRANCH" ;;
+    *) echo "$1" ;;
+  esac
+}
+azure_branch_sha() { remote_sha "$AZDO_REPO" "refs/heads/$(azure_branch "$1")"; }
+
+# Tags known anywhere, so a number is never reused. Azure is included once its credentials are loaded.
+known_tags() {
+  { github_tags; [[ -z "${AZDO_REPO:-}" ]] || azure_tags; } | LC_ALL=C sort -u
+}
+
+fetch_ref() { git fetch -q --no-tags "$GITHUB_REPO" "+$1:$1"; }
+fetch_azure_branch() { git fetch -q "$AZDO_REPO" "+refs/heads/$(azure_branch "$1"):refs/heads/azdo-$1"; }
+
+# Fetches a GitHub tag and prints the commit it points at.
+tag_commit() {
+  fetch_ref "refs/tags/$1" || die "Tag $1 does not exist on GitHub."
+  git rev-parse "refs/tags/$1^{commit}"
+}
+
+# Prints the tag named in the Deploy-Tag trailer of a commit, empty when there is none.
+deployed_tag_of() {
+  git log -1 --format=%B "$1" | sed -n 's/^Deploy-Tag: *//p' | head -n1
+}
+
+# ---- Release branch and tag planning. Planning only reads; apply_new_tag writes. ----
+
+# The highest RC tag known on GitHub or Azure; empty when there is none.
+latest_rc() { known_tags | rc_tags | highest; }
+
+# The highest release version known on GitHub or Azure (RC or final); empty when there is none.
+latest_version() { known_tags | sed -E 's/^v//; s/-rc[.][0-9]+$//' | highest; }
+
+# Says how a tag relates to its release/X.Y.Z branch.
+describe_release_branch() {
+  local tag="$1" branch commit tip ahead
+  branch="release/$(tag_version "$tag")"
+  tip=$(github_branch_sha "$branch")
+  if [[ -z "$tip" ]]; then
+    echo "    Branch:  $branch does not exist on GitHub"
+    return
+  fi
+  fetch_ref "refs/heads/$branch"
+  commit=$(tag_commit "$tag")
+  if [[ "$commit" == "$tip" ]]; then
+    echo "    Branch:  $branch @ ${tip:0:7} is exactly this tag"
+  elif git merge-base --is-ancestor "$commit" "refs/heads/$branch"; then
+    ahead=$(git rev-list --count "$commit..refs/heads/$branch")
+    echo "    Branch:  $branch has $ahead commit(s) after this tag"
+  else
+    echo "    Branch:  WARNING this tag's commit is not on $branch"
+  fi
+}
+
+# Plans the next vX.Y.Z-rc.N on release/X.Y.Z, asking first when the branch has to be created from main.
+# An optional second argument is the tag the user asked for; it must be exactly the next RC.
+plan_rc_tag() {
+  local version="$1" wanted="${2:-}" known last last_commit
+  require_version "$version"
+  require_branch_name "release/$version"
+  known=$(known_tags)
+  if printf '%s\n' "$known" | grep -qx -- "v$version"; then
+    die "v$version is already released; start a new version."
+  fi
+  last=$(printf '%s\n' "$known" | rc_tags_of "$version" | highest)
+  TAG="v$version-rc.1"
+  [[ -z "$last" ]] || TAG="v$version-rc.$((${last##*.} + 1))"
+  if [[ -n "$wanted" && "$wanted" != "$TAG" ]]; then
+    die "$wanted is not the next RC of $version. The latest is ${last:-none}, so the next one is $TAG."
+  fi
+  BRANCH_MISSING=0
+  if [[ -n "$(github_branch_sha "release/$version")" ]]; then
+    fetch_ref "refs/heads/release/$version"
+    TAG_COMMIT=$(git rev-parse "refs/heads/release/$version")
+  else
+    fetch_ref refs/heads/main
+    TAG_COMMIT=$(git rev-parse refs/heads/main)
+  fi
+  if [[ -n "$last" ]]; then
+    last_commit=$(tag_commit "$last")
+    if [[ "$last_commit" == "$TAG_COMMIT" ]]; then
+      die "release/$version @ ${TAG_COMMIT:0:7} is already tagged $last. Merge a fix before cutting a new RC."
+    fi
+  fi
+  if [[ -z "$(github_branch_sha "release/$version")" ]]; then
+    confirm "release/$version does not exist. Create it from main @ ${TAG_COMMIT:0:7}?"
+    BRANCH_MISSING=1
+  fi
+  TAG_MESSAGE="Release candidate $TAG"
+  TAG_PENDING=1
+}
+
+# Plans the final vX.Y.Z on the exact commit of the latest RC. The branch must exist and be at that RC.
+plan_final_tag() {
+  local version="$1" known rc rc_commit
+  require_version "$version"
+  known=$(known_tags)
+  if printf '%s\n' "$known" | grep -qx -- "v$version"; then
+    die "v$version already exists."
+  fi
+  rc=$(printf '%s\n' "$known" | rc_tags_of "$version" | highest)
+  [[ -n "$rc" ]] || die "No RC exists for $version. Create one first: sync-branch.sh deploy-dev --new-rc $version"
+  [[ -n "$(github_branch_sha "release/$version")" ]] || die "release/$version does not exist."
+  fetch_ref "refs/heads/release/$version"
+  TAG_COMMIT=$(git rev-parse "refs/heads/release/$version")
+  rc_commit=$(tag_commit "$rc")
+  if [[ "$rc_commit" != "$TAG_COMMIT" ]]; then
+    die "release/$version has commits after $rc. Cut a new RC and test it first."
+  fi
+  [[ -z "${AZDO_REPO:-}" ]] || azure_tags | grep -qx -- "$rc" ||
+    echo "Note: $rc was never deployed to Azure (its tag is not there), so it may not have been tested on Dev."
+  BRANCH_MISSING=0
+  TAG="v$version"
+  TAG_MESSAGE="Release $TAG"
+  TAG_PENDING=1
+}
+
+# Creates the missing release branch and the planned tag on GitHub. Call it after confirming.
+apply_new_tag() {
+  local gpg=()
+  if [[ $BRANCH_MISSING -eq 1 ]]; then
+    step "Create GitHub branch release/$(tag_version "$TAG") from main" \
+      git push "$GITHUB_REPO" "$TAG_COMMIT:refs/heads/release/$(tag_version "$TAG")"
+  fi
+  [[ $DRY_RUN -eq 0 ]] || gpg=(-c tag.gpgsign=false)
+  git ${gpg[@]+"${gpg[@]}"} tag -a "$TAG" "$TAG_COMMIT" -m "$TAG_MESSAGE"
+  step "Push tag $TAG to GitHub" git push "$GITHUB_REPO" "refs/tags/$TAG"
+}