[Distribution]: Homebrew formula for macOS/Linux users

[behrangsa]

Summary

Create a Homebrew formula to enable easy installation of Samoid on macOS and Linux systems via brew install samoid.

Distribution Channel

🍺 Homebrew - macOS/Linux package manager (brew install)

Target Users

Target audience:

• macOS developers using Homebrew as primary package manager
• Linux developers who prefer Homebrew over native package managers
• Users wanting simple one-command installation and updates
• Development teams standardizing on Homebrew for tool management

Current State

Current installation options:

• Manual binary download from GitHub releases (complex for end users)
• cargo install samoid (Rust developers only)
• Limitations:
  • No automatic updates
  • Manual PATH management required
  • No dependency resolution
  • Complex uninstallation process

Proposed Implementation

Implementation plan:

• Create Homebrew formula (samoid.rb) with proper binary download URLs
• Set up automated formula updates via GitHub Actions on new releases
• Test installation across macOS (Intel/ARM) and Linux platforms
• Submit to homebrew-core or create dedicated tap repository
• Update documentation with brew installation instructions

Acceptance Criteria

• Homebrew formula created and validated for samoid
• Formula supports both macOS (Intel/ARM) and Linux (x86_64)
• Automated formula update workflow on new releases
• Installation tested on multiple Homebrew environments
• Formula submitted to homebrew-core or published in dedicated tap
• Documentation updated with brew install samoid instructions
• Formula properly handles updates via brew upgrade samoid
• Clean uninstallation via brew uninstall samoid

Target Platforms

• macOS (Intel x64)
• macOS (Apple Silicon ARM64)
• Linux (x86_64)

Package Manifest/Formula Details

Package configuration:

• Package name: samoid
• Version management: Automatic from GitHub releases using semver tags
• Dependencies: None (statically linked Rust binary)
• Installation location: /usr/local/bin (Homebrew standard)
• Configuration files: None required for core functionality

Automation & Publishing

Automation approach:

• Trigger: On new GitHub release creation
• Update mechanism: Automated PR to homebrew-core or direct tap update
• Validation: Formula linting, installation testing via brew test-bot
• Rollback plan: Revert formula commit if installation issues discovered

Testing Strategy

Testing plan:

• Fresh installation on clean macOS/Linux systems via brew install samoid
• Update scenarios testing brew upgrade samoid from previous versions
• Uninstallation cleanup verification via brew uninstall samoid
• Cross-platform compatibility testing (Intel Mac, ARM Mac, Linux)
• Integration testing with existing Homebrew workflows

Security Considerations

Security requirements:

• SHA256 checksum validation for downloaded binaries
• HTTPS-only download URLs from GitHub releases
• Formula review process compliance (homebrew-core requirements)
• Signature verification of release artifacts (depends on [Quality]: Cryptographic signing of release artifacts #36)

Long-term Maintenance

Maintenance considerations:

• Automated formula updates reduce manual maintenance
• Monitor Homebrew ecosystem changes and deprecations
• Handle formula migration if tap repository structure changes
• Community support via Homebrew issue tracking
• Coordinate with Homebrew maintainers for homebrew-core inclusion

Dependencies & Prerequisites

Prerequisites:

• Depends on: Multi-platform binary distribution (Release Management and Distribution #12 - AC12.3) ✅
• Depends on: Release workflow automation (Release Management and Distribution #12 - AC12.15) ✅
• Relates to: Cryptographic signing ([Quality]: Cryptographic signing of release artifacts #36) for enhanced security
• Requires: Homebrew tap repository or homebrew-core submission approval

Success Metrics

Success criteria:

• Installation success rate: >95% across supported platforms
• User feedback: Positive reception from Homebrew community
• Adoption metrics: brew install downloads tracked
• Reduced GitHub Issues related to manual installation problems

Priority: High

Effort: 3-5 story points (Medium complexity with automation)
Phase: Transition

Source

Package manager integration best practices and Homebrew formula requirements.

Original Reference: Issue #12 - AC12.9