From 1484f77e236427d92eae975467ec97dfe0ec918a Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Fri, 2 Oct 2026 14:12:59 +0800 Subject: [PATCH] Add QC-SH-001 checklist for shell scripts (bash) Fourteen criteria (eleven mandatory), each tagged with an ISO/IEC 25010 characteristic: strict mode, quoting, naming, shellcheck, error handling, temporary files, secrets, safe defaults, header, traceability and tests. Co-Authored-By: Claude Sonnet 5.5 --- qc-programming-shell.md | 59 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 qc-programming-shell.md diff --git a/qc-programming-shell.md b/qc-programming-shell.md new file mode 100644 index 0000000..4184717 --- /dev/null +++ b/qc-programming-shell.md @@ -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 -- 2.54.0