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.
Before reporting an issue on the issue tracker, please check that it has not already been reported by searching for some related keywords.
Try to do one pull request per change.
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:
Addedfor new features.Changedfor changes in existing functionality.Deprecatedfor soon-to-be removed features.Removedfor now removed features.Fixedfor any bug fixes.Securityin case of vulnerabilities.
If the required subsection does not exist yet under Unreleased, create it!
This is no different than other Rust projects.
git clone https://github.com/mxsm/rocketmq-rust
cd rocketmq-rust
cargo test-
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
taploto formatCargo.tomlfiles across the repositorycargo install taplo-cli --locked taplo format -o align_entries=true **/Cargo.toml
- Production request headers use
RequestHeaderCodec, the only supported request-header derive. Register new headers in the typed registry and checked-in inventory. Preserve historicalcurrentCodec = "v3"records in the migration inventory. - A process entrypoint owns its runtime through
RuntimeOwner. Background work receives an injectedServiceContext/ChildServiceContextor a parentTaskGrouprather 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-releaseWhen 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 carriesErrororSharedErrorwithout 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::Resultfrom library or public business APIs. - Add or reuse one canonical
ErrorDescriptorentry before exposing a new public failure. Construct source-free failures withError::newand retain typed causes withError::caused_by. - Use
PublicErrorVieworDiagnosticViewfor 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
SharedErrorwhen several owners need the same canonical failure; do not clone or reconstruct an error fromDisplayoutput. - Select
CORE_INTERNAL_FAILUREonly for audited internal invariants, not ordinary business failures.
Run the error hygiene guard before opening a pull request:
python scripts/error_architecture_guard.pyOn Windows, the same guard is available through:
.\scripts\check-error-hygiene.ps1