30 lines
2.2 KiB
Markdown
30 lines
2.2 KiB
Markdown
---
|
|
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. |