Contributing to HDDS

Thank you for your interest in contributing to HDDS! This guide explains how to get started.

Ways to Contribute

Report Issues

Found a bug or have a feature request?

1. Check existing issues first
2. If not found, create a new issue
3. Use the appropriate template:
   • Bug Report: For bugs and unexpected behavior
   • Feature Request: For new functionality
   • Documentation: For doc improvements

Submit Code

Ready to contribute code?

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Improve Documentation

Documentation contributions are always welcome:

• Fix typos and clarify wording
• Add examples and tutorials
• Translate to other languages
• Improve API documentation

Development Setup

Prerequisites

# Rust (1.75+)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable

# Development tools
cargo install cargo-watch cargo-nextest cargo-llvm-cov

Clone and Build

git clone https://git.hdds.io/hdds/hdds.git
cd hdds

# Build all components
cargo build --workspace

# Run tests
cargo nextest run

# Run with debug logging
RUST_LOG=hdds=debug cargo run --example hello_world

Project Structure

hdds/
├── hdds/                 # Core DDS library
│   ├── src/
│   │   ├── domain/       # Domain participant
│   │   ├── transport/    # Network transports
│   │   ├── discovery/    # SPDP/SEDP
│   │   ├── qos/          # QoS policies
│   │   └── rtps/         # RTPS protocol
│   └── tests/
├── hdds-gen/             # Code generator
├── hdds-derive/          # Proc macros
├── tools/
│   ├── hdds-viewer/      # Traffic analyzer
│   └── hdds-studio/      # Visual editor
└── examples/             # Usage examples

Code Guidelines

Rust Style

Follow Rust idioms and conventions:

// Good: Use Result for fallible operations
pub fn create_topic(&self, name: &str) -> Result<Topic, hdds::Error> {
    // ...
}

// Good: Use fluent builder pattern
let writer = topic
    .writer()
    .qos(QoS::reliable().keep_last(10))
    .build()?;

// Good: Document public APIs
/// Creates a new DataWriter for the specified topic.
///
/// # Errors
///
/// Returns `hdds::Error::TopicNotFound` if the topic doesn't exist.
pub fn create_datawriter(&self, topic: &Topic) -> Result<DataWriter, hdds::Error> {
    // ...
}

Formatting

# Format code
cargo fmt

# Check formatting
cargo fmt --check

Linting

# Run clippy
cargo clippy --workspace --all-targets -- -D warnings

# With pedantic lints (recommended for new code)
cargo clippy --workspace -- -W clippy::pedantic

Testing

# Run all tests
cargo nextest run

# Run specific test
cargo nextest run test_reliable_delivery

# Run with coverage
cargo llvm-cov nextest --workspace

# Integration tests
cargo test --test integration

# Doc integration tests (validates documentation accuracy)
cargo test --test doc_integration

Doc-as-Contract Tests

HDDS includes Doc Integration Tests that validate documented API patterns work correctly. If a test fails, it indicates the documentation may be misleading.

Located at crates/hdds/tests/doc_integration.rs:

Test	Validates
uc01_basic_pubsub	Basic pub/sub with create_writer/create_reader, write/take
uc02_qos_reliable_keeplast	QoS builder: QoS::reliable().keep_last(10)
uc03_publisher_subscriber	Publisher/Subscriber entities with create_publisher/create_subscriber
uc04_coherent_changes	Coherent changes: begin_coherent_changes, begin_access, nested error handling
uc05_qos_best_effort	QoS::best_effort() creates non-reliable QoS
uc06_partition_qos	QoS::default().partition_single("name") sets partition
uc07_durability_qos	volatile() vs transient_local() durability
uc08_content_filtered_topic	create_content_filtered_topic() with SQL-like filters
uc09_filter_expression_syntax	Filter operators: >, <, AND, OR, NOT, LIKE

Purpose: Every documented API pattern has a corresponding test. When updating documentation, ensure corresponding tests exist. When tests fail, documentation must be corrected.

// Example: UC-04 validates coherent changes
#[test]
fn uc04_coherent_changes() {
    let publisher = participant.create_publisher(QoS::default())?;

    // Documented: begin_coherent_changes() starts coherent set
    publisher.begin_coherent_changes()?;

    // Documented: nested calls should fail
    assert!(publisher.begin_coherent_changes().is_err());

    // Documented: end_coherent_changes() commits
    publisher.end_coherent_changes()?;
}

Pull Request Process

Before Submitting

1. Ensure tests pass:

   cargo nextest run
   cargo clippy --workspace -- -D warnings
   cargo fmt --check

2. Add tests for new functionality

3. Update documentation if needed

4. Write a clear commit message:

   feat(transport): add shared memory transport
   
   Implements zero-copy shared memory transport for same-host
   communication. Supports automatic fallback to UDP.
   
   Closes #123

Commit Message Format

Use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Formatting, no code change
• refactor: Code change, no new feature or fix
• perf: Performance improvement
• test: Adding tests
• chore: Build process or tooling

PR Review Process

1. Automated checks run on all PRs:

   • Build and test on Linux, macOS, Windows
   • Clippy lints
   • Format check
   • Security audit

2. Code review by maintainers:

   • Architecture and design
   • Code quality
   • Test coverage
   • Documentation

3. Approval and merge:

   • At least one maintainer approval required
   • All checks must pass
   • Squash merge preferred

Adding New Features

Proposing Changes

For significant changes:

1. Open an issue describing the proposal
2. Discuss with maintainers
3. Get approval before implementing

Feature Branches

# Create feature branch
git checkout -b feat/shared-memory-transport

# Make changes and commit
git add .
git commit -m "feat(transport): implement shared memory"

# Push and create PR
git push origin feat/shared-memory-transport

Example: Adding a New QoS Policy

1. Define the policy in hdds/src/qos/mod.rs:

#[derive(Clone, Debug, Default)]
pub struct NewPolicy {
    pub setting: bool,
}

2. Add to QoS builders:

impl DataWriterQos {
    pub fn new_policy(mut self, policy: NewPolicy) -> Self {
        self.new_policy = policy;
        self
    }
}

3. Implement wire format in hdds/src/rtps/parameter.rs

4. Add tests:

#[test]
fn test_new_policy() {
    let qos = QoS::reliable().new_policy(true);
    assert!(qos.new_policy);
}

5. Update documentation

Documentation Contributions

Building Docs

cd docs
npm install
npm run start  # Local preview
npm run build  # Production build

Doc Structure

docs/
├── getting-started/     # Tutorials
├── guides/              # How-to guides
├── concepts/            # Explanations
├── reference/           # API reference
└── tools/               # Tool documentation

Writing Style

• Use clear, concise language
• Include code examples
• Add diagrams where helpful
• Test all code snippets

Release Process

Versioning

HDDS follows Semantic Versioning:

• Major (1.x.x): Breaking changes
• Minor (x.1.x): New features, backwards compatible
• Patch (x.x.1): Bug fixes

Release Checklist

1. Update CHANGELOG.md
2. Update version in Cargo.toml
3. Create release tag
4. Build and publish crates
5. Update documentation

Getting Help

Questions

• Contact

Real-Time Chat

Join our Discord server for:

• Development discussions
• Quick questions
• Community support

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• Annual contributor spotlight

Thank you for contributing to HDDS!