diff --git a/CHANGELOG.md b/CHANGELOG.md index aced4b7..c22773c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,29 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [2026.6.9] - 2026-06-09 + ### Changed -- **Guidelines**: Improve grammar, wording, and clarity in the error handling - guidance without changing the underlying recommendations. - - `Proper Error Handling` -- **Guidelines**: Improve grammar, wording, and consistency in the quoting and - variable declaration guidance. - - `Style` -- **TODO**: Mark the error handling guideline review as complete and remove an - outdated wording-review example. -- **Guidelines**: Improve grammar, wording, heading consistency, and internal - references in the aesthetics guidance. +- **Guidelines**: Rename `Bashisms` to `Bash Idioms` and reframe the section + around Bash-specific patterns, built-ins, keywords, and expansions. + - `Bash Idioms` +- **Guidelines**: Expand the Bash idioms rationale around safety, clarity, + performance, consistency, and POSIX portability tradeoffs. + - `Bash Idioms` +- **Guidelines**: Improve grammar, wording, and consistency across reviewed + guideline pages without changing the underlying recommendations. - `Aesthetics` -- **Guidelines**: Rename the Bash-specific patterns section to `Bash Idioms`, update - related wording to describe those patterns as idiomatic Bash practices, and expand - the section rationale around safety, clarity, performance, consistency, and POSIX - portability tradeoffs. Also improve wording across the conditional test, sequence - iteration, command substitution, arithmetic, parameter expansion, file handling, - collection, input parsing, and array population guidance. - `Bash Idioms` -- **Guidelines**: Improve wording and terminology in the draft common mistakes - guidance for choosing between `for` and `while` loops. + - `Proper Error Handling` + - `Style` +- **Guidelines**: Improve wording and terminology in the draft guidance for + choosing between `for` and `while` loops. - `Common Mistakes` +- **TODO**: Update guideline review tracking for `Aesthetics`, `Bash Idioms`, + `Error Handling`, and `Style`, and remove an outdated wording-review example. +- **CI**: Update pinned GitHub Actions references for `actions/checkout` and + `astral-sh/setup-uv` in the PR build and Zensical deploy workflows. ## [2026.5.31] - 2026-05-31 @@ -179,7 +179,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). N/A -[unreleased]: https://github.com/StrangeRanger/bash-style-guide/compare/2026.5.31...HEAD +[unreleased]: https://github.com/StrangeRanger/bash-style-guide/compare/2026.6.9...HEAD +[2026.6.9]: https://github.com/StrangeRanger/bash-style-guide/releases/tag/2026.6.9 [2026.5.31]: https://github.com/StrangeRanger/bash-style-guide/releases/tag/2026.5.31 [2026.1.21]: https://github.com/StrangeRanger/bash-style-guide/releases/tag/2026.1.21 [2025.7.15]: https://github.com/StrangeRanger/bash-style-guide/releases/tag/2025.7.15 diff --git a/docs/guidelines/error-handling.md b/docs/guidelines/error-handling.md index f07be04..105bcb9 100644 --- a/docs/guidelines/error-handling.md +++ b/docs/guidelines/error-handling.md @@ -22,6 +22,7 @@ Commands like `cd`, `rm`, and `mv` can fail for many reasons, including incorrec type: example ```bash +# Exit if changing to the specified directory fails. cd /some/path || exit 1 rm file ``` @@ -31,12 +32,13 @@ rm file //// tab | Error Messages for Clarity - **Guideline**: When a command fails, provide a clear error message that explains what went wrong. - - **Reason**: Clear error messages help users, including yourself, understand what failed and why, making troubleshooting easier. + - **Reason**: Error messages help users, including yourself, understand what failed and why, making troubleshooting easier. ///// admonition | Example type: example ```bash +# Exit if changing to the specified directory fails, and provide an error message. cd /some/path || { echo "ERROR: Failed to change directory to '/some/path'" >&2 exit 1 @@ -65,7 +67,7 @@ Standard error (`stderr`) is a [file descriptor](https://mywiki.wooledge.org/Fil ```bash cd /some/nonexistent/path || { - echo "Error: Failed to change directory to '/some/nonexistent/path'" >&2 + echo "ERROR: Failed to change directory to '/some/nonexistent/path'" >&2 exit 1 } ``` @@ -81,7 +83,7 @@ The `trap` command lets scripts capture and respond to signals sent by the syste //// tab | Cleanup Operations - **Usage**: Use `trap` to define actions, such as removing temporary files, that should run before a script exits. - - **Reason**: Without `trap`, reliable cleanup can be difficult, especially if a script exits unexpectedly. `trap` runs cleanup actions regardless of how the script ends, helping keep the environment clean. + - **Reason**: Without `trap`, reliable cleanup can be difficult, especially if a script exits unexpectedly. Traps ensure cleanup actions run regardless of how the script ends, helping keep the environment clean. ///// admonition | Example type: example @@ -116,28 +118,27 @@ TMP_FILE=$(mktemp) # Define a cleanup function. cleanup() { - if (( $1 == 0 )); then - echo "[INFO] Exiting normally" - else + local exit_code="$1" + + if (( exit_code != 0 )); then echo "[ERROR] An error occurred" >&2 + echo "[NOTE] Exit code: $exit_code" >&2 fi - echo "[INFO] Cleaning up..." - rm -f "$TMP_FILE" \ - && echo "[INFO] Temporary file removed" \ - || { - echo "[ERROR] Failed to remove temporary file" >&2 - echo "[NOTE] Please remove it manually: $TMP_FILE" - } + echo "[INFO] Cleaning up..." + rm "$TMP_FILE" || { + echo "[ERROR] Failed to remove temporary file" >&2 + echo "[NOTE] Please remove it manually: '$TMP_FILE'" >&2 + } - echo "[INFO] Exiting with status code: $1" - exit "$1" + echo "[INFO] Exiting..." + exit "$exit_code" } # Trap EXIT signal and invoke the cleanup function. trap 'cleanup $?' EXIT -echo "[INFO] Performing some operations..." +echo "[INFO] Performing some operations..." # Simulate an error. exit 1 diff --git a/docs/guidelines/style.md b/docs/guidelines/style.md index 02c5847..74a3b7e 100644 --- a/docs/guidelines/style.md +++ b/docs/guidelines/style.md @@ -26,7 +26,7 @@ echo "Hello, $name" //// tab | Single Quotes (`'`) - **String Literals**: Use single quotes to define string literals. - - **Reason**: Single quotes preserve the literal value of every character in a string, preventing the shell from performing expansions or substitutions. This behavior is important for commands such as `find`, `grep`, and `awk`, each of which has its own rules for interpreting special characters. Single quotes ensure that these commands receive the input exactly as written, without the shell modifying it first. + - **Reason**: Single quotes preserve the literal value of every character in a string, preventing the shell from performing expansions or substitutions. This behavior is important for commands such as `find`, `grep`, and `awk`, each of which has its own rules for interpreting special characters. Single quotes ensure that these commands receive the input exactly as written, without the shell first modifying it. ///// admonition | Example type: example @@ -88,7 +88,7 @@ Bash offers several ways to declare variables, each with implications for scope, - **Naming Convention**: Use `snake_case` for variable names. - **Scope Management**: Use the `local` keyword to limit a variable's scope to a function. - - **Reason**: Declaring a variable as `local` prevents accidental overwrites of global variables with the same name. It also ensures that once the function completes, the variable is unset and released from memory. (1) + - **Reason**: Declaring a variable as `local` prevents accidental overwrites to global variables with the same name. It also ensures that once the function completes, the variable is unset and released from memory. (1) { .annotate } 1. **Variable Scope**: In Bash, variables declared inside a function without the `local` keyword are global by default, meaning they persist beyond the function's scope and can impact other parts of the script.