|
1 | | -# Contributing to InferaDB Rust SDK |
| 1 | +# Contributing to InferaDB |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to the InferaDB Rust SDK! This document provides guidelines and instructions for contributing. |
| 3 | +Thank you for your interest in contributing to InferaDB! We welcome contributions from the community and are grateful for any help you can provide. |
4 | 4 |
|
5 | | -## Development Setup |
| 5 | +## Code of Conduct |
6 | 6 |
|
7 | | -### Prerequisites |
| 7 | +This project and everyone participating in it is governed by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [open@inferadb.com](mailto:open@inferadb.com). |
8 | 8 |
|
9 | | -- [Mise](https://mise.jdx.dev/) - Tool version manager (recommended) |
10 | | -- Rust 1.88.0+ (stable) - Managed by mise or rustup |
11 | | -- Rust nightly (for formatting) |
12 | | -- Docker and Docker Compose (for integration tests) |
13 | | -- [inferadb/deploy](https://github.com/inferadb/deploy) - Development environment (for integration tests) |
| 9 | +## How to Contribute |
14 | 10 |
|
15 | | -### Minimum Supported Rust Version (MSRV) |
| 11 | +### Reporting Issues |
16 | 12 |
|
17 | | -The SDK requires Rust **1.88.0** or later. We maintain the MSRV at two releases behind the latest stable release where possible (e.g., if stable is 1.90, MSRV would be 1.88). |
| 13 | +- **Bug Reports**: Search existing issues first to avoid duplicates. Include version information, steps to reproduce, expected vs actual behavior, and relevant logs. |
| 14 | +- **Feature Requests**: Describe the use case, proposed solution, and alternatives considered. |
| 15 | +- **Security Issues**: Do **not** open public issues for security vulnerabilities. Instead, email [security@inferadb.com](mailto:security@inferadb.com). |
18 | 16 |
|
19 | | -- MSRV increases will be called out in the [CHANGELOG](CHANGELOG.md) |
20 | | -- We do not guarantee builds on compiler versions earlier than the MSRV |
21 | | -- The `rust-version` field in `Cargo.toml` enforces this at build time |
| 17 | +### Pull Requests |
22 | 18 |
|
23 | | -### Getting Started |
| 19 | +1. **Fork the repository** and create your branch from `main` |
| 20 | +2. **Follow the development workflow** documented in the repository's README |
| 21 | +3. **Write clear commit messages** following [Conventional Commits](https://www.conventionalcommits.org/): |
| 22 | + - `feat:` New features |
| 23 | + - `fix:` Bug fixes |
| 24 | + - `docs:` Documentation changes |
| 25 | + - `test:` Test additions or improvements |
| 26 | + - `refactor:` Code refactoring |
| 27 | + - `chore:` Maintenance tasks |
| 28 | +4. **Ensure all tests pass** before submitting |
| 29 | +5. **Update documentation** if your changes affect public APIs or user-facing behavior |
| 30 | +6. **Submit a pull request** with a clear description of your changes |
24 | 31 |
|
25 | | -```bash |
26 | | -# Clone the SDK repository |
27 | | -git clone https://github.com/inferadb/rust |
28 | | -cd rust-sdk |
| 32 | +### Development Setup |
29 | 33 |
|
30 | | -# One-time setup (installs Rust toolchain and dev tools) |
31 | | -make setup |
| 34 | +Each repository has its own development setup and workflow. Please refer to: |
32 | 35 |
|
33 | | -# Build the project |
34 | | -make build |
| 36 | +- **[DEVELOPMENT.md](./DEVELOPMENT.md)** for repository-specific development and contribution guidance |
| 37 | +- **README.md** for general project information and quick start instructions |
35 | 38 |
|
36 | | -# Run tests |
37 | | -make test |
| 39 | +These documents cover prerequisites, dependencies, build commands, code style guidelines, and repository-specific requirements. |
38 | 40 |
|
39 | | -# See all available commands |
40 | | -make help |
41 | | -``` |
| 41 | +## Review Process |
42 | 42 |
|
43 | | -### Makefile Targets |
| 43 | +1. **Automated Checks**: CI will run tests, linters, and formatters |
| 44 | +2. **Peer Review**: At least one maintainer will review your contribution |
| 45 | +3. **Feedback**: Address any review comments |
| 46 | +4. **Approval**: Once approved, a maintainer will merge your contribution |
44 | 47 |
|
45 | | -| Target | Description | |
46 | | -| --------------- | --------------------------------------- | |
47 | | -| `make setup` | One-time dev environment setup via Mise | |
48 | | -| `make build` | Build all workspace crates | |
49 | | -| `make test` | Run unit tests | |
50 | | -| `make test-all` | Run unit + integration tests | |
51 | | -| `make check` | Run format check + clippy | |
52 | | -| `make coverage` | Run tests with coverage report | |
53 | | -| `make doc` | Build documentation | |
54 | | -| `make proto` | Regenerate protobuf code and format | |
55 | | -| `make ci` | Full CI pipeline (format, lint, test) | |
56 | | - |
57 | | -### Running with Local InferaDB |
58 | | - |
59 | | -Integration tests require a running InferaDB instance. Use the official development environment from [inferadb/deploy](https://github.com/inferadb/deploy): |
60 | | - |
61 | | -```bash |
62 | | -# Start the development environment using the InferaDB CLI |
63 | | -inferadb dev start |
64 | | - |
65 | | -# The environment includes: |
66 | | -# - InferaDB Engine (authorization API) |
67 | | -# - InferaDB Control (management API) |
68 | | -# - FoundationDB (storage) |
69 | | -# - Supporting services |
70 | | -``` |
71 | | - |
72 | | -Once the development environment is running, return to the SDK directory and run integration tests: |
73 | | - |
74 | | -```bash |
75 | | -cd /path/to/inferadb-rust-sdk |
76 | | - |
77 | | -# Run integration tests against local InferaDB |
78 | | -make test-integration |
79 | | - |
80 | | -# Or run specific integration tests |
81 | | -cargo test --test integration --features "rest,insecure" -- --ignored |
82 | | -``` |
83 | | - |
84 | | -#### Environment Variables |
85 | | - |
86 | | -The integration tests use these environment variables (with defaults for local development): |
87 | | - |
88 | | -| Variable | Default | Description | |
89 | | -| ---------------------- | ----------------------- | ------------------------------------------- | |
90 | | -| `INFERADB_URL` | `http://localhost:8080` | InferaDB Engine URL | |
91 | | -| `INFERADB_CONTROL_URL` | `http://localhost:8081` | InferaDB Control URL | |
92 | | -| `INFERADB_CLIENT_ID` | - | Test client ID (created by dev environment) | |
93 | | -| `INFERADB_PRIVATE_KEY` | - | Path to test private key | |
94 | | - |
95 | | -The dev environment from `inferadb/deploy` automatically configures test credentials. |
96 | | - |
97 | | -## Code Style |
98 | | - |
99 | | -We use Rust's standard formatting and linting tools. Use the Makefile for convenience: |
100 | | - |
101 | | -```bash |
102 | | -# Format code (requires nightly) |
103 | | -make fmt |
104 | | - |
105 | | -# Lint with clippy |
106 | | -make clippy |
107 | | - |
108 | | -# Run all checks (format + clippy) |
109 | | -make check |
110 | | - |
111 | | -# Build documentation |
112 | | -make doc |
113 | | -``` |
114 | | - |
115 | | -### Style Guidelines |
116 | | - |
117 | | -- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) |
118 | | -- Use `rustfmt` defaults (no custom configuration) |
119 | | -- All public items must have documentation |
120 | | -- No `unwrap()` or `expect()` in library code (except in tests) |
121 | | -- Prefer `?` operator over explicit `match` for error handling |
122 | | - |
123 | | -## gRPC Code Generation |
124 | | - |
125 | | -The SDK uses [tonic](https://github.com/hyperium/tonic) for gRPC support. Protobuf definitions are in `proto/inferadb.proto` and generated Rust code lives in `src/transport/proto/`. |
126 | | - |
127 | | -### When to Regenerate |
128 | | - |
129 | | -Regenerate protobuf code when: |
130 | | - |
131 | | -- The `proto/inferadb.proto` file is updated |
132 | | -- Upgrading tonic or prost versions |
133 | | -- Generated code gets out of sync |
134 | | - |
135 | | -### How to Regenerate |
136 | | - |
137 | | -```bash |
138 | | -make proto |
139 | | -``` |
140 | | - |
141 | | -This command: |
142 | | - |
143 | | -1. Touches the proto file to trigger regeneration |
144 | | -2. Runs `cargo build --features grpc` to invoke tonic-build |
145 | | -3. Formats the generated code with `make fmt` |
146 | | - |
147 | | -### Notes |
148 | | - |
149 | | -- Generated code is committed to the repository for reproducible builds |
150 | | -- The `build.rs` script handles code generation via tonic-build |
151 | | -- Only the gRPC client is generated (no server code) |
152 | | - |
153 | | -## Testing Guidelines |
154 | | - |
155 | | -### Unit Tests |
156 | | - |
157 | | -Use mocks for unit tests to avoid network dependencies: |
158 | | - |
159 | | -```rust |
160 | | -use inferadb::testing::MockClient; |
161 | | - |
162 | | -#[tokio::test] |
163 | | -async fn test_check_returns_true_for_allowed() { |
164 | | - let mock = MockClient::builder() |
165 | | - .check("user:alice", "view", "doc:1", true) |
166 | | - .build(); |
167 | | - |
168 | | - assert!(mock.check("user:alice", "view", "doc:1").await.unwrap()); |
169 | | -} |
170 | | - |
171 | | -#[tokio::test] |
172 | | -async fn test_check_returns_false_for_denied() { |
173 | | - let mock = MockClient::builder() |
174 | | - .check("user:bob", "delete", "doc:1", false) |
175 | | - .build(); |
176 | | - |
177 | | - assert!(!mock.check("user:bob", "delete", "doc:1").await.unwrap()); |
178 | | -} |
179 | | -``` |
180 | | - |
181 | | -### Integration Tests |
182 | | - |
183 | | -Integration tests require a running InferaDB instance. See [Running with Local InferaDB](#running-with-local-inferadb) for setup instructions using the [inferadb/deploy](https://github.com/inferadb/deploy) development environment. |
184 | | - |
185 | | -Use `#[ignore]` for tests that require a running InferaDB instance: |
186 | | - |
187 | | -```rust |
188 | | -#[tokio::test] |
189 | | -#[ignore] // Run with: cargo test --ignored |
190 | | -async fn integration_test_check() { |
191 | | - let client = test_client().await; |
192 | | - let vault = TestVault::create(&client).await.unwrap(); |
193 | | - |
194 | | - vault.write(Relationship::new("doc:1", "viewer", "user:alice")).await.unwrap(); |
195 | | - assert!(vault.check("user:alice", "view", "doc:1").await.unwrap()); |
196 | | -} |
197 | | -``` |
198 | | - |
199 | | -Run integration tests with: |
200 | | - |
201 | | -```bash |
202 | | -# Ensure inferadb/deploy dev environment is running first |
203 | | -make test-integration |
204 | | -``` |
205 | | - |
206 | | -### Test Organization |
207 | | - |
208 | | -```text |
209 | | -tests/ |
210 | | -├── unit/ # Unit tests with mocks |
211 | | -├── integration/ # Tests requiring InferaDB instance |
212 | | -└── fixtures/ # Shared test data and helpers |
213 | | -``` |
214 | | - |
215 | | -## Pull Request Process |
216 | | - |
217 | | -### Before Submitting |
218 | | - |
219 | | -Run the full CI pipeline locally: |
220 | | - |
221 | | -```bash |
222 | | -make ci |
223 | | -``` |
224 | | - |
225 | | -This runs format checks, clippy, tests, and documentation checks. |
226 | | - |
227 | | -Or run individual steps: |
228 | | - |
229 | | -```bash |
230 | | -make fmt # Format code |
231 | | -make check # Format check + clippy |
232 | | -make test # Run tests |
233 | | -make doc-check # Check documentation |
234 | | -``` |
235 | | - |
236 | | -### PR Checklist |
237 | | - |
238 | | -- [ ] CI passes (`make ci`) |
239 | | -- [ ] Tests pass (`make test`) |
240 | | -- [ ] No clippy warnings (`make clippy`) |
241 | | -- [ ] Code formatted (`make fmt`) |
242 | | -- [ ] Documentation updated for public API changes |
243 | | -- [ ] CHANGELOG.md updated (under `[Unreleased]`) |
244 | | -- [ ] Version bumped if needed (for breaking changes) |
245 | | - |
246 | | -### Commit Messages |
247 | | - |
248 | | -Follow [Conventional Commits](https://www.conventionalcommits.org/): |
249 | | - |
250 | | -```text |
251 | | -feat: add batch check support |
252 | | -fix: resolve token refresh race condition |
253 | | -docs: update authentication examples |
254 | | -refactor: simplify error handling |
255 | | -test: add integration tests for watch streams |
256 | | -chore: update dependencies |
257 | | -``` |
258 | | - |
259 | | -### Breaking Changes |
260 | | - |
261 | | -For breaking changes: |
262 | | - |
263 | | -1. Add `BREAKING CHANGE:` footer to commit message |
264 | | -2. Document upgrade instructions in CHANGELOG.md |
265 | | -3. Bump major version (or minor for 0.x) |
266 | | - |
267 | | -## Reporting Issues |
268 | | - |
269 | | -File issues at: <https://github.com/inferadb/rust/issues> |
270 | | - |
271 | | -### Bug Reports |
272 | | - |
273 | | -Include: |
274 | | - |
275 | | -- SDK version (`cargo pkgid inferadb`) |
276 | | -- Rust version (`rustc --version`) |
277 | | -- Operating system and version |
278 | | -- Minimal reproduction code |
279 | | -- Full error message with request ID if available |
280 | | -- Expected vs actual behavior |
281 | | - |
282 | | -### Feature Requests |
283 | | - |
284 | | -Include: |
| 48 | +## License |
285 | 49 |
|
286 | | -- Use case description |
287 | | -- Proposed API (if applicable) |
288 | | -- Alternative solutions considered |
| 50 | +By contributing to InferaDB, you agree that your contributions will be licensed under the same license as the repository you are contributing to. See the LICENSE file in each repository for details. |
289 | 51 |
|
290 | | -## Getting Help |
| 52 | +## Questions? |
291 | 53 |
|
292 | | -- **Questions:** Open a [Discussion](https://github.com/inferadb/rust/discussions) |
293 | | -- **Bugs:** Open an [Issue](https://github.com/inferadb/rust/issues) |
294 | | -- **Security:** Email <security@inferadb.com> (do not open public issues) |
| 54 | +If you have questions or need help: |
295 | 55 |
|
296 | | -## License |
| 56 | +- Open a [Discussion](https://github.com/inferadb/inferadb/discussions) on GitHub |
| 57 | +- Email us at [open@inferadb.com](mailto:open@inferadb.com) |
297 | 58 |
|
298 | | -By contributing, you agree that your contributions will be licensed under the Apache License 2.0. |
| 59 | +Thank you for helping make InferaDB better! |
0 commit comments