5W1H Specification

• Who: Maintainers, downstream system maintainers (thread_system, logger_system, etc.)
• What: Document and plan removal of deprecated APIs scheduled for v3.0.0
• Where: logger_interface.h, potentially other interface files
• When: Before v3.0.0 release (medium priority)
• Why: Clean API surface, reduce maintenance burden, improve code clarity
• How: Document deprecated APIs, provide migration guides, coordinate with dependent systems

Problem Statement

Currently Deprecated APIs

1. logger_interface.h:179-184

[[deprecated("Use log(log_level, std::string_view, const source_location&) instead")]]
virtual VoidResult log(log_level level,
                       const std::string& message,
                       const std::string& file,
                       int line,
                       const std::string& function) = 0;

Deprecation Reason: Replaced by C++20 source_location based API for:

• Type safety
• Automatic capture at call site
• Reduced parameter count

Potential Additional Candidates

Review needed for:

• result.h: Any legacy factory functions
• error_codes.h: Uppercase constant aliases (backward compatibility)
• Other interface files with legacy overloads

Proposed Roadmap

Phase 1: Documentation (v2.x)

• Create docs/DEPRECATION.md listing all deprecated APIs
• Add migration examples for each deprecated API
• Update CHANGELOG with deprecation notices

Phase 2: Compiler Warnings (v2.x)

• Ensure all deprecated APIs have [[deprecated]] attribute
• Add compile-time deprecation messages with migration hints
• Enable -Wdeprecated in CI for dependent projects

Phase 3: Removal Preparation (v2.x → v3.0.0)

• Notify downstream maintainers via GitHub issues (see deprecation: Notify downstream systems about v0.3.0.0 API changes #220)
• Provide grace period (1-2 minor versions)
• Track migration status in dependent projects

Phase 4: Removal (v3.0.0)

• Remove deprecated APIs (see deprecation: Remove deprecated APIs in v0.3.0.0 #217)
• Update all documentation
• Release v3.0.0 with breaking change notes

Migration Guide Template

## Migrating from Legacy `log()` to `source_location` API

### Before (v2.x, deprecated)
```cpp
logger->log(log_level::info, "message", __FILE__, __LINE__, __func__);

After (v3.0+)

logger->log(log_level::info, "message");  // source_location auto-captured

## Acceptance Criteria

- [x] `docs/DEPRECATION.md` created with complete API list
- [x] Migration guides for each deprecated API
- [x] Downstream systems notified (thread_system, logger_system, pacs_system, etc.) - see #220
- [x] Timeline communicated in CHANGELOG

## Dependent Systems to Notify

| System | Repository | Maintainer | Status |
|--------|------------|------------|--------|
| thread_system | kcenon/thread_system | @kcenon | [#331](https://github.com/kcenon/thread_system/issues/331) |
| logger_system | kcenon/logger_system | @kcenon | [#248](https://github.com/kcenon/logger_system/issues/248) |
| monitoring_system | kcenon/monitoring_system | @kcenon | [#269](https://github.com/kcenon/monitoring_system/issues/269) |
| pacs_system | kcenon/pacs_system | @kcenon | [#399](https://github.com/kcenon/pacs_system/issues/399) |
| database_system | kcenon/database_system | @kcenon | [#276](https://github.com/kcenon/database_system/issues/276) |

## Impact

- **Priority**: Medium (planned for future major version)
- **Effort**: Medium (documentation + coordination)
- **Breaking Change**: Yes (in v3.0.0)

## Related Issues

- #214 - Document all deprecated APIs in DEPRECATION.md (completed)
- #217 - Remove deprecated APIs in v3.0.0 (Phase 4)
- #220 - Notify downstream systems (Phase 3) - **Completed**