Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
164 lines (111 loc) · 4.19 KB

CONTRIBUTING.md

File metadata and controls

164 lines (111 loc) · 4.19 KB

Contributing to ObzenFlow IDKit

Thanks for your interest in contributing!

By participating, you agree to follow the Code of Conduct (CODE_OF_CONDUCT.md).

Sign-off (DCO)

We use the Developer Certificate of Origin (DCO) instead of a Contributor License Agreement (CLA).

  • All commits in a PR must be signed off.
  • Sign off your commits with: git commit -s
  • The sign-off line looks like: Signed-off-by: Your Name <your.email@example.com>

The full text is in DCO.md.

Fixing missing sign-offs

  • Amend the most recent commit: git commit --amend -s
  • Sign off all commits on your branch (interactive): git rebase -i --signoff main

Contribution provenance

If you are employed, you are responsible for ensuring your employer's intellectual property policies permit your contribution. Many employment contracts include IP assignment clauses that may cover work done outside of office hours or on personal equipment.

If your employer requires a corporate sign-off or approval for open source contributions, please obtain it before submitting a pull request. By signing off your commits (DCO), you attest you have the right to contribute the work under the project's license terms.

Development Setup

Prerequisites

  • Rust toolchain (see .github/workflows/ci.yml for the pinned version used in CI)
  • Cargo

Building

# Native build
cargo build

# WASM build (compile check)
rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown

Testing

Run all tests:

cargo test

Run all tests with all features:

cargo test --all-features

Run a specific test:

cargo test test_name

Run tests with output:

cargo test -- --nocapture

Code Style

  • Follow standard Rust conventions
  • Use cargo fmt to format your code
  • Use cargo clippy to catch common mistakes
  • Add documentation comments for public APIs
  • Include examples in doc comments where appropriate

Testing Guidelines

Test Organization

  • Unit tests go in the same file as the code they test (in mod tests)
  • Integration tests go in the tests/ directory
  • Test both native and WASM targets when applicable
  • Use descriptive test names that explain what is being tested

Writing Tests

  • Test both success and failure cases
  • Test edge cases and boundary conditions
  • Ensure tests are deterministic (avoid relying on timing unless necessary)

Documentation

  • All public APIs must have documentation comments
  • Include examples in documentation where helpful
  • Update the README if you add new features
  • Explain phantom type usage clearly

Pull Request Process

  1. Before submitting:

    • Ensure all tests pass
    • Run cargo fmt and cargo clippy
    • Update documentation as needed

  2. PR Description:

    • Clearly describe what the PR does
    • Reference any related issues
    • Include examples of usage if adding new features
    • List any breaking changes

  3. Review Process:

    • PRs require at least one review before merging
    • Address reviewer feedback promptly
    • Keep PRs focused - one feature/fix per PR

Types of Contributions

Bug Reports

  • Use the issue tracker to report bugs
  • Include a minimal reproducible example
  • Describe expected vs actual behavior
  • Include environment details (OS, Rust version)

Feature Requests

  • Open an issue to discuss new features first
  • Explain the use case and motivation

Code Contributions

We especially welcome:

  • Performance improvements
  • Additional test coverage
  • Documentation improvements
  • Bug fixes
  • New examples

Questions?

Feel free to open an issue for any questions about contributing.

License

By contributing, you agree that your contributions will be licensed under the project's dual license (MIT OR Apache-2.0).

Source headers (SPDX)

All Rust source files (*.rs) must start with an SPDX header block.

Use:

// SPDX-License-Identifier: MIT OR Apache-2.0
// SPDX-FileCopyrightText: 2025-2026 ObzenFlow Contributors
// https://obzenflow.dev

Do not add individual names to per-file headers. Attribution lives in LICENSE-MIT and LICENSE-APACHE.

Security

Please do not open public issues for security vulnerabilities. See SECURITY.md.