Skip to content
bz

Contributing

We welcome contributions to bz! This guide explains how to get started.

Ways to Contribute

  • Report bugs - Open an issue describing the problem
  • Suggest features - Open an issue with your idea
  • Improve documentation - Fix typos, add examples, clarify explanations
  • Submit code - Fix bugs or implement features

Development Setup

  1. Fork and clone

    Terminal window
    git clone https://github.com/YOUR-USERNAME/bz.git
    cd bz

  2. Install dependencies

    Terminal window
    go mod download

  3. Build

    Terminal window
    go build -o bz .

  4. Run tests

    Terminal window
    go test ./...

  5. Set up dev workflow

    The project uses just as a task runner and lefthook for Git hooks. Install both, then run:

    Terminal window
    lefthook install

    See the justfile for available recipes (e.g., just test, just lint).

Code Structure

bz/
├── cmd/              # CLI commands (Cobra)
│   ├── mod/          # mod subcommands (search, sync, etc.)
│   ├── registry/     # registry subcommands
│   └── root.go       # Root command
├── internal/         # Internal packages
│   ├── bzconfig/     # bz configuration loading
│   ├── cli/          # CLI helpers
│   ├── cmdutil/      # Command utilities
│   ├── config/       # Configuration types
│   │   └── modules/  # Module configuration
│   ├── depgraph/     # Dependency graph
│   ├── envutil/      # Environment utilities
│   ├── modsync/      # Module sync service
│   ├── module/       # Module types
│   ├── modulearg/    # Module argument parsing
│   ├── osv/          # OSV vulnerability data
│   ├── publisher/    # Publisher implementations
│   ├── registry/     # Registry implementations
│   ├── starlark/     # Starlark interpreter
│   │   ├── builtins/ # Built-in Starlark functions
│   │   ├── convertutil/ # Starlark conversion utilities
│   │   └── value/    # Starlark value types
│   ├── testutil/     # Test utilities
│   ├── tui/          # Terminal UI components
│   └── version/      # Version information
├── docs/             # Documentation (Starlight)
├── justfile          # Task runner recipes (just)
├── lefthook.yml      # Git hooks configuration
└── main.go           # Entry point

Making Changes

  1. Create a branch

    Terminal window
    git checkout -b feature/my-feature
    # or
    git checkout -b fix/my-bugfix

  2. Make your changes

    • Follow existing code style
    • Add tests for new functionality
    • Update documentation if needed

  3. Run tests

    Terminal window
    go test ./...

  4. Run linter

    Terminal window
    go tool -modfile=tools.go.mod golangci-lint run --config=tools/lint/golangci.toml

  5. Commit

    Terminal window
    git add .
    git commit -m "feat: add my feature"

    Use Conventional Commits:

    • feat: - New feature
    • fix: - Bug fix
    • docs: - Documentation
    • refactor: - Code refactoring
    • test: - Tests
    • chore: - Maintenance

  6. Push and create PR

    Terminal window
    git push origin feature/my-feature

    Then open a Pull Request on GitHub.

Pull Request Guidelines

  • Keep PRs focused - one feature or fix per PR
  • Include tests for new functionality
  • Update documentation if behavior changes
  • Ensure all tests pass
  • Respond to review feedback

Testing

Unit Tests

Terminal window
# Run all tests
go test ./...


# Run tests with coverage
go test -cover ./...


# Run specific package tests
go test ./internal/registry/...

Integration Tests

Terminal window
# Build and test CLI
go build -o bz .
./bz mod search rules_go
./bz mod info rules_go

Documentation

Documentation lives in docs/ and uses Starlight.

Local Development

Terminal window
cd docs
bun install
bun run dev

Visit http://localhost:4321/bz/ to preview.

Note: We use bun as the package manager for the docs. Do not use npm or yarn.

Writing Docs

  • Use MDX format (.mdx files)
  • Keep explanations clear and concise
  • Include code examples
  • Test that code examples work

Questions?

Thank you for contributing!