proxmox/docs/10-best-practices/SCRIPT_HEADER_TEMPLATE.md

Script Header Template

Purpose: Standardize script metadata, usage, and error handling for all new and updated shell scripts.
Source: 00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md §4 (items 36–38); legacy: ALL_IMPROVEMENTS_AND_GAPS_INDEX.md.

---

Template

#!/usr/bin/env bash
# One-line description of what the script does.
# Usage: ./path/to/script.sh [OPTIONS] [ARGS]
#   --dry-run    Print what would be done; do not change state.
#   --help       Show this usage and exit.
# Exit codes: 0 = success, 1 = usage/validation error, 2 = runtime failure.
# Recommendation: docs/10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"   # adjust depth as needed

# Optional: logging helpers
log_info()  { echo "[INFO] $*" >&2; }
log_ok()    { echo "[OK] $*" >&2; }
log_warn()  { echo "[WARN] $*" >&2; }
log_err()   { echo "[ERROR] $*" >&2; }

# Optional: --dry-run and --help
DRY_RUN=false
for a in "$@"; do
  [[ "$a" == "--dry-run" ]] && DRY_RUN=true && break
  [[ "$a" == "--help" || "$a" == "-h" ]] && { sed -n '2,10p' "$0"; exit 0; }
done

# Your script logic below

---

Rules

Item	Rule
Shebang	Use #!/usr/bin/env bash (not #!/bin/bash).
Error handling	Use set -euo pipefail unless the script intentionally allows unset vars or ignores errors.
Usage	Document in a comment after the shebang: one-line description, Usage:, optional --dry-run / --help.
Exit codes	0 = success, 1 = usage/validation, 2 = runtime failure; document in comment.
Paths	Prefer SCRIPT_DIR and PROJECT_ROOT (or equivalent) so the script works from any CWD.

---

Optional: progress indicator

For long-running scripts, add a simple progress message:

log_info "Step 1/5: Validating config..."
# ... do work ...
log_info "Step 2/5: Deploying..."

---

Where to use

• New scripts under scripts/ (including scripts/verify/, scripts/maintenance/, etc.).
• When touching existing scripts for fixes or features, add the header if missing.

See also: IMPLEMENTATION_CHECKLIST.md, RECOMMENDATIONS_AND_SUGGESTIONS.md.