[GingerGraham]

Summary

Addresses the seven open documentation issues for the 3.0 release in one PR, with one commit per issue so each can be traced. The documents still described the 2.x, Bash-only library and left out several 3.0 behaviour changes.

Every message text, mode and behaviour that is now documented was checked against logging.sh and by running the library (bash and dash). zsh and busybox are not installed in the session, so statements about those shells come from docs/shell-compatibility.md and docs/upgrading-to-3.0.md.

Changes

One commit per issue:

• [DOCS] tests/README.md lists 7 suites and 201 tests #155 tests/README.md: replace the fixed suite counts with suites grouped by area, use N placeholders in the example output, and point to docs/testing.md
• [DOCS] Contributor test docs omit the 3.0 cross-shell test suites #173 tests/README.md (bash 3.2, cross-shell runs), docs/writing-tests.md (scenarios, known failures, golden files, shell helpers), and both test skills (TEST_SHELLS command, required after any change to logging.sh)
• [DOCS] Update environment-variable docs and the security-review skill for 3.0 #167 docs/initialization.md (only SCRIPT_NAME is inherited), security-review skill (test_ prefix, _is_readonly and _logger_readonly, _into names), and the list of deliberately kept characters (INF-01)
• [DOCS] README.md still describes bash-logger as Bash-only after 3.0 #169 README.md: shell-neutral wording, a Features bullet and a POSIX sh Quick Start example, and an upgrade NOTE block at the top
• [DOCS] Guides still use Bash-only wording and a 2.7.0 install example after 3.0 #170 guide introductions, POSIX sh examples in Getting Started and Examples, <version> placeholder for INSTALL_VERSION, shell-neutral "check your version" step, new troubleshooting entries, &> label, config header
• [DOCS] Document 3.0 log file behaviour: private modes and per-write symlink check #171 private log files (600 and 700) and the per-write symlink check in sensitive-data.md, troubleshooting.md, initialization.md, getting-started.md and SECURITY.md
• [DOCS] Bring sanitization, tag validation and LOGGER_PATH docs in line with 3.0 #172 sanitization section rewrite, unsafe-mode wording, journal Tag Rules, and "Using a Stub logger in Tests"

Things to review

These go beyond, or differ from, the issue text:

