Merge pull request 'Add QC-SH-001 checklist for shell scripts (bash)' (#2 ) from add-qc-shell into main

Reviewed-on: #2
Add QC-SH-001 checklist for shell scripts (bash)
2026-10-02 08:14:57 +02:00 · 2026-10-02 14:12:59 +08:00
1 changed files with 59 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Quality Criteria: Shell Script (bash)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | QC-SH-001 |
+| CrossReference | [QC-DCD-001], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-02 | Accepted | Jens Tirsvad Nielsen | S07 | Initial version | — |
+
+---
+
+## Purpose
+
+Shell scripts automate steps that change files, repositories and remote systems, so a defect often does damage quietly. This checklist confirms that a bash script follows the shell conventions (strict mode, quoting, error handling, safe defaults), so that it is predictable, maintainable and safe to run.
+
+## Quality Criteria Checklist
+
+Level: **Mandatory** criteria are the baseline every instance must meet; **Optional** criteria are advanced and may be deferred.
+
+| # | Criterion | Level | ISO/IEC 25010 Characteristic(s) | Notes |
+| --- | --- | --- | --- | --- |
+| 1 | Starts with `#!/usr/bin/env bash` and `set -euo pipefail` (or a comment explains the exception) | Mandatory | Reliability | |
+| 2 | Every expansion is quoted; lists are arrays; tests use `[[ ]]` and `$(...)` | Mandatory | Reliability, Security | Unquoted expansions break on spaces and globs |
+| 3 | Names follow the conventions: `kebab-case.sh` files, `snake_case` functions and variables, `UPPER_SNAKE` constants and environment variables | Mandatory | Maintainability, Usability | |
+| 4 | Passes `shellcheck` and `bash -n` with no unexplained `disable` comments | Mandatory | Maintainability, Reliability | State the tool versions used |
+| 5 | Errors go to standard error with an `error:` message and a non-zero exit code; bad or missing arguments print a usage line | Mandatory | Reliability, Usability | |
+| 6 | Temporary files use `mktemp` with a `trap ... EXIT` cleanup; no fixed `/tmp` names | Mandatory | Security, Reliability | |
+| 7 | No secret is written in the script, echoed, or put on a command line; secrets come from the environment or a gitignored file | Mandatory | Security | |
+| 8 | A script that changes state outside its own directory defaults to a dry run or needs an explicit flag, and says so in its header | Mandatory | Reliability, Security | |
+| 9 | A header comment states purpose, usage, options, environment variables and exit codes | Mandatory | Usability, Maintainability | |
+| 10 | The script implements a task or design it cites; deviations are recorded | Mandatory | Functional Suitability, Maintainability | |
+| 11 | Behaviour is tested for success, failure and any disabled or bypass path | Mandatory | Reliability | Tests may be a recorded manual run |
+| 12 | Formatted with `shfmt` (or the project's formatter) | Optional | Maintainability | |
+| 13 | Safe to re-run: a second run does not duplicate or corrupt what the first did | Optional | Reliability | |
+| 14 | Bash version and external tools it needs are stated; GNU-only options are named | Optional | Portability | |
+
+## Common Defects
+
+- Unquoted `$var` that breaks on a space or an empty value
+- Missing `set -euo pipefail`, or `|| true` hiding a real failure
+- Parsing `ls` output instead of using globs or `find -print0`
+- A script that deletes or overwrites by default with no dry run
+- A token echoed to the terminal or kept in the script
+- No usage message, so a wrong call fails with a cryptic error
+- A script that implements nothing in any task or design
+
+## Traceability Rule
+
+- Backward: Design Class Diagram checklist ([QC-DCD-001]) where the script implements a design; Architecture Decision Record checklist ([QC-ADR-001]) for the decisions that constrain it
+- Forward: none, source code is the end of the QC checklist chain
+
+---
+
+[QC-DCD-001]: ./qc-dcd.md
+[QC-ADR-001]: ./qc-adr.md