Skip to main content

Welcome Contributors

We’re excited that you want to contribute to boop network! This guide will help you get started with contributing code, documentation, and improvements.
First time contributing? Start by reading our Code of Conduct and License.

Getting Started

Prerequisites

Before contributing, make sure you have:

Development Environment

Running Services

Get familiar with Docker Setup

System Understanding

Read the System Architecture documentation

GitHub Account

Needed for submitting pull requests

Your First Contribution

1

Find an Issue

Browse GitHub Issues and look for issues labeled good first issue or help wanted.
2

Fork & Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/boop-network.git
cd boop-network
git remote add upstream https://github.com/boop-network/boop-network.git
3

Create Branch

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

Make Changes

Implement your changes following our coding standards
5

Test & Submit

Test your changes and submit a pull request

Types of Contributions

What: Fix existing bugs or issuesProcess:
  1. Reproduce the bug locally
  2. Write a test that demonstrates the bug
  3. Fix the bug
  4. Verify the test passes
  5. Submit a pull request
Branch naming: fix/issue-description
What: Add new functionality to boop networkProcess:
  1. Discuss the feature in an issue first
  2. Get approval from maintainers
  3. Write tests for the new feature
  4. Implement the feature
  5. Update documentation
  6. Submit a pull request
Branch naming: feature/feature-name
What: Improve or add documentationProcess:
  1. Identify documentation gaps
  2. Write clear, helpful content
  3. Test documentation examples
  4. Submit a pull request
Branch naming: docs/topic-name
What: Improve code quality without changing functionalityProcess:
  1. Ensure tests pass before starting
  2. Make incremental changes
  3. Verify tests still pass
  4. Submit a pull request
Branch naming: refactor/component-name

Coding Standards

Rust Code Standards

// Use rustfmt for formatting (runs automatically)
cargo fmt

// Follow Rust naming conventions
struct UserData {
    user_id: String,        // snake_case for fields
    created_at: DateTime,   // descriptive names
}

impl UserData {
    pub fn new(user_id: String) -> Self {  // snake_case for functions
        Self {
            user_id,
            created_at: Utc::now(),
        }
    }
}

// Use descriptive error handling
pub enum UserError {
    NotFound { user_id: String },
    InvalidData { reason: String },
    DatabaseError(sqlx::Error),
}

Testing Standards

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

    #[test]
    fn test_user_creation() {
        let user = UserData::new("test_user".to_string());
        assert_eq!(user.user_id, "test_user");
        assert!(user.created_at <= Utc::now());
    }

    #[tokio::test]
    async fn test_authentication_success() {
        let mock_data = create_mock_biometric_data();
        let context = create_test_context();

        let result = authenticate_user(&mock_data, &context).await;

        assert!(result.is_ok());
        assert!(result.unwrap().success);
    }
}
// tests/integration_test.rs
use boop_network::prelude::*;

#[tokio::test]
async fn test_full_authentication_flow() {
    // Start test services
    let test_env = TestEnvironment::new().await;

    // Register a user
    let user_id = test_env.register_user("test_user").await?;

    // Simulate authentication
    let auth_request = AuthRequest {
        user_id,
        context_type: ContextType::Payment { amount: 1000 },
        attributes: vec!["email".to_string()],
    };

    let result = test_env.authenticate(auth_request).await?;

    assert!(result.success);
    assert_eq!(result.attributes.len(), 1);

    test_env.cleanup().await;
}
# Run tests with coverage
cargo tarpaulin --out Html --output-dir coverage

# Requirements:
# - Unit tests: > 80% coverage
# - Integration tests for all public APIs
# - Error case testing
# - Performance regression tests

Commit Standards

We use Conventional Commits format:
# Features
feat: add palm vein quality scoring
feat(auth): implement multi-factor authentication

# Bug fixes
fix: resolve WebSocket connection timeout
fix(api): handle malformed authentication requests

# Documentation
docs: add API integration examples
docs(contrib): update contributing guidelines

# Refactoring
refactor: simplify user authentication logic
refactor(db): optimize database query performance

# Tests
test: add unit tests for biometric matching
test(e2e): add end-to-end authentication tests

# Chores
chore: update dependencies to latest versions
chore(ci): improve GitHub Actions workflow

Pull Request Process

