Skip to content

Adopt component log categories and deprecate VERBOSE #188

Description

@codeforester

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

Metadata

Metadata

Assignees

Labels

enhancementNew feature or product improvement

Type

No type

Projects

Status
Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions