Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
237 lines (170 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

237 lines (170 loc) · 5.48 KB

Contributing to bandwidthmon

Thank you for your interest in contributing to bandwidthmon! This document provides guidelines and instructions for contributing.

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers and encourage diverse perspectives
  • Focus on constructive feedback
  • Respect differing viewpoints and experiences

How to Contribute

Reporting Bugs

  1. Check existing issues - Search for similar issues first
  2. Create a detailed report including:
    • Your operating system and version
    • Rust version (rustc --version)
    • Terminal emulator being used
    • Steps to reproduce the issue
    • Expected vs actual behavior
    • Screenshots if applicable

Suggesting Enhancements

  1. Check existing issues for similar suggestions
  2. Create an enhancement issue with:
    • Clear description of the feature
    • Use cases and benefits
    • Possible implementation approach
    • Any potential drawbacks

Pull Requests

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes following the code style guidelines
  4. Test thoroughly on your platform
  5. Commit with clear messages (git commit -m 'Add amazing feature')
  6. Push to your fork (git push origin feature/amazing-feature)
  7. Open a Pull Request with:
    • Clear description of changes
    • Reference to related issues
    • Screenshots/demos if UI changes

Development Setup

Prerequisites

  • Rust 1.70 or later
  • Cargo (comes with Rust)

Getting Started

# Clone your fork
git clone https://github.com/cumulus13/bandwidthmon
cd bandwidthmon

# Build
cargo build

# Run tests (when available)
cargo test

# Run with cargo
cargo run --bin bandwidthmon -- -l

# Build release version
cargo build --release

Project Structure

bandwidthmon/
├── src/
│   ├── bandwidthmon.rs      # Main binary using rasciichart
│   └── bandwidthmon2.rs     # Alternative binary with manual rendering
├── Cargo.toml               # Dependencies and metadata
├── README.md                # Main documentation
├── EXAMPLES.md              # Usage examples
├── CHANGELOG.md             # Version history
└── CONTRIBUTING.md          # This file

Code Style Guidelines

Rust Style

  • Follow the Rust Style Guide
  • Use rustfmt for consistent formatting: cargo fmt
  • Use clippy for linting: cargo clippy
  • Write idiomatic Rust code
  • Add documentation comments for public APIs

Formatting Rules

# Format code
cargo fmt

# Check formatting without changing files
cargo fmt -- --check

# Run clippy
cargo clippy -- -D warnings

Documentation

  • Document all public functions with /// comments
  • Include examples in documentation
  • Keep comments up-to-date with code changes
  • Use clear variable and function names

Error Handling

  • Use anyhow::Result for most functions
  • Use thiserror for custom error types
  • Provide context with .context() when propagating errors
  • Never use unwrap() or expect() in production code

Testing

While tests are not yet comprehensive, contributions should:

  • Not break existing functionality
  • Be tested manually on your platform
  • Include test cases for new features (when test infrastructure is added)

Commit Message Guidelines

Format

<type>: <subject>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Build process or auxiliary tool changes

Examples

feat: add export to CSV functionality

Add ability to export bandwidth statistics to CSV format
for later analysis. Includes new --export flag.

Closes #123

fix: handle interface disconnection gracefully

Previously crashed when interface was disconnected during monitoring.
Now shows error message and exits cleanly.

Fixes #456

Feature Ideas

We welcome contributions in these areas:

High Priority

  • Export data to CSV/JSON
  • Network traffic filtering by port/protocol
  • Alert thresholds for bandwidth limits
  • Historical data persistence

Medium Priority

  • Multiple interface monitoring in single view
  • Packet count statistics
  • Connection tracking
  • Interactive mode with keyboard navigation

Low Priority

  • Configuration file support
  • Custom color schemes
  • Plugin system
  • Remote monitoring support

Testing Checklist

Before submitting a PR, ensure:

  • Code compiles without warnings (cargo build)
  • Code is formatted (cargo fmt)
  • Clippy passes (cargo clippy)
  • Tested on your platform
  • Documentation is updated
  • CHANGELOG is updated
  • Commit messages follow guidelines

Platform-Specific Testing

If possible, test on:

  • Linux (various distributions)
  • macOS
  • Windows
  • BSD systems

Note the platforms you've tested on in your PR description.

Questions?

  • Open an issue for discussion
  • Email the maintainer: cumulus13@gmail.com
  • Check existing issues for similar questions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Recognition

All contributors will be recognized in:

  • Git history
  • Release notes
  • README (for significant contributions)

Thank you for contributing to bandwidthmon! 🎉