# Contributing to Graph_D
Thank you for your interest in contributing to Graph_D! This document provides guidelines and information for contributors.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Commit Guidelines](#commit-guidelines)
- [Pull Request Process](#pull-request-process)
- [Testing](#testing)
- [Documentation](#documentation)
- [Release Process](#release-process)
## Code of Conduct
This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please be respectful and constructive in all interactions.
## Getting Started
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone https://github.com/YOUR_USERNAME/graph_d.git
cd graph_d
```
3. **Add upstream remote**:
```bash
git remote add upstream https://github.com/your-org/graph_d.git
```
## Development Setup
### Prerequisites
- Rust 1.70 or later (check with `rustc --version`)
- Git
### Building
```bash
# Build library only (default)
cargo build
# Build with CLI
cargo build --features cli
# Run tests
cargo test
# Run benchmarks
cargo bench
```
### Project Structure
```
graph_d/
├── src/
│ ├── lib.rs # Library entry point
│ ├── bin/
│ │ └── graph_d.rs # CLI binary (requires 'cli' feature)
│ ├── error.rs # Error types
│ ├── gql/ # GQL parser and executor
│ ├── graph/ # Core graph structures
│ ├── index/ # Indexing system
│ ├── memory/ # Memory management
│ ├── query/ # Query engine
│ ├── storage/ # Storage backend
│ └── transaction/ # Transaction management
├── tests/ # Integration tests
├── benches/ # Benchmarks
└── examples/ # Usage examples
```
## Commit Guidelines
We use **Conventional Commits** to ensure consistent commit messages and enable automated releases.
### Format
```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
### Types
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only changes |
| `style` | Formatting, missing semicolons, etc. |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `build` | Changes to build system or dependencies |
| `ci` | Changes to CI configuration |
| `chore` | Other changes that don't modify src or test files |
| `revert` | Reverts a previous commit |
### Scopes (Optional)
Common scopes for this project:
- `gql` - GQL parser/executor
- `graph` - Core graph structures
- `index` - Indexing system
- `query` - Query engine
- `storage` - Storage backend
- `transaction` - Transaction management
- `cli` - CLI binary
- `api` - Public API changes
### Examples
```bash
# Feature
git commit -m "feat(query): add path finding algorithm"
# Bug fix
git commit -m "fix(gql): resolve parser error on empty MATCH clauses"
# Documentation
git commit -m "docs: add CLI usage examples to README"
# Performance improvement
git commit -m "perf(index): optimize B-tree lookups"
# Breaking change (note the !)
git commit -m "feat(api)!: rename Database to GraphDb"
```
### Breaking Changes
For breaking changes, add `!` after the type/scope or include `BREAKING CHANGE:` in the footer:
```
feat(api)!: rename Database to GraphDb
BREAKING CHANGE: The `Database` struct has been renamed to `GraphDb`.
Update all imports and type references.
```
## Pull Request Process
1. **Create a feature branch**:
```bash
git checkout -b feat/my-feature
```
2. **Make your changes** with appropriate commits following the commit guidelines
3. **Ensure all tests pass**:
```bash
cargo test
cargo clippy -- -D warnings
cargo fmt --check
```
4. **Update documentation** if needed:
```bash
cargo doc --no-deps
```
5. **Push to your fork**:
```bash
git push origin feat/my-feature
```
6. **Open a Pull Request** against the `main` branch
### PR Requirements
- [ ] All tests pass
- [ ] Code follows project style (run `cargo fmt`)
- [ ] No clippy warnings (run `cargo clippy -- -D warnings`)
- [ ] Documentation updated if needed
- [ ] Commits follow conventional commit format
- [ ] PR description explains the changes
## Testing
### Running Tests
```bash
# All tests
cargo test
# Specific test
cargo test test_name
# With output
cargo test -- --nocapture
# Integration tests only
cargo test --test '*'
```
### Writing Tests
- Place unit tests in the same file as the code they test
- Place integration tests in the `tests/` directory
- Use descriptive test names that explain what is being tested
- Include both positive and negative test cases
### Benchmarks
```bash
# Run all benchmarks
cargo bench
# Run specific benchmark
cargo bench bench_name
```
## Documentation
- All public items must have documentation
- Use `///` for item documentation
- Use `//!` for module-level documentation
- Include examples in documentation where appropriate
```rust
/// Creates a new graph database.
///
/// # Arguments
///
/// * `path` - Path to the database file
///
/// # Examples
///
/// ```
/// use graph_d::Database;
///
/// let db = Database::open("my_graph.db")?;
/// ```
///
/// # Errors
///
/// Returns an error if the file cannot be created or opened.
pub fn open(path: impl AsRef<Path>) -> Result<Self, Error> {
// ...
}
```
## Release Process
Releases are automated via GitHub Actions using [release-please](https://github.com/googleapis/release-please).
### How It Works
1. Merge PRs with conventional commits to `main`
2. `release-please` creates a Release PR with:
- Updated `CHANGELOG.md`
- Bumped version in `Cargo.toml`
3. Merge the Release PR to trigger:
- GitHub Release creation
- Binary artifacts for all platforms
- Publication to crates.io
### Version Bumping
Version bumps are determined by commit types:
| `fix:` | Patch (0.0.X) |
| `feat:` | Minor (0.X.0) |
| `feat!:` or `BREAKING CHANGE:` | Major (X.0.0) |
### Repository Secrets (Maintainers)
For the release workflow to function, repository maintainers must configure these secrets:
| `GITHUB_TOKEN` | Create releases, push tags | Auto-provided by GitHub Actions |
| `CRATES_IO_TOKEN` | Publish to crates.io | Generate at [crates.io/settings/tokens](https://crates.io/settings/tokens) |
To configure secrets:
1. Go to **Settings** → **Secrets and variables** → **Actions**
2. Click **New repository secret**
3. Add `CRATES_IO_TOKEN` with your crates.io API token
### Binary Distribution
The release workflow automatically builds binaries for:
- Linux x86_64 (`x86_64-unknown-linux-gnu`)
- macOS x86_64 (`x86_64-apple-darwin`)
- macOS ARM64 (`aarch64-apple-darwin`)
- Windows x86_64 (`x86_64-pc-windows-msvc`)
Binaries are attached to GitHub Releases with SHA256 checksums.
## Questions?
If you have questions, feel free to:
- Open an issue for discussion
- Check existing issues and discussions
Thank you for contributing!