b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 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](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) §4 (items 36–38); legacy: [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md).
|
||
|
||
---
|
||
|
||
## Template
|
||
|
||
```bash
|
||
#!/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:
|
||
|
||
```bash
|
||
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](IMPLEMENTATION_CHECKLIST.md), [RECOMMENDATIONS_AND_SUGGESTIONS.md](RECOMMENDATIONS_AND_SUGGESTIONS.md).
|