Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (96 loc) · 2.51 KB

CONTRIBUTING.md

File metadata and controls

132 lines (96 loc) · 2.51 KB

Contributing to zgrok

Development Setup

git clone https://github.com/copyleftdev/zgrok.git
cd zgrok
cargo build
cargo test

Code Standards

No Tutorial Comments

Comments explaining what code does are prohibited. Code must be self-documenting.

// BAD
let count = 0; // Initialize counter to zero

// BAD
// Loop through items and process each one
for item in items { process(item); }

// GOOD - no comment needed
let active_connections = 0;
for connection in connections { connection.process(); }

// GOOD - explains why, not what
// Subtract 1 because stream IDs are 1-indexed in the protocol
let index = stream_id - 1;

Allowed comments:

  • TODO, FIXME
  • SAFETY: for unsafe blocks
  • Doc comments (///) for public APIs
  • Non-obvious "why" explanations

Error Handling

  • Use thiserror for library errors
  • Use anyhow for binary errors
  • No .unwrap() in library code
  • Propagate errors with ?

Async

  • Tokio runtime
  • Prefer async fn over manual Future implementations
  • Use tokio::select! for concurrent operations

Imports

Group in order:

  1. std
  2. External crates
  3. Workspace crates
  4. crate::
  5. super::, self::

Branch Workflow

# 1. Start from main
git checkout main && git pull

# 2. Create feature branch
git checkout -b feat/short-description

# 3. Make changes, then verify
cargo test && cargo clippy -- -D warnings && cargo fmt --check

# 4. Commit
git add -A && git commit -m "feat(component): description"

# 5. Push and create PR
git push -u origin feat/short-description
gh pr create --fill

# 6. Merge after review
gh pr merge --squash --delete-branch

# 7. Return to main
git checkout main && git pull

Commit Messages

Format: type(scope): description

Types:

  • feat - New feature
  • fix - Bug fix
  • refactor - Code change that neither fixes a bug nor adds a feature
  • docs - Documentation only
  • test - Adding or fixing tests
  • chore - Maintenance tasks

Examples:

feat(agent): add TCP tunnel support
fix(edge): handle connection timeout gracefully
refactor(protocol): simplify frame encoding

Testing

# All tests
cargo test

# Single crate
cargo test -p zgrok-protocol

# Single test
cargo test test_name

# With output
cargo test -- --nocapture

Write tests alongside code in #[cfg(test)] modules.

Pull Request Checklist

  • Tests pass: cargo test
  • No warnings: cargo clippy -- -D warnings
  • Formatted: cargo fmt --check
  • No tutorial comments
  • Commit message follows convention