Contributing

Contributions are welcome. Start with the contributor guidelines, which cover commit sign-off (DCO), employer contributions, and how reviews work.

Every PR needs a release-note block in its description (or NONE for changes with no user-facing impact) — CI validates this automatically and comments on the PR if the block is missing or malformed.

Adding a beta feature

When a new capability is not yet ready for all users, gate it behind a Cargo feature and a runtime flag. The full lifecycle:

private branch / draft PR
       ↓
Cargo feature: beta-<name>    ← compiled in, invisible by default
       ↓
mur beta enable <name>        ← user opts into the public beta
       ↓
graduate: remove is_enabled() check, remove #[cfg] guards
       ↓
(optional) remove Cargo feature if it is now core behaviour

Step 1 — Add a Cargo feature

In crates/murmur-cli/Cargo.toml:

[features]
default = []
beta = []
beta-blueprint = ["beta"]   # ← add one line per new feature

Step 2 — Register in the feature list

In crates/murmur-cli/src/beta.rs, add a block to compiled_beta_features():

#[cfg(feature = "beta-blueprint")]
features.push(BetaFeature {
    name: "blueprint",
    description: "Blueprint file support in taskflow stage slots (preview)",
});

Step 3 — Gate the code

Wrap any new commands, handlers, or registrations in #[cfg(feature = "beta-blueprint")]. For runtime visibility, also check the enabled flag before registering subcommands in main.rs:

#[cfg(feature = "beta-blueprint")]
{
    let beta_cfg = load_mur_config().map(|c| c.beta).unwrap_or_default();
    if beta_cfg.is_enabled("blueprint") {
        // register the subcommand
    }
}

Step 4 — Graduate to stable

When the feature is ready for all users:

1. Remove the #[cfg(feature = "beta-blueprint")] guards from main.rs and the command file.
2. Remove the is_enabled("blueprint") check — always register the subcommand.
3. Remove the entry from compiled_beta_features() in beta.rs.
4. Optionally remove the beta-blueprint Cargo feature (keeping it as a no-op is harmless).

Running tests

Run the unit tests plus the integration suites for the area you touched before submitting:

cargo test --workspace --lib --bins     # unit tests across all crates
cargo test -p murmur-cli --test build   # one integration suite (see crates/murmur-cli/tests/)

Every PR that changes behavior must include tests — see the testing section of the contributor guidelines for where tests go and how much coverage is expected. A few integration tests are marked #[ignore] because they depend on a sibling default-artifacts checkout; they only run with cargo test -- --ignored.