spine-runtimes/formatters/logging/terminal-logging-guide.md

Terminal Logging Style Guide

This guide defines the terminal output style for all bash scripts in the Spine Runtimes project.

Design Principles

1. Minimal visual noise - Use color sparingly for emphasis, not decoration
2. Clear hierarchy - Different levels of information have distinct visual treatments
3. Consistent spacing - Clean vertical rhythm throughout output
4. Accessible - Readable and meaningful even without colors
5. Scannable - Easy to quickly identify successes, failures, and important information

Visual Hierarchy

1. Title (log_title)

• Purpose: Main script/tool name
• Style: Bold with vertical spacing
• Usage: Once at the beginning of script execution

log_title "Spine-C++ Build"

2. Action + Result (inline format)

• Purpose: Individual operations with immediate result
• Style: Action on same line as result for density
• Usage: log_action followed immediately by log_ok/fail/warn/skip

log_action "Building all variants"
log_ok                           # Green ✓ on same line

log_action "Testing headless-test"  
log_fail                         # Red ✗ on same line

Results:

• log_ok - Green ✓ (success)
• log_fail - Red ✗ (failure)
• log_warn - Yellow ! (warning)
• log_skip - Gray - (skipped)

4. Error Output (log_error_output)

• Purpose: Full error output when operations fail
• Style: Normal text (not grayed), prominent
• Usage: Show command output after failures

log_action "Building"
if BUILD_OUTPUT=$(command 2>&1); then
    log_ok
else
    log_fail
    log_error_output "$BUILD_OUTPUT"
fi

5. Detail (log_detail)

• Purpose: Secondary information, debug info (not errors)
• Style: Gray text, indented
• Usage: Additional context, platform info

log_detail "Platform: Darwin"
log_detail "Branch: main"

6. Summary (log_summary)

• Purpose: Final result or conclusion
• Style: Bold with vertical spacing
• Usage: End of script execution

log_summary "✓ All tests passed (5/5)"
log_summary "✗ Tests failed (3/5)"

Complete Example

#!/bin/bash
source ../formatters/logging/logging.sh

log_title "Spine-C++ Build"
log_detail "Platform: $(uname)"

log_action "Configuring debug build"
if CMAKE_OUTPUT=$(cmake --preset=debug . 2>&1); then
    log_ok
else
    log_fail
    log_error_output "$CMAKE_OUTPUT"
    exit 1
fi

log_action "Building"
if BUILD_OUTPUT=$(cmake --build --preset=debug 2>&1); then
    log_ok
else
    log_fail
    log_error_output "$BUILD_OUTPUT"
    exit 1
fi

log_summary "✓ Build successful"

Output Preview

Success case:

Spine-C++ Build
Platform: Darwin

  Configuring debug build... ✓
  Building... ✓

✓ Build successful

Failure case:

Spine-C++ Build
Platform: Darwin

  Configuring debug build... ✗
CMake Error: Could not find cmake file...
(full error output shown prominently)

Error Handling Best Practices

1. Capture output: Use OUTPUT=$(command 2>&1) to capture both stdout and stderr
2. Check exit codes: Always check if critical operations succeeded
3. Show errors prominently: Use log_error_output for command failures (not grayed)
4. Fail fast: Exit immediately on critical failures
5. Use inline results: log_action + log_ok/fail for dense, scannable output

Calling Other Scripts

When calling other bash scripts that have their own logging:

1. Trust their logging: Don't wrap calls in redundant log actions
2. Capture output for errors: Use OUTPUT=$(script.sh 2>&1) to capture output and only show on failure
3. Let them handle success: Avoid "script completed" messages when the script shows its own status

Good:

# Let the script handle its own logging
../formatters/format.sh cpp

# Or capture output and only show on error
if output=$(./setup.sh 2>&1); then
    log_ok "Setup completed"
else
    log_fail "Setup failed"
    log_detail "$output"
fi

Avoid:

# This creates duplicate logging
log_action "Formatting C++ files"
../formatters/format.sh cpp
log_ok "C++ formatting completed"

if BUILD_OUTPUT=$(./build.sh clean release 2>&1); then
    log_ok "Build completed"
else
    log_fail "Build failed"
    log_detail "$BUILD_OUTPUT"
    exit 1
fi

Usage

1. Source the utilities in your script:

source ../formatters/logging/logging.sh

2. Follow the hierarchy patterns shown above
3. Use appropriate functions for each type of output
4. Test output both with and without color support