Overhaul pass: robustness, readability, and docs#172
Merged
Conversation
- README: remove Next-Level Roadmap, Migration Guide, Behavior Contracts section; fold parser/logging guarantees into Features, fold style rules into Coding Style with CI-enforced note (374 → 256 lines) - main.sh: remove unused __invocation variable, fix "increcemnt" typo, add comments explaining ; true log pattern and NO_COLOR detection - src/templater.sh: send error messages to stderr - test/acceptance.sh: fix stale deploy.sh comment, remove Travis-specific sed patterns - example.sh: clarify duplicated sections are intentional overrides - repodocs/overhaul.md: condense iteration log to summary Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Script archetypes, strict mode, exit semantics → FAQ entrypoint/library answer - Function packaging, export -f → already in Best Practices and FAQ - Parser as contract → already in Features - Portability boundary → already in FAQ portability answer - Compatibility matrix → folded into Testing section - Remove Design Principles section and TOC entry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Move Testing, Release Checklist, and CI-enforced coding standards to new CONTRIBUTING.md - Rephrase README coding style as recommendations for consuming devs (ShellCheck as suggestion, not CI rule) - Simplify Best Practices intro - Point FAQ "How can I contribute" to CONTRIBUTING.md - README 236 → 188 lines: now fully consumer-facing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Consolidate 8 shellcheck SC2034 disables into single declaration block
- Break up dense color-detection conditional across multiple lines
- Fix __b3bp_err_report: consistent 2-space indent, function keyword,
quoted and braced exit "${error_code}"
- Simplify repeatable arg display: remove fragile declare -p|grep
pattern in favor of direct array iteration
- Reword pipefail comment to explain the real-life example
- Clarify set +o nounset comment (getopts/OPTARG reference)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
kvz
changed the title
Add test/shfmt.sh that installs shfmt v3.12.0 idempotently and supports lint and fix modes. Wire into package.json as yarn lint:shfmt / fix:shfmt. CI picks it up automatically via the existing npm-run-all 'lint:**' pattern. Config: shfmt -i 2 -bn (2-space indent, binary ops may start a line). Apply shfmt formatting across all .sh files. Key style changes: - function foo() instead of function foo () - one statement per line - no double blank lines between sections - spaces in arithmetic: $((OPTIND - 1)) - done <<<"..." (no space before heredoc) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
kvz
marked this pull request as ready for review
March 3, 2026 14:05
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
b3bp's docs had grown organically over the years — README was 374 lines mixing contributor instructions with user guidance, Design Principles lived in their own section but duplicated FAQ content, and main.sh had accumulated formatting inconsistencies and stale comments. The src/ libraries also had strict-mode and error-handling gaps that could bite users who source them.
This pass tightens the project across code, tests, and docs while staying true to b3bp's mission: a delete-key friendly, Bash 3+ portable starter template.
What changed
main.sh — the core template
--flag, missing values, invalid--flag=valueon boolean options)# shellcheck disablecomments into one declaration block, broke dense color-detection conditional across multiple lines, fixed inconsistent indentation in__b3bp_err_reportmysqldump | gzipas a real-life example), clarifiedset +o nounsetreason, added;truepattern explanation on log functionssrc/ libraries
Documentation
Testing
main-longopt-errors,main-logging-contracts,parse_url-robust,parse_url-strict,ini_val-robust,templater-robusttest/bash3-docker.shruns the full suite against Alpine bash:3.2.57, catching portability issues that modern Bash hidestest/release-ready.shchecks branch, clean tree, green CI, and CHANGELOG state before taggingyarn test:fastruns contract-focused subset for quick feedbackHousekeeping
increcemnt→increment)./deploy.shreference in acceptance.sh usage commentValidation
All lanes green:
yarn lint:shellcheck(warning severity)yarn lint:styleyarn test(full acceptance suite)yarn test:fast(contract subset)yarn test:bash3:docker(Bash 3.2.57)