Contributing

Contributing

Thank you for your interest in contributing to the MQTT platform!

---

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Install prerequisites and verify the build:

git clone https://github.com/YOUR_USERNAME/mqtt-lib.git
cd mqtt-lib

# Rust 1.88+ and cargo-make are required
cargo install cargo-make

# Generate test certificates (needed for TLS tests)
./scripts/generate_test_certs.sh

cargo make ci-verify

---

Development Workflow

Create an Issue First

• Describe what you want to fix or add
• Wait for feedback from maintainers before starting large changes

Before Making Changes

1. Create a branch for your work:

   git checkout -b feature/my-feature

2. Make sure the baseline passes:

   cargo make ci-verify

While Developing

1. Run checks frequently:

   cargo check
   cargo clippy --all-targets --workspace -- -D warnings -W clippy::pedantic

2. Run relevant tests:

   cargo test --lib --bins  # Fast unit tests
   cargo test               # All tests

Before Submitting

1. Format code and run the pre-commit checks:

   cargo fmt
   cargo make pre-commit

2. Run full CI verification:

   cargo make ci-verify

3. Commit with a descriptive message (no prefixes, no period at end):

   git commit -m "add support for topic aliases"

---

Code Style

Rust Guidelines

• Follow Rust API Guidelines
• Use Result<T, E> for fallible operations
• Prefer &str over String when borrowing
• Use descriptive names over comments
• Use tracing for logging, not println!
• Keep functions focused and small

Error Handling

// Good: Specific error types
pub fn connect(&self, url: &str) -> Result<(), MqttError>

// Avoid: Generic errors
pub fn connect(&self, url: &str) -> Result<(), Box<dyn Error>>

Async Code

• Use Tokio for async runtime
• Prefer direct async/await over channels
• Use Arc<RwLock<T>> for shared state

---

Testing Requirements

New Features

• Add unit tests next to the code they cover
• Add integration tests in tests/ for end-to-end behavior
• Update existing tests if behavior changes

Bug Fixes

• Add a test that reproduces the bug
• Verify the fix makes the test pass

Testing Guidelines

• Use property-based tests (proptest) for protocol edge cases
• Network simulation is available via turmoil (feature-gated)
• Test both success and failure paths
• Mock external dependencies where practical

---

MQTT v5.0 Compliance

When implementing MQTT features:

• Reference the MQTT v5.0 specification
• Test against multiple brokers (Mosquitto, MQTTX, etc.)
• Ensure backward compatibility with v3.1.1

---

Pull Request Process

1. Title: Describe what the PR does

2. Description: Include:

   • What changes were made
   • Why the changes are needed
   • How to test the changes
   • The issue being fixed, if any

3. Checklist:

   • cargo make ci-verify passes
   • Tests added/updated
   • Documentation updated if needed

4. Review: Address feedback promptly

---

Release Process

Releases are managed by the maintainers, who:

1. Update the version in the relevant Cargo.toml
2. Update CHANGELOG.md
3. Run the full test suite: cargo make ci-verify
4. Create a git tag (v<version>)
5. Publish to crates.io (Docker images are built automatically from the tag)

---

Issue Reporting

Bug Reports

Include:

• Rust version (rustc --version)
• OS and version
• Steps to reproduce (a minimal reproducible example helps)
• Expected vs actual behavior
• Error messages/logs

Feature Requests

Include:

• Use case description
• Proposed solution (if any)
• Alternatives considered

---

Areas for Contribution

Good First Issues

Look for issues labeled good first issue on GitHub.

Documentation

• Improve wiki pages
• Add code examples
• Fix typos

Testing

• Add test coverage
• Property-based tests with proptest
• Network simulation with turmoil

Features

• Protocol enhancements
• New transport options
• Performance improvements

---

License

By contributing, you agree that your contributions will be licensed under the same license as the project (Apache 2.0 or MIT).

---

Questions?

• Open a GitHub issue for bugs or features
• Check existing issues before creating new ones
• Be respectful and constructive in discussions