# How to Understand the Pumpkin-MC/Pumpkin Versioning Scheme

> Understand Pumpkin MC/Pumpkin versioning. Learn how its SemVer format with dev tags and build metadata traces every binary to its exact GitHub Actions CI build.

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

---

**Pumpkin-MC/Pumpkin uses a Semantic Versioning (SemVer) format augmented with a `-dev` pre‑release tag and `+<run>.<job>` build metadata to trace every binary back to its exact GitHub Actions CI build.**

The Pumpkin Minecraft server—an open‑source Rust implementation hosted at Pumpkin-MC/Pumpkin—encodes its development status and build provenance directly into its version string. Understanding this versioning scheme allows developers to pinpoint which CI pipeline produced a binary and ensures consistent compatibility across the workspace’s multiple crates.

## The Anatomy of a Pumpkin Version String

Pumpkin version strings follow the pattern `MAJOR.MINOR.PATCH-dev+RUN.JOB`, as seen in the current workspace definition:

```

0.1.0-dev+26.2

```

This format breaks down into **three distinct informational layers**: the SemVer core, the pre‑release label, and the CI‑generated build metadata.

### Major, Minor, and Patch Components

The foundation follows strict **Semantic Versioning** rules:

- **Major (`0`)** – Pumpkin remains pre‑1.0, indicating the API is not yet stable.
- **Minor (`1`)** – Incremented for significant feature sets or milestones.
- **Patch (`0`)** – Currently at zero because bug fixes are rolled into development builds rather than distinct patch releases.

These numbers are defined in the workspace root’s [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) and shared across all crates in the repository.

### The `-dev` Pre‑Release Label

The **`-dev`** suffix signals that the artifact is a development build, not an official stable release. According to the [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) configuration and project documentation, this label appears on every automated build produced by the CI pipeline. When Pumpkin eventually publishes a stable release, this suffix will be removed and the version will bump to the next appropriate SemVer component (e.g., `0.2.0` or `1.0.0`).

### Build Metadata: `+<run>.<job>`

The **`+26.2`** segment provides **traceability** without affecting SemVer precedence ordering:

- **`26`** – The GitHub Actions **run number** for the workflow that built the binary.
- **`2`** – The **matrix job index**, indicating this was job 2 of N in a multi‑target build matrix.

This metadata is injected during the CI process defined in [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml), allowing developers to correlate any binary with its exact origin in the GitHub Actions logs.

## Workspace‑Wide Version Inheritance

All crates inside the Pumpkin workspace inherit the single version defined in the `[workspace.package]` section of the root [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml). This includes `pumpkin`, `pumpkin-world`, `pumpkin-nbt`, and `pumpkin-codegen`.

Because the version is defined once at the workspace level, every published crate carries an identical version string. This eliminates version drift and ensures that `0.1.0-dev+26.2` refers to the same commit across the entire codebase, from the core server to the NBT manipulation utilities.

## Accessing Version Information Programmatically

Developers can extract the version string at compile time or runtime using standard Rust patterns.

### Runtime Version Retrieval

Use the `env!` macro to embed the compiled version directly into your binary:

```rust
/// Returns the Pumpkin version string compiled into the binary.
pub fn pumpkin_version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

// Example output:
// println!("Pumpkin version: {}", pumpkin_version());
// → Pumpkin version: 0.1.0-dev+26.2

```

### Parsing with the `semver` Crate

For structured access to individual components, parse the version using the `semver` crate:

```rust
use semver::Version;

fn parse_version() -> Result<Version, semver::Error> {
    Version::parse(env!("CARGO_PKG_VERSION"))
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let v = parse_version()?;
    println!("Major: {}", v.major);
    println!("Minor: {}", v.minor);
    println!("Patch: {}", v.patch);
    println!("Pre‑release: {:?}", v.pre);
    println!("Build metadata: {:?}", v.build);
    Ok(())
}

```

This approach separates the **pre‑release identifier** (`dev`) from the **build metadata** (`26.2`), making it easy to filter development builds in deployment scripts.

### CI Pipeline Integration

In GitHub Actions workflows, extract the version for logging or artifact naming:

```bash

# In .github/workflows/rust.yml

VERSION=$(cargo metadata --format-version 1 | jq -r '.packages[0].version')
echo "Built Pumpkin version $VERSION"

# → Built Pumpkin version 0.1.0-dev+26.2

```

## Key Files Controlling Version Definitions

| File | Purpose |
|------|---------|
| [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) | Defines the workspace‑level version (`0.1.0-dev+26.2`) in the `[workspace.package]` section. |
| [`pumpkin-codegen/Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-codegen/Cargo.toml) | Demonstrates version inheritance; references `version.workspace = true` to sync with the root. |
| [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml) | Injects the run number and matrix index into the build metadata during CI execution. |
| [`README.md`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/README.md) | Documents the project’s pre‑1.0 status, contextualizing the `-dev` suffix usage. |

## Summary

- **Pumpkin-MC/Pumpkin** adheres to **SemVer** with the format `MAJOR.MINOR.PATCH-dev+RUN.JOB`.
- The **`-dev`** pre‑release tag marks builds as development artifacts, not stable releases.
- **Build metadata** (`+26.2`) encodes the GitHub Actions run number and job index for complete traceability.
- The version is defined once in the workspace root [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) and inherited by all sub‑crates.
- Use `env!("CARGO_PKG_VERSION")` in Rust to access the version string at runtime.

## Frequently Asked Questions

### What does the `-dev` suffix indicate in Pumpkin versions?

The **`-dev`** suffix is a SemVer pre‑release identifier that signals the binary was built from a development branch rather than a tagged release. It appears in every CI artifact produced before the project reaches 1.0.0 stable status. When Pumpkin makes an official release, this suffix is removed.

### How can I determine which CI build produced a specific Pumpkin binary?

Examine the **build metadata** following the `+` sign. The first number is the GitHub Actions run ID, and the second is the matrix job index. For example, `+26.2` indicates run 26, job 2. You can cross‑reference this with the Actions tab in the Pumpkin‑MC/Pumpkin repository to find the exact commit and logs.

### Do all crates in the Pumpkin workspace share the same version?

Yes. All crates—including `pumpkin`, `pumpkin-world`, and `pumpkin-nbt`—reference `version.workspace = true` in their individual [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) files. This ensures that when the root [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) declares `0.1.0-dev+26.2`, every crate in the workspace reports that identical version string.

### When will Pumpkin version 1.0.0 be released?

The project currently maintains a **major version of 0**, indicating active development toward a stable API surface. Version 1.0.0 will be tagged only after the core Minecraft server implementation reaches API stability and the `-dev` pre‑release label is retired. Until then, rely on the build metadata to distinguish between development snapshots.