Problem
Reusable base-bash-libs modules currently emit records through the default
logger. A caller that selects DEBUG for its own diagnostics therefore has no
stable way to keep library diagnostics at INFO unless every library record is
assigned a component category.
The library also exposes a Bash-specific VERBOSE level and log_verbose*
helpers. There are no production callers in the Base repositories, and
non-Bash wrappers already collapse --verbose-wrapper to the same
LOG_DEBUG=1 contract as --debug-wrapper.
Goal
Adopt component categories throughout the reusable library and begin a
compatibility-safe deprecation of the extra VERBOSE surface.
Dependency
Scope
- Assign every internal library log call to one of these categories:
base_bash_libs.std
base_bash_libs.arg
base_bash_libs.file
base_bash_libs.git
base_bash_libs.gh
- Initialize the parent
base_bash_libs category at INFO so a caller's DEBUG
terminal setting does not implicitly enable reusable-library DEBUG records.
- Preserve explicit opt-in:
--debug-wrapper enables DEBUG terminal output and the
base_bash_libs DEBUG category.
--verbose-wrapper preserves its current terminal and library-category
behavior during the deprecation window.
- Mark these compatibility surfaces deprecated in documentation and source
comments without emitting runtime warnings:
- the
VERBOSE level;
log_verbose and log_verbose_file;
log_verbose_enter and log_verbose_leave;
--verbose-wrapper.
- Keep all deprecated symbols and their current behavior in the 1.x line.
- Document how applications can independently configure caller and reusable
library diagnostics.
- Add a changelog entry and focused regression coverage.
Acceptance criteria
- A caller using DEBUG while
base_bash_libs remains at its default INFO gate
does not receive library DEBUG records.
- Enabling
base_bash_libs=DEBUG enables DEBUG records for every library
component.
- A child override such as
base_bash_libs.git=DEBUG enables only that
component when the parent remains at INFO.
- Every production severity call in the reusable modules has a component
category.
--debug-wrapper continues to expose command-line and library DEBUG output.
- Existing
VERBOSE calls and --verbose-wrapper retain their exact runtime
behavior.
- Deprecation documentation identifies the next major release as the earliest
removal point.
- Focused BATS tests and the complete repository validation pass.
Non-goals
- Removing or aliasing the
VERBOSE level in this change.
- Emitting deprecation warnings at runtime.
- Deprecating
basectl --verbose-wrapper; that belongs to a separate Base
issue/PR after this library train is available.
- Changing rendered log-record formatting.
- Changing
VERSION or publishing a release.
Validation
- Focused logging tests in
lib/bash/std/tests/lib_std.bats.
- Module-level category coverage, including
lib/bash/git/tests/lib_git.bats.
- Wrapper/launcher compatibility coverage.
./tests/validate.sh
git diff --check
Problem
Reusable
base-bash-libsmodules currently emit records through the defaultlogger. A caller that selects DEBUG for its own diagnostics therefore has no
stable way to keep library diagnostics at INFO unless every library record is
assigned a component category.
The library also exposes a Bash-specific
VERBOSElevel andlog_verbose*helpers. There are no production callers in the Base repositories, and
non-Bash wrappers already collapse
--verbose-wrapperto the sameLOG_DEBUG=1contract as--debug-wrapper.Goal
Adopt component categories throughout the reusable library and begin a
compatibility-safe deprecation of the extra
VERBOSEsurface.Dependency
log_is_enabledcontract.Scope
base_bash_libs.stdbase_bash_libs.argbase_bash_libs.filebase_bash_libs.gitbase_bash_libs.ghbase_bash_libscategory at INFO so a caller's DEBUGterminal setting does not implicitly enable reusable-library DEBUG records.
--debug-wrapperenables DEBUG terminal output and thebase_bash_libsDEBUG category.--verbose-wrapperpreserves its current terminal and library-categorybehavior during the deprecation window.
comments without emitting runtime warnings:
VERBOSElevel;log_verboseandlog_verbose_file;log_verbose_enterandlog_verbose_leave;--verbose-wrapper.library diagnostics.
Acceptance criteria
base_bash_libsremains at its default INFO gatedoes not receive library DEBUG records.
base_bash_libs=DEBUGenables DEBUG records for every librarycomponent.
base_bash_libs.git=DEBUGenables only thatcomponent when the parent remains at INFO.
category.
--debug-wrappercontinues to expose command-line and library DEBUG output.VERBOSEcalls and--verbose-wrapperretain their exact runtimebehavior.
removal point.
Non-goals
VERBOSElevel in this change.basectl --verbose-wrapper; that belongs to a separate Baseissue/PR after this library train is available.
VERSIONor publishing a release.Validation
lib/bash/std/tests/lib_std.bats.lib/bash/git/tests/lib_git.bats../tests/validate.shgit diff --check