Skip to main content
Thanks for your interest in contributing to zerobrew! This guide will help you get started.

​
Licensing

By contributing to zerobrew, you agree your contributions will be dual-licensed under either Apache OR MIT, at the licensee’s choice.

​
Prerequisites

Rust 1.90+

Install the latest stable Rust toolchain

macOS or Linux

Development requires either platform

​
A Note on LLM Usage

While we encourage the use of LLMs for thinking through problems, helping with tests, and even writing code, we cannot accept PRs with no clear guidance or thought put into them.
We reserve the right to close PRs that exhibit clear indicators of heavy LLM usage without thoughtful engagement. Code must reach a level of quality that’s typically achieved through thoughtful engagement in the community and the issues/agenda of zerobrew.
If you need help or want to walk through an issue or idea with maintainers, join the community Discord - we’re happy to assist!

​
Project Structure

zerobrew is organized as a Cargo workspace with three crates:

zb_core

Core data models and domain logic (formula resolution, bottle selection)

zb_io

I/O operations (API client, downloads, extraction, installation)

zb_cli

Command-line interface
Any changes that touch several crates should be organized properly. See commit hygiene below.

​
Development Workflow

We prefer that PRs are linked to an open issue or previously discussed through other channels. If you’re introducing changes that aren’t tracked, reach out in Discord or open an issue first.

​
General Flow

1

Fork the repository

Create your own fork of the zerobrew repository
2

Make your changes

Ensure at minimum:
  • Code is formatted: cargo fmt --all
  • No clippy warnings: cargo clippy --workspace --all-targets -- -D warnings
  • Unit tests pass: cargo test --workspace
  • Integration tests pass: cargo test --workspace -- --ignored
These will run in CI, but it’s best to clean up your code before opening a PR to ensure a quick turnaround!
3

Write tests

Each module should have accompanying tests for new functionality
4

Commit with clear messages

Follow our commit hygiene guidelines
5

Push and create PR

Push to your fork and submit a pull request

​
Using Just

This project includes a Justfile. Install just and use these commands: 
just build  # Format, lint, then build debug binary
Before creating a PR, make sure you build your changes and test them.
You can customize the installation directory with $ZEROBREW_BIN: 
export ZEROBREW_BIN=~/bin
just install

​
Commit Hygiene

Follow this format for commit messages: 
[prefix]($crate): description

​
Examples

fix(zb_cli): handle edge case in command parsing
feat(zb_core): add support for bottle selection caching
chore(zb_io): update dependency versions

​
Allowed Prefixes

PrefixDescription
fixFixes a bug or regression
featNew feature
choreHousekeeping (deps, typos in docs, etc.)
testsAdded, changed, or removed tests
ciChanges to CI
refactorRefactored code
perfPerformance related
buildChanges to build system (external deps, tooling, scripts)

​
Atomic Commits

Write isolated, atomic commits. If your PR touches various parts of the codebase, ensure commits are contained and cleanly separated, properly describing which changes belong where.

​
Testing

  • Colocate with code in mod tests blocks
  • Use tempfile for filesystem tests
  • Tests should be deterministic and not rely on external network access
  • Use wiremock for HTTP mocking
  • Run with: cargo test --workspace -- --ignored
  • Or use: just test for all tests

​
Running Benchmarks

To benchmark performance: 
just bench --full
This runs a 100-package installation suite comparing zerobrew to Homebrew. This is crucial if you’re contributing performance/optimization changes.

​
Useful Options

just bench --quick  # 22 packages

​
Notes

  • Defaults to the quick package list (22 packages); use --full for all 100
  • --full [dir] writes all formats (txt/json/csv/html) to the directory
  • --output infers format from file extension when --format is omitted
  • Output includes cold + warm cache speedups per package

​
macOS Homebrew Permissions

On macOS, Homebrew should be installed with a user-writable prefix. If just bench fails with a permission error, fix it: 
sudo chown -R "$(whoami)" "$(brew --prefix)"

​
Questions?

Open an Issue

Ask questions or report problems on GitHub

Join Discord

Connect with maintainers and the community

Build docs developers (and LLMs) love

Get started for freeTalk to us