Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
381 lines (266 loc) · 8.22 KB

CONTRIBUTING.md

File metadata and controls

381 lines (266 loc) · 8.22 KB

Contributing to MAIL-CARD

We welcome contributions from developers around the world! MAIL-CARD is a modern email infrastructure server built in Rust, and we'd love your help in making it even better.

🚀 Getting Started

Prerequisites

  • Rust 1.70+ (stable recommended)
  • OpenSSL development libraries
  • Git

Development Setup

# Clone the repository
git clone https://github.com/GLOBAL-FINTECH/mailcard.git
cd mailcard

# Install Rust toolchain
rustup install stable
rustup component add rustfmt clippy

# Build the project
cargo build

# Run tests
cargo test

# Run with example configuration
cargo run -- --config config.example.toml

Development Dependencies

# Install useful development tools
cargo install cargo-audit    # Security audit
cargo install cargo-deny     # License checking
cargo install cargo-watch    # Auto-reload during development

📋 Coding Standards

Code Quality

  • Rustfmt: All code must be formatted with cargo fmt
  • Clippy: All clippy warnings must be resolved or explicitly allowed
  • Tests: New features must include unit tests
  • Documentation: Public APIs must have rustdoc comments

Pre-commit Checklist

# Format code
cargo fmt

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

# Run tests
cargo test --all-features

# Run security audit
cargo audit

# Check documentation
cargo doc --no-deps --all-features

🏗️ Project Structure

MAIL-CARD/
├── src/                    # Core source code
│   ├── main.rs            # Application entry point
│   ├── server.rs          # Server implementations
│   ├── smtp/              # SMTP protocol handling
│   ├── imap/              # IMAP protocol handling
│   ├── pop3/              # POP3 protocol handling
│   ├── storage/           # Storage abstraction
│   └── security/          # Security features
├── docs/                   # Documentation
│   ├── architecture/      # System architecture
│   ├── protocols/         # Protocol documentation
│   └── api/              # API documentation
├── tests/                  # Integration tests
├── benches/               # Performance benchmarks
└── examples/              # Example configurations

🔄 Development Workflow

1. Create an Issue

Before starting work, create an issue to discuss your planned changes.

2. Fork and Branch

# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/mailcard.git
cd mailcard

# Create a feature branch
git checkout -b feature/your-feature-name

3. Make Changes

  • Follow the coding standards
  • Add tests for new functionality
  • Update documentation as needed
  • Keep commits focused and atomic

4. Test Your Changes

# Run full test suite
cargo test --all-features

# Run benchmarks (if performance-related)
cargo bench

# Check formatting and linting
cargo fmt
cargo clippy

5. Submit Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub

🧪 Testing

Unit Tests

# Run all unit tests
cargo test

# Run specific test
cargo test test_smtp_connection

# Run tests with output
cargo test -- --nocapture

Integration Tests

# Run integration tests
cargo test --test integration

# Run specific integration test
cargo test --test integration -- test_smtp_flow

Benchmarks

# Run performance benchmarks
cargo bench

# Run specific benchmark
cargo bench smtp_throughput

📝 Documentation

Code Documentation

  • All public functions must have rustdoc comments
  • Include examples for complex APIs
  • Document error conditions and edge cases
/// Sends an email message via SMTP
/// 
/// # Arguments
/// 
/// * `message` - The email message to send
/// * `recipients` - List of recipient addresses
/// 
/// # Returns
/// 
/// Returns `Ok(())` if the message was sent successfully,
/// otherwise returns an `Err` with details about the failure.
/// 
/// # Examples
/// 
/// ```rust
/// let message = EmailMessage::new();
/// let recipients = vec!["user@example.com".to_string()];
/// send_email(message, recipients)?;
/// ```
pub fn send_email(message: EmailMessage, recipients: Vec<String>) -> Result<(), MailError> {
    // Implementation
}

Documentation Updates

  • Update README.md for user-facing changes
  • Add protocol documentation for new features
  • Update architecture diagrams for structural changes

🔍 Code Review Process

What We Look For

  • Correctness: Does the code work as intended?
  • Performance: Is it efficient and scalable?
  • Security: Does it follow security best practices?
  • Documentation: Is it well-documented?
  • Testing: Are there adequate tests?
  • Style: Does it follow our coding standards?

Review Guidelines

  • Be constructive and respectful
  • Focus on the code, not the author
  • Explain your reasoning clearly
  • Offer suggestions for improvement

🐛 Bug Reports

Reporting Bugs

Use the bug report template in .github/ISSUE_TEMPLATE/bug_report.md and include:

  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Rust version, etc.)
  • Relevant logs or error messages

Debugging Tips

  • Enable debug logging: RUST_LOG=debug
  • Use cargo run -- --help for configuration options
  • Check the metrics endpoint: GET /metrics

💡 Feature Requests

Proposing Features

  1. Check existing issues and discussions
  2. Create an issue with the feature request template
  3. Describe the problem you're solving
  4. Outline your proposed solution
  5. Consider implementation complexity

Feature Criteria

  • Aligns with project goals
  • Benefits the broader community
  • Has a clear implementation path
  • Maintains backward compatibility when possible

🔧 Performance Guidelines

Performance Considerations

  • Use async/await for I/O operations
  • Avoid unnecessary allocations
  • Profile critical paths with cargo flamegraph
  • Benchmark performance changes

Memory Management

  • Prefer stack allocation when possible
  • Use Vec::with_capacity for known sizes
  • Avoid copying large data structures
  • Consider Cow<str> for string handling

🛡️ Security Guidelines

Security Principles

  • Validate all input data
  • Use type-safe APIs
  • Follow principle of least privilege
  • Keep dependencies updated

Security Testing

  • Run cargo audit regularly
  • Test with malformed inputs
  • Verify authentication and authorization
  • Check for information disclosure

📚 Resources

Rust Resources

Email Protocol Resources

🤝 Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

  • Be respectful and considerate
  • Use inclusive language
  • Focus on constructive feedback
  • Help others learn and grow

Getting Help

  • Create an issue for bugs or questions
  • Join discussions in existing issues
  • Check the documentation first
  • Search existing issues before creating new ones

🎯 Contribution Areas

We're particularly interested in contributions to:

  • Protocol Implementations: Enhanced SMTP/IMAP/POP3 features
  • Security: DKIM, SPF, DMARC implementations
  • Performance: Optimization and profiling
  • Documentation: Guides, examples, and API docs
  • Testing: Test coverage and integration tests
  • Tooling: Development and debugging tools

📧 Contact

Thank you for contributing to MAIL-CARD! 🚀

⭐ If you find MAIL-CARD useful, please star the repository to help others discover it!