Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (127 loc) · 5 KB

CONTRIBUTING.md

File metadata and controls

181 lines (127 loc) · 5 KB
Raw

Contributing to grafton-ndi

Thank you for your interest in contributing to grafton-ndi! This document provides guidelines and information for contributors.

Code of Conduct

By participating in this project, you agree to abide by our code of conduct: be respectful, constructive, and professional.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a new branch for your feature or fix
  4. Make your changes
  5. Run tests and ensure they pass
  6. Submit a pull request

Development Setup

Prerequisites

  • Rust 1.87 or later
  • NDI SDK 6.x installed (see README for platform-specific instructions)
  • Git

Building

# Clone the repository
git clone https://github.com/GrantSparks/grafton-ndi.git
cd grafton-ndi

# Build the project
cargo build

# Run tests
cargo test

# Run examples
cargo run --example NDIlib_Find

Contribution Guidelines

Code Style

  • Follow Rust idioms and conventions
  • Use cargo fmt to format code
  • Run cargo clippy and address warnings
  • Add rustdoc comments for all public APIs
  • Include examples in documentation where helpful

Commit Messages

  • Use conventional commit format: type(scope): description
  • Types: feat, fix, docs, style, refactor, test, chore
  • Keep the first line under 72 characters
  • Reference issues when applicable

Examples:

feat(recv): add support for compressed video formats
fix(send): prevent panic on invalid frame dimensions
docs(api): improve VideoFrame builder documentation

Pull Requests

  1. Title: Use a clear, descriptive title
  2. Description: Explain what changes you made and why
  3. Testing: Describe how you tested your changes
  4. Breaking Changes: Clearly mark any breaking API changes

Testing

  • Add tests for new functionality
  • Ensure all existing tests pass
  • Include integration tests for complex features
  • Test on multiple platforms if possible

Compile Contract Tests

Zero-copy receive and async-send lifetime guarantees are enforced with trybuild compile tests in tests/compile_contracts.rs.

Run the compile contracts directly:

cargo test --test compile_contracts

Refresh expected compiler diagnostics after intentionally changing the contract fixtures or after stable rustc diagnostic wording changes:

TRYBUILD=overwrite cargo test --test compile_contracts

The project uses the stable Rust toolchain with clippy, rustfmt, and rust-src components via rust-toolchain.toml. The rust-src component keeps standard-library diagnostics consistent in local and CI runs. Treat .stderr snapshot updates as part of normal stable-compiler-upgrade maintenance, and review them to confirm they still fail for the intended lifetime or auto-trait reason.

CI/CD Configuration

GitHub Actions NDI SDK

The CI/CD pipeline requires the NDI SDK to build and test the project. You can configure the SDK version in two ways:

  1. Default: Uses the hardcoded NDI 6 SDK URL in the workflow
  2. Custom: Set the NDI_SDK_URL repository secret to use a different SDK version

To update the NDI SDK version for CI/CD:

  1. Go to Settings → Secrets and variables → Actions in your GitHub repository
  2. Create or update the NDI_SDK_URL secret with the new SDK download URL
  3. The cache will automatically invalidate when the URL changes

Example URLs:

  • NDI 6: https://downloads.ndi.tv/SDK/NDI_SDK/NDI%206%20SDK.exe
  • NDI 5: https://downloads.ndi.tv/SDK/NDI_SDK/NDI%205%20SDK.exe

Documentation

  • Update relevant documentation for any API changes
  • Add rustdoc comments for new public items
  • Update README if adding new features
  • Include code examples where appropriate

Areas for Contribution

High Priority

  • macOS platform testing and fixes
  • Performance optimizations
  • Additional examples
  • Documentation improvements

Feature Ideas

  • Async/await support
  • Additional color format conversions
  • Enhanced metadata handling
  • Debugging and diagnostic tools

Known Issues

Check the issue tracker for current bugs and feature requests.

Architecture Overview

Project Structure

grafton-ndi/
├── src/
│   ├── lib.rs          # Main library interface
│   ├── error.rs        # Error types
│   └── ndi_lib.rs      # Generated FFI bindings
├── build.rs            # Build script for bindgen
├── examples/           # Example applications
└── tests/              # Integration tests

Key Design Principles

  1. Safety First: Wrap all unsafe FFI in safe Rust APIs
  2. Zero-Cost Abstractions: Minimize overhead over raw NDI SDK
  3. Idiomatic Rust: Follow Rust conventions and patterns
  4. Thread Safety: Properly implement Send/Sync where appropriate

Questions?

  • Open an issue for bugs or feature requests
  • Start a discussion for design questions
  • Check existing issues before creating new ones

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.