Skip to content

Latest commit

Β 

History

History
145 lines (106 loc) Β· 4.56 KB

CONTRIBUTING.md

File metadata and controls

145 lines (106 loc) Β· 4.56 KB

Contribution guidelines

First off, thank you for considering contributing to rocketmq-rust.

If your contribution is not straightforward, please first discuss the change you wish to make by creating a new issue before making the change.

Reporting issues

Before reporting an issue on the issue tracker, please check that it has not already been reported by searching for some related keywords.

Pull requests

Try to do one pull request per change.

Updating the changelog

Update the changes you have made in CHANGELOG file under the Unreleased section.

Add the changes of your pull request to one of the following subsections, depending on the types of changes defined by Keep a changelog:

  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for soon-to-be removed features.
  • Removed for now removed features.
  • Fixed for any bug fixes.
  • Security in case of vulnerabilities.

If the required subsection does not exist yet under Unreleased, create it!

Developing

Set up

This is no different than other Rust projects.

git clone https://github.com/mxsm/rocketmq-rust
cd rocketmq-rust
cargo test

Useful Commands

  • Build and run release version:

    cargo build --release && cargo run --release
  • Run Clippy:

    cargo clippy --all-targets --all-features --workspace
  • Run all tests:

    cargo test --all-features --workspace
  • Check to see if there are code formatting issues

    cargo fmt --all -- --check
  • Format the code in the project

    cargo fmt --all
  • Use taplo to format Cargo.toml files across the repository

    cargo install taplo-cli --locked
    taplo format -o align_entries=true **/Cargo.toml

Foundation safety and compatibility

  • Production request headers use RequestHeaderCodec, the only supported request-header derive. Register new headers in the typed registry and checked-in inventory. Preserve historical currentCodec = "v3" records in the migration inventory.
  • A process entrypoint owns its runtime through RuntimeOwner. Background work receives an injected ServiceContext/ChildServiceContext or a parent TaskGroup rather than creating another runtime or detached task.
  • Recoverable production failures use the owning typed error. Follow the error architecture below instead of adding unwrap, expect, or a string-only error path for protocol, I/O, configuration, or lifecycle failures.
  • Explain unsafe invariants with adjacent safety comments and relevant tests. Review changed runtime ownership without maintaining source identities or historical counts.

Before opening a pull request that changes these boundaries, run:

cargo test -p rocketmq-protocol --test request_header_codec_registry
python scripts/rust_hygiene_guard.py --scope core-release

Error architecture

When adding or changing an error that can cross crate, process, protocol, or CLI boundaries:

  • Prefer rocketmq_error::Result<T> in canonical library APIs. A component may expose a narrow result facade only when it carries Error or SharedError without losing descriptor identity, context, or typed sources.
  • Maintain one current error model; do not add compatibility aliases or versioned error facades.
  • Do not expose anyhow::Result from library or public business APIs.
  • Add or reuse one canonical ErrorDescriptor entry before exposing a new public failure. Construct source-free failures with Error::new and retain typed causes with Error::caused_by.
  • Use PublicErrorView or DiagnosticView for approved context fields and descriptor-owned projection primitives for remoting, gRPC, HTTP, and CLI responses.
  • Store only descriptor-approved bounded values in ErrorContext; represent sensitive details with typed presence fields rather than their raw values.
  • Preserve source chains with typed wrappers and #[source] instead of early stringification.
  • Use SharedError when several owners need the same canonical failure; do not clone or reconstruct an error from Display output.
  • Select CORE_INTERNAL_FAILURE only for audited internal invariants, not ordinary business failures.

Run the error hygiene guard before opening a pull request:

python scripts/error_architecture_guard.py

On Windows, the same guard is available through:

.\scripts\check-error-hygiene.ps1