Date: 2025-02-23

Status

Accepted

Context

Our project requires multiple external tools and dependencies:

• System package managers (Homebrew)
• TeX distribution and packages
• Conversion tools (Pandoc, Calibre)
• Ruby gems for development
• Platform-specific tools (Kindle Previewer)

We need a reliable strategy to manage these dependencies across development environments.

Decision

We will implement the following dependency management strategy:

1. System Package Management

   • Homebrew as primary package manager on macOS
   • Explicit version requirements in PackageDefinitions
   • Automated health checks and updates
   • Consistent installation patterns

2. Version Control

   • Pin major versions of critical tools
   • Regular update checks via setup_tools
   • Version compatibility matrix documentation
   • Automated version validation

3. Installation Management

   • Dedicated managers per tool type:
     • HomebrewManager for system packages
     • TeXManager for TeX packages
     • KindleManager for Amazon tools
   • Consistent interface across managers
   • Automated installation verification

4. Update Strategy

   • Regular automated checks for updates
   • Controlled update process
   • Version change logging
   • Compatibility testing post-update

Consequences

Positive

• Reliable dependency state across environments
• Automated update management
• Clear version requirements
• Consistent installation process
• Easy dependency health checking

Negative

• Complex dependency graph to maintain
• Need to manage multiple package managers
• Version conflicts between tools
• Platform-specific complications