Compose-Files/Backups/Miker/Scripts/SCRIPTING_BEST_PRACTICES_INDEX.md

tags

tags
Scirpts Desktop

📚 Scripts Directory Best Practices Index

Purpose: This document serves as the mandatory quality gate index for all shell scripts, configuration guides, and setup manuals (*.md/*.sh) residing in this directory. Every script must adhere to these updated standards.

Mandates of Modern Scripting (Version v2.0)

All standalone scripts should follow a template emphasizing security, idempotency, and clear execution logic.

1. Structure and Readability

• Headers: Must start with a # title and include an executive summary stating WHO, WHAT the script does, and WHY it is necessary (the problem it solves).
• Dependencies: The first section must clearly list all required external tools (# Requires: sudo, curl, docker-compose).

2. Execution Practices

• Idempotency Check: Scripts should aim for idempotent operations. If step N fails, running the exact same script on a machine that subsequently fixed step N should not fail again due to intermediate artifacts.
• Error Handling: Use set -euo pipefail at the top of every shell script. This ensures that:
  • -e: The script will exit immediately if any command fails.
  • -u: Unset variables are treated as an error.
  • -o pipefail: Pipelines fail if any command in the pipeline fails, not just the last one.

3. Deployment & Automation Best Practices (The 'Modern' Way)

For production environments or CI/CD:

1. DO NOT rely solely on simple shell scripts. For complex workflows involving multi-step deployments, utilize Ansible Playbooks or Docker Compose. These tools manage state and dependencies far more reliably than manual scripting.
2. If a script must be used (e.g., for one-off cleanup), it should minimally rely on sudo and include instructions to run the subsequent necessary user permission changes (sudo usermod...).

[!NOTE] Modernized Workflow Moving forward, any new scripting requirement that involves setup or deployment logic must first be modeled as a declarative configuration (Ansible Playbook) before being written as an imperative script. Shell scripts should be relegated to simple file execution wrappers only.