# How to Contribute to the Pumpkin-MC/Pumpkin Project: A Complete Rust Guide

> Learn how to contribute to the Pumpkin-MC/Pumpkin project with this comprehensive Rust guide. Fork the repo, make changes, run tests, fix Clippy, and submit your PR.

- Repository: [Pumpkin MC/Pumpkin](https://github.com/Pumpkin-MC/Pumpkin)
- Tags: how-to-guide
- Published: 2026-07-23

---

**To contribute to the Pumpkin-MC/Pumpkin project, fork the repository, modify the appropriate crate within the Cargo workspace, verify all tests pass with `cargo test --all`, ensure zero Clippy warnings, and submit a pull request against the `master` branch.**

Pumpkin is a full-featured Minecraft server implementation written in Rust, organized as a Cargo workspace that separates distinct subsystems into logical crates. Understanding how to contribute to the Pumpkin-MC/Pumpkin project requires familiarity with this modular architecture, strict linting standards, and the collaborative workflow managed through continuous integration.

## Understanding the Pumpkin Workspace Architecture

The repository follows a **Cargo workspace** structure defined in the root [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml), grouping multiple crates that handle specific subsystems. When contributing, you must identify the correct crate for your changes to maintain clean separation of concerns.

| Subsystem | Crate | Key Source File(s) |
|-----------|-------|-------------------|
| **Core server & game loop** | `pumpkin` | [[`pumpkin/src/main.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/main.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin/src/main.rs) |
| **World handling** | `pumpkin-world` | [[`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-world/src/world.rs) |
| **Configuration** | `pumpkin-config` | [[`pumpkin-config/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/lib.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-config/src/lib.rs) |
| **Network protocol** | `pumpkin-protocol` | [[`pumpkin-protocol/src/serial/serializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/serializer.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-protocol/src/serial/serializer.rs) |
| **Plugin API** | `pumpkin-plugin-api` | [[`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-plugin-api/src/lib.rs) |
| **Inventory system** | `pumpkin-inventory` | [[`pumpkin-inventory/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-inventory/src/lib.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-inventory/src/lib.rs) |
| **Code generation** | `pumpkin-codegen` | [[`pumpkin-codegen/src/world_event.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-codegen/src/world_event.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-codegen/src/world_event.rs) |
| **Data formats** | `pumpkin-nbt` | [[`pumpkin-nbt/src/serializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/serializer.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-nbt/src/serializer.rs) |
| **Utilities** | `pumpkin-util` | [[`pumpkin-util/src/uuid.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-util/src/uuid.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-util/src/uuid.rs) |

Each crate maintains strict **Clippy** linting rules and comprehensive unit tests. Your contributions must preserve code quality across the entire workspace.

## Step-by-Step Contribution Workflow

Follow these ten steps to ensure your contribution meets the project's standards:

1. **Join the community.** Ask questions or request guidance on the official Discord server: https://discord.gg/wT8XjrjKkf.

2. **Fork and clone the repository.**

   ```bash
   git clone https://github.com/<your-username>/Pumpkin.git
   cd Pumpkin
   ```

3. **Install Rust.** Use the official installer at https://www.rust-lang.org/tools/install to ensure you have the latest stable toolchain.

4. **Run the test suite.** Verify the current codebase passes all tests before making changes:

   ```bash
   cargo test --all
   ```

5. **Create a descriptive branch.** Use clear naming conventions like `feature/async-chunk-loader` or `fix/protocol-serialization`.

6. **Make targeted changes.** Edit only the appropriate crate. For example, add new packets in `pumpkin-protocol`, world logic in `pumpkin-world`, or configuration fields in `pumpkin-config`.

7. **Add unit tests.** Place new tests in the crate's `tests/` directory to cover any public API changes.

8. **Run Clippy.** Enforce zero warnings with strict denial:

   ```bash
   cargo clippy --all-targets -- -D warnings
   ```

9. **Commit your changes.** Write concise commit titles and detailed descriptions following the guidelines in [[`CONTRIBUTING.md`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/CONTRIBUTING.md)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/CONTRIBUTING.md).

10. **Open a pull request.** Push your branch and submit a PR against `master`. If submitting via an automated bot, append `🤖🤖🤖` to the PR title for fast-track merging. CI will automatically run tests, Clippy checks, and benchmarks.

## Code Examples for Common Contributions

### Adding a New World Event

When extending world functionality in `pumpkin-codegen`, define your event structure and implement serialization logic:

```rust
// In pumpkin-codegen/src/world_event.rs
/// Fires when a player enters a custom dimension.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PlayerEnterDimension {
    pub player_uuid: Uuid,
    pub dimension_id: i32,
}

```

Include corresponding unit tests to validate round-trip serialization:

```rust
#[test]
fn serialize_deserialize() {
    let ev = PlayerEnterDimension {
        player_uuid: Uuid::new_v4(),
        dimension_id: 2,
    };
    let bytes = ev.serialize();
    let decoded = PlayerEnterDimension::deserialize(&bytes).unwrap();
    assert_eq!(ev, decoded);
}

```

### Extending the Packet Serializer

Protocol changes require updates to [`pumpkin-protocol/src/serial/serializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/serializer.rs):

```rust
// In pumpkin-protocol/src/serial/serializer.rs
impl Serializer {
    pub fn write_var_int(&mut self, value: i32) {
        // implementation follows the Minecraft var-int spec
    }
}

```

After modifying serialization code, run benchmarks to detect performance regressions:

```bash
cargo bench --bench packet_serialization

```

### Updating the Configuration Schema

New server settings belong in `pumpkin-config` with corresponding TOML definitions:

```toml

# In config/default.toml

[server]
max_players = 100          # new field, default 100

enable_rcon = true

```

Validate parsing logic with unit tests:

```rust
#[test]
fn parse_max_players() {
    let cfg = Config::load_str("[server]\nmax_players = 50").unwrap();
    assert_eq!(cfg.server.max_players, 50);
}

```

## Key Files Every Contributor Should Know

- **[[`README.md`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/README.md)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/README.md)** – Project overview, badge links, and quick-start instructions.
- **[[`CONTRIBUTING.md`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/CONTRIBUTING.md)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/CONTRIBUTING.md)** – Detailed coding standards, commit message formats, and CI expectations.
- **[[`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/Cargo.toml)** – Workspace definition listing all member crates and dependencies.
- **[[`pumpkin/src/main.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/main.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin/src/main.rs)** – Server entry point demonstrating initialization flow and subsystem integration.
- **[[`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-world/src/world.rs)** – Core world management logic frequently modified for terrain or entity updates.
- **[[`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-plugin-api/src/lib.rs)** – Public plugin API surface for adding new events and hooks.

## Summary

- **Join the community** at https://discord.gg/wT8XjrjKkf before starting major work.
- **Fork and clone** the repository, then install the latest stable Rust toolchain.
- **Identify the correct crate** for your changes using the workspace architecture table.
- **Maintain code quality** by running `cargo test --all` and `cargo clippy --all-targets -- -D warnings` with zero warnings.
- **Write tests** for all new public APIs and configuration options.
- **Submit PRs** against `master` with descriptive titles, adding `🤖🤖🤖` for automated contributions.

## Frequently Asked Questions

### What programming language does Pumpkin use?

Pumpkin is written entirely in **Rust**, leveraging the language's memory safety guarantees and concurrency model to build a high-performance Minecraft server. All contributions must compile with the latest stable Rust toolchain and pass the workspace's Clippy linting rules.

### How do I know which crate to modify?

Consult the workspace architecture table to map your feature to the correct subsystem. For example, packet serialization changes belong in `pumpkin-protocol`, while world generation logic belongs in `pumpkin-world`. When in doubt, ask in the Discord server before beginning work.

### What are the automated checks for pull requests?

Continuous integration automatically runs `cargo test --all`, `cargo clippy --all-targets -- -D warnings`, and benchmark suites on every PR. Your code must pass all checks and maintain or improve existing performance benchmarks before maintainers can merge.

### Does Pumpkin accept automated or AI-generated contributions?

Yes, automated contributions are accepted. If submitting via a bot or automated tool, append `🤖🤖🤖` to the PR title for fast-track merging. However, all code must still pass the full CI pipeline including tests and linting, regardless of its origin.