Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (141 loc) · 5.64 KB

CONTRIBUTING.md

File metadata and controls

203 lines (141 loc) · 5.64 KB
Raw

Contributing to lib3mf_rust

Thank you for your interest in contributing to lib3mf_rust! This document provides guidelines for contributing to the project.

Code of Conduct

This project follows the Rust Code of Conduct. Please be respectful and constructive in all interactions.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR_USERNAME/lib3mf_rust.git
  3. Create a new branch: git checkout -b feature/your-feature-name
  4. Make your changes
  5. Test your changes
  6. Submit a pull request

Development Setup

Prerequisites

  • Rust 1.70 or later
  • Git

Building the Project

cargo build

Running Tests

# Run all tests
cargo test

# Run conformance tests
cargo test --test conformance_tests summary -- --ignored --nocapture

# Run specific test suite
cargo test --test conformance_tests suite3_core -- --nocapture

Running the Linter

cargo clippy -- -D warnings

Running Benchmarks

cargo bench

Code Style and Conventions

General Rust Style

  • Follow standard Rust conventions (use rustfmt)
  • Use meaningful variable names that reflect 3MF terminology
  • Prefer explicit types over type inference when it improves clarity
  • NO unsafe code allowed - forbidden at crate level with #![forbid(unsafe_code)]

Error Handling

  • Use Result<T, Error> for all fallible operations
  • Return descriptive errors using the Error enum defined in error.rs
  • Use thiserror for custom error types
  • Include context in error messages (e.g., file paths, element names)

Testing Practices

  1. Unit tests: Test individual functions and modules in the same file using #[cfg(test)]
  2. Integration tests: Test complete workflows in tests/ directory
  3. Conformance tests: Official 3MF Consortium test suites
  4. Examples: Working code in examples/ that demonstrates features
  5. Always run clippy before committing: cargo clippy -- -D warnings

Documentation

  • Add doc comments (///) for all public APIs
  • Include usage examples in doc comments where helpful
  • Keep README.md updated with new features
  • Document complex algorithms with inline comments

Naming Conventions

  • Use 3MF specification terminology (e.g., objectid, pid, requiredextensions)
  • Follow Rust naming: snake_case for functions/variables, PascalCase for types
  • Struct field names match 3MF XML attribute names when possible
  • Constants use UPPER_SNAKE_CASE

Pull Request Guidelines

Before Submitting

  1. Run all tests: Ensure cargo test passes
  2. Run clippy: Fix all warnings with cargo clippy -- -D warnings
  3. Format code: Run cargo fmt
  4. Update documentation: If you add features, update README.md and relevant docs
  5. Add examples: For new features, add examples in examples/
  6. Update CHANGELOG.md: Add your changes under "Unreleased"

Pull Request Process

  1. Ensure your PR has a clear title and description
  2. Reference any related issues
  3. Include test results if applicable
  4. For user-facing changes, update documentation
  5. Add benchmark results for performance-sensitive changes
  6. Wait for CI checks to pass
  7. Address any review feedback

Commit Messages

  • Write clear, concise commit messages
  • Use the imperative mood ("Add feature" not "Added feature")
  • First line should be 50 characters or less
  • Include more details in the body if needed

Example:

Add support for displacement extension

- Implement displacement map parsing
- Add displacement coordinate groups
- Update conformance tests

Adding New Features

Extension Support

When adding support for a new 3MF extension:

  1. Add types to src/model.rs
  2. Implement parsing in src/parser.rs
  3. Add validation in src/validator.rs
  4. Create integration tests
  5. Update documentation in README.md
  6. Add conformance tests if available
  7. Add examples demonstrating the feature

Performance Considerations

  • Parsing should scale linearly with file size
  • Use pre-allocated buffers where possible
  • Profile with cargo bench for performance-critical code
  • Avoid unnecessary allocations in hot paths

Testing

Running Specific Tests

# Run a specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run integration tests
cargo test --test integration_test_name

Conformance Testing

This library is validated against the official 3MF Consortium test suites. To run conformance tests:

# Run all conformance tests
cargo test --test conformance_tests summary -- --ignored --nocapture

# Run specific suite
cargo test --test conformance_tests suite3_core -- --nocapture

Security

Reporting Security Issues

If you discover a security vulnerability, please do not open a public issue. Instead, please email the maintainers directly or use GitHub's private security advisory feature.

Security Guidelines

  • Never add unsafe code (enforced by #![forbid(unsafe_code)])
  • Validate all XML input thoroughly
  • Check array bounds and prevent integer overflows
  • Validate resource ID references to prevent infinite loops
  • Handle ZIP bomb scenarios
  • Never commit secrets or credentials

Getting Help

License

By contributing to lib3mf_rust, you agree that your contributions will be licensed under the MIT License, the same as the project.