Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
133 lines (93 loc) · 4.68 KB

CONTRIBUTING.md

File metadata and controls

133 lines (93 loc) · 4.68 KB

Contributing to InferaDB

Thank you for your interest in contributing to InferaDB! We welcome contributions from the community and are grateful for any help you can provide.

Code of Conduct

This project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to open@inferadb.com.

How to Contribute

Reporting Issues

  • Bug Reports: Search existing issues first to avoid duplicates. Include version information, steps to reproduce, expected vs actual behavior, and relevant logs.
  • Feature Requests: Describe the use case, proposed solution, and alternatives considered.
  • Security Issues: Do not open public issues for security vulnerabilities. Instead, email security@inferadb.com.

Pull Requests

  1. Fork the repository and create your branch from main
  2. Follow the development workflow documented in the repository's README.md
  3. Write clear commit messages following Conventional Commits
  4. Run just before submitting to verify formatting, lints, and tests pass
  5. Update documentation if your changes affect public APIs or user-facing behavior
  6. Submit a pull request with a clear description of your changes

Development Setup

Each repository has its own development setup and workflow. See the repository's README.md for prerequisites, build commands, and development workflow.

Review Process

  1. Automated Checks: CI will run tests, linters, and formatters
  2. Peer Review: At least one maintainer will review your contribution
  3. Feedback: Address any review comments
  4. Approval: Once approved, a maintainer will merge your contribution

License

By contributing to InferaDB, you agree that your contributions will be dual-licensed under:

Builder Pattern Guidelines

This SDK uses two builder approaches. Choose based on the pattern requirements:

When to Use #[bon::builder]

Use bon-derived builders for transport and configuration internals:

  • Simple constructors with no async finalization patterns
  • No IntoFuture requirement (users call .build() explicitly)
  • No typestate enforcement needed
  • Single finalizer method
// Example: Transport builder using bon
#[bon]
impl RestTransport {
    #[builder]
    pub fn new(
        base_url: Url,
        #[builder(default)] tls_config: Option<TlsConfig>,
        #[builder(default)] timeout: Option<Duration>,
    ) -> Result<Self, Error> { /* ... */ }
}

// Usage
let transport = RestTransport::builder()
    .base_url(url)
    .tls_config(tls)
    .build()?;

When to Use Manual Builders

Use manual builders for client-facing async APIs:

Pattern Reason Example
IntoFuture Enables ergonomic .await without .build() vault.check(...).await
Typestate Compile-time enforcement of required fields ClientBuilder<HasUrl, HasCredentials>
Dual Finalizers Multiple consumption methods .stream() and .collect() 
// Example: IntoFuture builder (manual)
pub struct CheckRequest { /* ... */ }

impl IntoFuture for CheckRequest {
    type Output = Result<bool, Error>;
    type IntoFuture = /* ... */;
    
    fn into_future(self) -> Self::IntoFuture { /* ... */ }
}

// Usage - no .build() needed
let allowed = vault.check("user:alice", "view", "doc:1").await?;

Decision Tree

Need .await without .build()?
  └─ Yes → Manual builder with IntoFuture
  └─ No → Continue

Need compile-time required field enforcement?
  └─ Yes → Manual builder with typestate
  └─ No → Continue

Need multiple finalizers (.stream() + .collect())?
  └─ Yes → Manual builder with dual finalizers
  └─ No → Use #[bon::builder]

Future bon Migration Opportunities

The bon crate is actively developed. Features that would enable more migrations:

  • IntoFuture support: Would allow converting async request builders
  • Multiple finalizers: Would allow converting streaming builders
  • Typestate support: Would allow converting ClientBuilder

Track progress: GitHub Issue #23

Questions?

If you have questions or need help:

Thank you for helping make InferaDB better!