Skip to main content

Contributing to beachcomber

Thanks for your interest in contributing! beachcomber is a Rust project that benefits from contributions of all kinds — bug reports, documentation improvements, new providers, performance optimizations, and consumer integrations.

Getting Started​

git clone https://github.com/OWNER/beachcomber.git
cd beachcomber
cargo build
cargo test

The binary is comb (not beachcomber):

cargo run -- get hostname.name -f text

Development​

Prerequisites​

  • Rust 1.85+ (see mise.toml for exact version)
  • macOS (Linux support is planned but not yet implemented)

Running Tests​

cargo test

Some tests require filesystem watching (FSEvents) and may not work inside sandboxed environments. These are the watcher tests and the uptime_provider_executes test.

Running Benchmarks​

cargo bench

See docs/performance.md for the performance regression checklist — verify these thresholds before submitting PRs that touch the hot path.

Project Structure​

See docs/architecture.md for a full overview. Key files:

  • src/scheduler.rs — the core: trigger management, provider execution, subscriptions
  • src/server.rs — Unix socket server, protocol handling
  • src/cache.rs — concurrent cache (DashMap)
  • src/provider/ — all provider implementations
  • benches/ — criterion benchmarks

Contributing a New Provider​

See docs/provider-development.md for a step-by-step walkthrough. The short version:

  1. Create src/provider/yourprovider.rs implementing the Provider trait
  2. Add tests in tests/provider_yourprovider.rs
  3. Register in src/provider/mod.rs and src/provider/registry.rs
  4. Run cargo test and cargo bench --bench providers

Performance guidelines: Read a file instead of spawning a process whenever possible. See the performance tiers in docs/performance.md.

Pull Requests​

  • One logical change per PR
  • Include tests for new functionality
  • Run cargo clippy and cargo fmt before submitting
  • If touching performance-sensitive code, include benchmark results (before/after)
  • Update docs if you change user-facing behavior

Reporting Bugs​

Open an issue with:

  • What you expected to happen
  • What actually happened
  • comb --version output
  • macOS version
  • Steps to reproduce

Code of Conduct​

Be kind, be constructive, assume good intent. We're all here to make terminals better.