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

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/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/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/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/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/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/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/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/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:

# 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 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:

[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:

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.
• 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) 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 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:

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.

What triggers the CI pipeline on the main branch?

The workflow file .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 or pumpkin-protocol/src/packet.rs do not break the build or violate project standards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}