migrate

2026-07-20 09:23:17 -04:00
parent c1315882da
commit 72272e4006
3179 changed files with 562960 additions and 14 deletions
@@ -0,0 +1,30 @@
+---
+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.