# What Is the Role of the `main` Branch in Pumpkin‑MC/Pumpkin

> Discover the role of the main branch in Pumpkin-MC/Pumpkin. It's the stable integration line, consolidating vetted code and configurations for the core engine, protocol handlers, and plugin API.

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

---

**The `main` branch serves as the canonical integration line and stable baseline for the Pumpkin‑MC Pumpkin Minecraft server implementation, consolidating the latest vetted code, CI configurations, and multi‑crate workspace definition that powers the core engine, protocol handlers, and plugin API.**

The `main` branch in the **Pumpkin‑MC/Pumpkin** repository represents the primary development trunk for this Rust‑based Minecraft server implementation. As a multi‑crate workspace, this branch aggregates the server core, network protocol layers, NBT utilities, and plugin infrastructure into a single, reproducible baseline. Understanding the specific role of the `main` branch is essential for developers contributing to the codebase, deploying production builds, or integrating Pumpkin’s libraries into downstream Rust projects.

## Stable Integration and Release Baseline

The `main` branch functions as the **central integration point** where all feature branches, bug fixes, and refactors converge after code review. According to the repository structure, this branch contains the continuous integration pipeline defined in [[`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/.github/workflows/rust.yml), which executes on every push to ensure the codebase remains buildable and testable.

This branch also acts as the **release baseline** for the project. Official crate releases published to crates.io are cut directly from `main`, with version tags such as `v0.1.0` created on top of the commit history in this branch. This guarantees that any tagged release corresponds to a specific, tested state of the `main` branch.

## Multi‑Crate Workspace Architecture

Pumpkin‑MC organizes its codebase as a Cargo workspace, and the `main` branch hosts the root [[`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/Cargo.toml) that orchestrates the following member crates:

- **`pumpkin-world`** – Core server‑side world handling, including chunk management, Anvil format I/O, and tick scheduling, defined in [[`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).
- **`pumpkin-protocol`** – Network serialization and deserialization logic for Minecraft protocol packets, located in [[`pumpkin-protocol/src/packet.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-protocol/src/packet.rs).
- **`pumpkin-nbt`** – Utilities for reading, writing, and compressing NBT (Named Binary Tag) structures, exposed in [[`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-nbt/src/lib.rs).
- **`pumpkin-plugin-api`** – Public API surface for third‑party plugins, providing events, permissions, and logging facilities from [[`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).
- **`pumpkin-codegen`** – Build‑time code generation for packet mappings and sound identifiers, implemented in [[`pumpkin-codegen/src/main.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-codegen/src/main.rs)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/pumpkin-codegen/src/main.rs).

Because these crates are version‑aligned in `main`, developers can depend on this branch with confidence that all internal APIs remain compatible.

## Documentation and Dependency Anchor

Beyond source code, the `main` branch hosts the project’s canonical documentation. The [[`README.md`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/README.md)](https://github.com/Pumpkin-MC/Pumpkin/blob/master/README.md) and contribution guidelines live here, ensuring that users cloning the repository receive the most current setup instructions without switching branches.

Downstream projects and plugins reference the `main` branch when they require the latest stable API surface. By targeting this branch, external crates ensure compatibility with the most recent changes to the `pumpkin-plugin-api` and core libraries.

## Building and Depending on the `main` Branch

Developers interact with the `main` branch to compile the server or integrate specific crates into their own Rust projects.

### Building the Server from Source

To compile the latest stable code from the `main` branch:

```bash

# Clone the repository (defaults to the main branch)

git clone https://github.com/Pumpkin-MC/Pumpkin.git
cd Pumpkin

# Build the entire workspace in release mode

cargo build --release

```

This command processes the workspace [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) from the `main` branch, ensuring all five member crates compile together with compatible versions.

### Adding Pumpkin as a Git Dependency

To depend on the latest `main` branch code in another Rust project:

```toml
[dependencies]
pumpkin = { git = "https://github.com/Pumpkin-MC/Pumpkin.git", branch = "main" }

```

Specifying `branch = "main"` pins your project to the most recent vetted commit, providing access to bleeding‑edge features before they appear in a crates.io release.

### Using the Plugin API

The `main` branch exposes the plugin system through `pumpkin-plugin-api`. The following example registers a server tick event listener:

```rust
use pumpkin_plugin_api::events::server::ServerTickStart;
use pumpkin_plugin_api::scheduler::Scheduler;

fn register_tick_listener(scheduler: &mut Scheduler) {
    scheduler.register_event::<ServerTickStart>(|event| {
        println!("Server tick {} started", event.tick);
    });
}

```

This code compiles against the `pumpkin-plugin-api` crate as found in the `main` branch.

## Summary

- The `main` branch acts as the **canonical integration line** for all Pumpkin‑MC development, enforced by the CI pipeline in [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml).
- It serves as the **release baseline**, where version tags are created and official crates.io releases originate.
- The branch contains the **workspace root** ([`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml)) that coordinates the five core crates: `pumpkin-world`, `pumpkin-protocol`, `pumpkin-nbt`, `pumpkin-plugin-api`, and `pumpkin-codegen`.
- Developers build from `main` using standard Cargo commands, and downstream projects can depend on it via Git to access the latest API features.

## Frequently Asked Questions

### How does the `main` branch differ from release tags in Pumpkin‑MC/Pumpkin?

The `main` branch represents the rolling, latest stable state of development, while release tags (e.g., `v0.1.0`) mark specific immutable commits on `main` that correspond to published crates.io versions. Tags provide fixed reference points for reproducible builds, whereas `main` continuously receives new commits.

### Is it safe to deploy a production server from the `main` branch?

While the `main` branch is configured to pass all CI checks defined in [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml) before merging, production deployments typically should target a specific release tag cut from `main` rather than the moving tip. This ensures you deploy a version that has undergone additional release testing and versioning.

### How do I target the `main` branch in my Cargo.toml dependencies?

Specify the Git URL and branch name in your dependency declaration:

```toml
pumpkin-plugin-api = { git = "https://github.com/Pumpkin-MC/Pumpkin.git", branch = "main" }

```

This instructs Cargo to fetch the crate from the latest commit on `main`, ensuring you have access to the most recent API changes in [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs).

### What triggers the CI pipeline on the `main` branch?

The workflow file [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml) executes on every push to `main` and on pull requests targeting the branch. This automated process validates that changes to critical files like [`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs) or [`pumpkin-protocol/src/packet.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs) do not break the build or violate project standards.