Contributing Guidelines

​

Getting Started

​

Ways to Contribute

​

Reporting Bugs

1. Search existing issues first to avoid duplicates
2. Open a new issue if none exists
3. Provide clear details:
   • Steps to reproduce the bug
   • Expected vs. actual behavior
   • Server version and configuration
   • Relevant logs or error messages
   • Screenshots or recordings if applicable

​

Suggesting Features

1. Open an issue on the tracker
2. Describe the feature in detail:
   • What problem does it solve?
   • How should it work?
   • What are the benefits?
   • Potential implementation considerations

​

Submitting Pull Requests

1. Fork the repository on GitHub
2. Install Rust from rust-lang.org
3. Make your changes on your local fork
4. Test thoroughly (see requirements below)
5. Create a pull request to the main repository

​

Pull Request Requirements

​

Basic Requirements

​

Clear Title and Description

• What was changed?
• Why were these changes necessary?
• What is the impact of this change?
• Are there any known issues or limitations?
• Link to related issues or discussions

​

No Clippy Warnings

cargo clippy --all-targets

• all - All standard Clippy lints
• nursery - Experimental lints
• pedantic - Opinionated lints
• cargo - Cargo-specific lints

• dbg_macro - Prevent debug macros in production
• print_stdout / print_stderr - Use proper logging
• use_self - Enforce Self usage
• And many more (see Cargo.toml)

​

Passing Unit Tests

cargo test

​

Best Practices

​

Writing Unit Tests

1. Write tests to prevent future regressions
2. Test edge cases and error conditions
3. Follow Rust testing conventions

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

    #[test]
    fn test_feature_works() {
        // Arrange
        let input = setup_test_data();
        
        // Act
        let result = your_function(input);
        
        // Assert
        assert_eq!(result, expected);
    }
}

​

Benchmarking

1. Add benchmarks using Criterion
2. Run before and after your changes
3. Document performance impact in PR description

use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn benchmark_function(c: &mut Criterion) {
    c.bench_function("my_function", |b| {
        b.iter(|| my_function(black_box(input)))
    });
}

criterion_group!(benches, benchmark_function);
criterion_main!(benches);

cargo bench

​

Clear Commit Messages

# Good
git commit -m "Add chunk caching to reduce disk I/O"
git commit -m "Fix off-by-one error in chunk coordinate calculation"

# Bad
git commit -m "Fix bug"
git commit -m "Update code"

• First line: Brief summary (50 chars or less)
• Blank line
• Detailed explanation: Why the change was made, context, etc.

​

Code Style

1. Follow Rust conventions: Use cargo fmt to format code
2. Meaningful names: Use clear, descriptive variable and function names
3. Documentation: Add doc comments for public APIs
4. Consistency: Match existing code style in the area you’re modifying

cargo fmt

​

Documentation

1. Update relevant documentation at pumpkinmc.org
2. Add doc comments to public APIs:
   /// Loads a chunk from disk or generates it if not found.
   ///
   /// # Arguments
   /// * `pos` - The chunk position to load
   ///
   /// # Returns
   /// The loaded or generated chunk data
   pub async fn load_chunk(&self, pos: Vector2<i32>) -> Result<ChunkData> {
       // ...
   }
   
3. Update the changelog if applicable

​

Working with Tokio and Rayon

​

Critical Rules

1. Use Rayon’s thread pool:
   • rayon::spawn
   • Parallel iterators (par_iter)
   • Other Rayon primitives
2. Transfer data asynchronously:
   • Use tokio::sync::mpsc channels
   • Never block waiting for Rayon results

​

Example: Correct Pattern

use tokio::sync::mpsc;

// Create channel for communication
let (tx, mut rx) = mpsc::channel(100);

// Spawn CPU-intensive work on Rayon
rayon::spawn(move || {
    let result = expensive_computation();
    // Send result through channel (non-blocking)
    tx.blocking_send(result).ok();
});

// Receive results on Tokio runtime (async)
while let Some(result) = rx.recv().await {
    // Process result asynchronously
    process(result).await;
}

​

What NOT to Do

// ❌ WRONG: Blocking Tokio runtime
let result = rayon::spawn(|| expensive_computation()).join();

// ❌ WRONG: Blocking on async from Rayon
rayon::spawn(|| {
    tokio::runtime::Runtime::new()
        .unwrap()
        .block_on(async_fn())
});

// ✅ CORRECT: Use channels
let (tx, rx) = mpsc::channel(1);
rayon::spawn(move || {
    tx.blocking_send(expensive_computation()).ok();
});
let result = rx.recv().await;

​

Coding Standards

​

Edition and Version

• Rust Edition: 2024
• Minimum Rust Version: 1.89
• Resolver: Version 3

​

Denied Lints

• dbg_macro - Use proper logging instead
• print_stdout / print_stderr - Use tracing crate
• redundant_clone - Optimize away unnecessary clones
• needless_pass_by_ref_mut - Don’t take &mut when not needed
• use_self - Use Self instead of explicit type names

​

Allowed Lints

• cast_precision_loss - Floating point casts are common
• missing_panics_doc - Not all panics need documentation
• missing_errors_doc - Not all errors need documentation
• module_name_repetitions - Sometimes necessary for clarity

​

Development Helpers

​

Typo Detection

# Install
cargo install typos-cli

# Check for typos
typos

# Auto-fix typos
typos --write-changes

​

Pre-commit Checks

# Format code
cargo fmt

# Check for issues
cargo clippy --all-targets

# Run tests
cargo test

# Check for typos
typos

#!/bin/sh
# .git/hooks/pre-commit
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo test

​

Communication

• Comment on existing issues to share thoughts and feedback
• Ask questions in issues or on Discord
• Reach out to maintainers if you need assistance
• Be respectful and follow our Code of Conduct

​

Getting Help

• Discord: discord.gg/pumpkinmc
• Documentation: pumpkinmc.org
• Issue Tracker: GitHub Issues

​

Release Cycle

• Active development toward 1.0.0 release
• See 1.0.0 milestone
• Breaking changes may occur before 1.0.0

​

Recognition

• GitHub contributors list
• Release notes (for significant contributions)
• Discord community highlights

​

Next Steps

• System Architecture - Understand the codebase
• Building from Source - Set up your environment
• Quick Start - Run Pumpkin locally