• Stub logger needs more than readonly ([DOCS] Bring sanitization, tag validation and LOGGER_PATH docs in line with 3.0 #172 item 5). With a real logger installed, a readonly LOGGER_PATH alone is still refused, because validation finds a different logger on PATH. The docs show the pattern that tests/test_journal_logging.sh uses (lock the stub and replace _find_and_validate_logger and check_logger_available). docs/upgrading-to-3.0.md still says only "make the value readonly".
• Config tag key corrects, it does not reject ([DOCS] Bring sanitization, tag validation and LOGGER_PATH docs in line with 3.0 #172 item 4). -t, --tag and set_journal_tag keep the previous tag. The config file truncates to 64 characters or replaces unsafe characters with _. The Tag Rules section describes both.
• Tag rules describe the code today. Bidirectional overrides are currently accepted in tags ([BUG] Journal tag validation misses bidi and non-UTF-8-locale controls, and overlong config tags skip sanitising #154), and SCRIPT_NAME is not sanitized before init_logger runs ([SECURITY] SCRIPT_NAME from the environment is used unsanitized before init_logger runs #165). Whichever of those PRs merges second should update the wording.
• running-tests skill: its examples (./tests/run_tests.sh log_levels) fail with "Test file not found". Fixed in the [DOCS] Update environment-variable docs and the security-review skill for 3.0 #167 commit together with the security-review skill.
• Small fixes in sections that were being rewritten: --colors never (not an option) became --no-color, a dead ../examples.md link was replaced, and the "not writable" message no longer shows a path that logging.sh never prints.
• [BUG] test_path_traversal fails under umask 002, the default on Fedora and RHEL #151 says new log files use the caller's umask. On this branch they are created as 600 and directories as 700 under every umask, and Created log files have secure permissions passes under umask 002. The docs follow the code and the upgrade guide.

Testing

• Markdown: all 43 tracked .md files pass markdownlint 0.47.0 with .markdownlint.yaml (the version pinned in .pre-commit-config.yaml)
• Commit messages: all seven pass scripts/validate-commit-msg.sh
• Examples added to the docs were run: POSIX sh Quick Start, Getting Started and Examples scripts (dash), the stub logger examples, and the file modes under umask 022, 002 and 000
• Full suite: ./tests/run_tests.sh gives 687 tests, 651 passed, 11 failed, 25 skipped. origin/main gives the same numbers and the same 11 failures. They are permission tests that fail because the session runs as root.

Related issues

Closes #155
Closes #167
Closes #169
Closes #170
Closes #171
Closes #172
Closes #173

Refs #151
Refs #154
Refs #165

---

Generated by Claude Code

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

Approval should be held until the two documented MarkdownLint MD013 line-length violations are addressed and the noted grammatical error in README.md is corrected.

2 open issues

• Long blockquote line and article typo · New
• Long paragraph line exceeds limit · New

What changed in this PR

This pull request updates the project’s documentation and contributor guidance to match bash-logger 3.0 behavior, replacing remaining 2.x-era Bash-only wording and refreshing examples and operational/security notes across the docs set.

Changes:

• Aligns README and guides with 3.0 behavior and shell-neutral / POSIX sh-compatible examples where applicable.
• Updates testing documentation and skills to reflect current suite structure, cross-shell workflows, and stub logger requirements.
• Refreshes security/troubleshooting guidance for 3.0 (sanitization wording, journald/tag behavior, secure log-file modes, symlink/runtime checks).

File	Summary
tests/​README.md	Reworks test-suite documentation and cross-shell run guidance. Nit: avoid contradicting the runner exclusions (test_example.sh, test_helpers.sh) when describing tests/test_*.sh suites.
SECURITY.md	Updates security guidance to reflect 3.0 behavior and secure defaults. Nit: add a trailing period to the noted list item for consistent punctuation.
README.md	Shell-neutral wording, 3.0 upgrade note, and POSIX sh quick start/example updates. Nit: wrap an overlong blockquote line and fix “a expansion” → “an expansion”.
docs/​writing-tests.md	Expands test-writing guidance (scenarios, failures, golden files, helpers). Nit: wrap the noted overlong paragraph line to satisfy MD013.
docs/​upgrading-to-3.0.md	Updates/clarifies 3.0 upgrade guidance and behavior notes.
docs/​troubleshooting.md	Adds/updates 3.0 troubleshooting entries and clarifies behavior.
docs/​testing.md	Documents testing workflows including stub logger patterns consistent with 3.0 validation.
docs/​sensitive-data.md	Updates sanitization and sensitive-data handling guidance to match 3.0 behavior.
docs/​runtime-configuration.md	Minor wording/positioning updates for 3.0.
docs/​README.md	Updates docs index introduction wording to match current positioning.
docs/​output-streams.md	Clarifies redirection guidance and shell applicability.
docs/​log-levels.md	Updates wording to match current naming/behavior.
docs/​journal-logging.md	Updates journald/tag rules documentation and related testing notes.
docs/​initialization.md	Clarifies initialization behavior and environment inheritance in 3.0.
docs/​getting-started.md	Updates getting-started steps, examples, and 3.0-era notes.
docs/​formatting.md	Wording and guidance refresh consistent with 3.0 docs set.
docs/​examples.md	Updates examples and clarifies shell expectations/compatibility.
docs/​configuration.md	Refreshes configuration guidance and unsafe-mode wording.
docs/​api-reference.md	Aligns reference docs with 3.0 behavior descriptions.
.claude/​skills/​writing-tests/​SKILL.md	Updates skill guidance to match current test workflow and cross-shell expectations.
.claude/​skills/​security-review/​SKILL.md	Updates security review guidance and references to match current conventions.
.claude/​skills/​running-tests/​SKILL.md	Corrects/updates test-running guidance to match current suite/workflow naming.

This pull request is ready to be approved.

_{Review effort: Balanced}