Before Submitting

1

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy -- -D warnings

# Run all tests
cargo test --all
2

Integration Tests

# Run integration tests
cargo test --test '*'

# Test with Docker
cd docker/development
docker-compose up -d
./scripts/run-integration-tests.sh
3

Documentation

# Generate and check docs
cargo doc --no-deps --open

# Update README if needed
# Add examples for new features
4

Performance Check

# Run performance benchmarks
cargo bench

# Check for performance regressions

Pull Request Template

When creating a pull request, use this template:
## Description
Brief description of what this PR does and why.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing
- [ ] Performance testing

## Checklist:
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

Review Process

What happens:
  1. Automated checks run (CI/CD)
  2. Maintainers review your code
  3. Feedback is provided
  4. You address feedback
  5. PR is approved and merged
Review criteria:
  • Code quality and style
  • Test coverage
  • Documentation completeness
  • Security considerations
  • Performance implications
# Make requested changes
git add .
git commit -m "fix: address review feedback"
git push origin feature/your-branch

# If you need to squash commits before merge:
git rebase -i HEAD~3  # Interactive rebase for last 3 commits
git push --force-with-lease origin feature/your-branch

Development Guidelines

Security Considerations

Critical: Never commit secrets, API keys, or sensitive data. Use environment variables and .env.example files instead.
  • Never log raw biometric data
  • Always use MPC for biometric operations
  • Implement secure deletion of temporary data
  • Use proper encryption for data at rest
use serde::{Deserialize, Serialize};
use validator::{Validate, ValidationError};

#[derive(Debug, Deserialize, Validate)]
pub struct CreateUserRequest {
    #[validate(length(min = 1, max = 255))]
    pub user_id: String,

    #[validate(email)]
    pub email: Option<String>,

    #[validate(custom = "validate_biometric_data")]
    pub biometric_data: Vec<u8>,
}

fn validate_biometric_data(data: &[u8]) -> Result<(), ValidationError> {
    if data.is_empty() || data.len() > 10_000 {
        return Err(ValidationError::new("invalid_biometric_data"));
    }
    Ok(())
}
  • Validate API keys on every request
  • Use JWT tokens with proper expiration
  • Implement rate limiting
  • Log security events for auditing

Performance Guidelines

// Use prepared statements and connection pooling
pub struct DatabasePool {
    pool: sqlx::PgPool,
}

impl DatabasePool {
    pub async fn get_user(&self, user_id: &str) -> Result<User, DatabaseError> {
        let user = sqlx::query_as!(
            User,
            "SELECT * FROM users WHERE user_id = $1",
            user_id
        )
        .fetch_optional(&self.pool)
        .await?;

        user.ok_or(DatabaseError::UserNotFound)
    }
}

// Index frequently queried columns
// CREATE INDEX idx_users_user_id ON users(user_id);
// CREATE INDEX idx_auth_requests_created_at ON auth_requests(created_at);
use tokio::time::{timeout, Duration};

// Use timeouts for external calls
pub async fn call_external_service() -> Result<Response, ServiceError> {
    let future = external_service_call();

    match timeout(Duration::from_secs(30), future).await {
        Ok(result) => result,
        Err(_) => Err(ServiceError::Timeout),
    }
}

// Batch database operations when possible
pub async fn batch_insert_users(&self, users: Vec<User>) -> Result<(), DatabaseError> {
    let mut tx = self.pool.begin().await?;

    for user in users {
        sqlx::query!("INSERT INTO users (user_id, email) VALUES ($1, $2)")
            .bind(&user.user_id)
            .bind(&user.email)
            .execute(&mut *tx)
            .await?;
    }

    tx.commit().await?;
    Ok(())
}

Release Process

Maintainers Only: This section is for maintainers who handle releases.
We use Semantic Versioning:
  • Major (1.0.0): Breaking changes
  • Minor (0.1.0): New features, backwards compatible
  • Patch (0.0.1): Bug fixes, backwards compatible
  • All tests pass
  • Documentation updated
  • Changelog updated
  • Version numbers bumped
  • Security review completed
  • Performance benchmarks run
  • Release notes prepared

Getting Help


Thank you for contributing! Your contributions help make boop network better for everyone. Every contribution, no matter how small, is valuable and appreciated.