Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
339 lines (242 loc) · 7.85 KB

CONTRIBUTING.md

File metadata and controls

339 lines (242 loc) · 7.85 KB

Contributing to async-inspect 🔍

Thank you for your interest in contributing to async-inspect! We're excited to have you join us in making async Rust debugging better for everyone.

🚀 Project Vision

Make async Rust as easy to debug as synchronous code by providing complete visibility into state machines, execution flow, and task interactions.

🤝 Ways to Contribute

🐛 Report Bugs

Found a bug? Please open an issue with:

  • Clear description of the problem
  • Minimal reproduction code
  • Expected vs actual behavior
  • Your environment (OS, Rust version, async runtime)

💡 Suggest Features

Have an idea? Start a discussion or open an issue with:

  • The problem you're trying to solve
  • Your proposed solution
  • Why this would be valuable to others
  • Potential implementation approach

📝 Improve Documentation

Documentation improvements are always welcome! This includes:

  • Fixing typos or unclear explanations
  • Adding examples
  • Improving API documentation
  • Writing guides or tutorials
  • Creating blog posts or videos

💻 Contribute Code

Code contributions are highly valued! See the development guide below.

🏗️ Development Setup

Prerequisites

  • Rust 1.70 or later
  • Node.js 20+ (for documentation site)
  • Git

Getting Started

# Clone your fork
git clone https://github.com/YOUR_USERNAME/async-inspect
cd async-inspect

# Build the project
cargo build

# Run tests
cargo test

# Run examples
cargo run --example basic_inspection

# Run CLI
cargo run --bin async-inspect -- --help

# Build documentation
cargo doc --open

Running Examples

We have many examples demonstrating different features:

# Basic usage
cargo run --example basic_inspection

# TUI monitor
cargo run --example tui_monitor --features cli

# Relationship graphs
cargo run --example relationship_graph

# Ecosystem integration
cargo run --example ecosystem_integration

# Production configuration
cargo run --example production_ready

# Performance analysis
cargo run --example performance_analysis

# Deadlock detection
cargo run --example deadlock_detection

📋 Development Workflow

1. Find or Create an Issue

  • Check existing issues for something to work on
  • Or create a new issue describing what you'd like to add/fix
  • Discuss approach before starting large changes

2. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

3. Make Your Changes

  • Write clear, idiomatic Rust code
  • Follow the existing code style
  • Add tests for new functionality
  • Update documentation as needed

4. Test Your Changes

# Run all tests
cargo test

# Run specific example
cargo run --example YOUR_EXAMPLE

# Check formatting
cargo fmt --check

# Run clippy
cargo clippy -- -D warnings

# Build with all features
cargo build --all-features

5. Commit Your Changes

We follow Conventional Commits:

git commit -m "feat: add new deadlock detection algorithm"
git commit -m "fix: resolve panic in task tracking"
git commit -m "docs: improve README examples"
git commit -m "chore: update dependencies"

Types: feat, fix, docs, style, refactor, perf, test, chore

6. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a PR on GitHub with:

  • Clear title describing the change
  • Description explaining what and why
  • Link to related issues
  • Screenshots/examples if relevant

🎨 Code Style Guidelines

Rust Code

  • Run cargo fmt before committing
  • Ensure cargo clippy passes with no warnings
  • Use descriptive variable and function names
  • Add doc comments for public APIs
  • Keep functions focused and small
  • Prefer clarity over cleverness

Documentation

  • Use clear, concise language
  • Include code examples
  • Explain the "why" not just the "what"
  • Keep examples runnable and tested

Commit Messages

  • Use present tense ("add feature" not "added feature")
  • Use imperative mood ("move cursor to..." not "moves cursor to...")
  • Reference issues and PRs liberally

🧪 Testing

Test Requirements

  • All new features must have tests
  • Bug fixes should include regression tests
  • Aim for high code coverage
  • Test both success and error cases

Test Types

# Unit tests
cargo test --lib

# Integration tests
cargo test --test '*'

# Doc tests
cargo test --doc

# All tests with all features
cargo test --all-features

Example Tests

Add tests to the appropriate module:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_task_creation() {
        let task = TaskInfo::new("test".to_string());
        assert_eq!(task.name, "test");
        assert_eq!(task.state, TaskState::Pending);
    }

    #[tokio::test]
    async fn test_async_tracking() {
        // Your async test here
    }
}

📦 Project Structure

async-inspect/
├── src/
│   ├── lib.rs              # Library entry point
│   ├── main.rs             # CLI entry point
│   ├── config.rs           # Configuration
│   ├── inspector/          # Core inspection logic
│   ├── task/               # Task tracking
│   ├── timeline/           # Event timeline
│   ├── graph/              # Relationship graphs
│   ├── deadlock/           # Deadlock detection
│   ├── profile/            # Performance profiling
│   ├── export/             # Data export
│   ├── tui/                # Terminal UI
│   ├── integrations/       # Ecosystem integrations
│   │   ├── tracing_layer.rs
│   │   ├── prometheus.rs
│   │   ├── opentelemetry.rs
│   │   └── tokio_console.rs
│   └── reporter/           # Reporting
├── examples/               # Usage examples
├── async-inspect-macros/   # Proc macros
├── docs/                   # Docusaurus site
└── tests/                  # Integration tests

🎯 Areas for Contribution

High Priority

  • ✅ Core infrastructure (mostly complete)
  • ✅ Ecosystem integration (complete)
  • 🔄 Performance optimization
  • 🔄 Additional examples
  • 🔄 Documentation improvements

Medium Priority

  • Advanced deadlock detection algorithms
  • Web-based dashboard
  • Browser-based timeline viewer
  • Additional runtime support (async-std, smol)
  • Grafana dashboard templates

Future Ideas

  • VS Code extension
  • Chrome DevTools integration
  • Distributed tracing support
  • AI-powered anomaly detection
  • Historical trace diff tool

🔍 Code Review Process

What We Look For

  • Correct functionality
  • Good test coverage
  • Clear documentation
  • Following code style
  • No breaking changes (or justified ones)
  • Performance considerations

Timeline

  • Initial review: Usually within 2-3 days
  • Expect iterative feedback
  • Most PRs merge within 1-2 weeks

🌟 Recognition

All contributors are recognized in:

  • README contributors section
  • Release notes
  • Documentation

We use All Contributors to track contributions.

📜 License

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

💬 Communication

  • GitHub Issues: Bug reports, feature requests
  • GitHub Discussions: Questions, design discussions, RFCs
  • Pull Requests: Code contributions
  • Email: For security issues, contact ibrahim@ibrahimcesar.com

🙏 Thank You!

Every contribution, no matter how small, helps make async-inspect better. Whether you're fixing a typo, adding a feature, or just providing feedback—thank you for being part of this project!

❓ Questions?

Not sure where to start? Feel free to:

  • Open a discussion
  • Comment on an existing issue
  • Reach out to maintainers

We're here to help! 🚀