---
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.