Category: Contributing

# Clone the monorepo
git clone https://github.com/codeprosorg/geode
cd geode

# The monorepo contains:
# - geode/              Main database server
# - geode-client-go/    Go client library
# - geode-client-python/ Python client library
# - geode-client-rust/  Rust client library
# - geode-client-zig/   Zig client library
# - geode-test-harness/ Cross-client testing
# - gql/                GQL reference implementation

cd geode

# Build the server
make build

# Run tests
make test

# Run comprehensive test suite (97.4% pass rate)
make geodetestlab-comprehensive

# Start development server
./zig-out/bin/geode serve --listen 127.0.0.1:3141

# Go client
cd geode-client-go
go test -v

# Python client
cd geode-client-python
pip install -r requirements.txt
pytest

# Rust client
cd geode-client-rust
cargo build
cargo test

# Zig client
cd geode-client-zig
zig build
zig build test

# Search existing issues
# Visit: https://gitlab.com/devnw/codepros/geode/-/issues

# Create a new issue if needed
# Describe the problem or feature request clearly
# Include reproduction steps for bugs
# Provide use cases for feature requests

# Create a branch from main
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

# Branch naming conventions:
# - feature/feature-name
# - fix/bug-description
# - docs/documentation-update
# - refactor/refactoring-description

// Zig code style
// - Use 4 spaces for indentation
// - Follow Zig naming conventions
// - Add doc comments for public APIs

/// Executes a GQL query and returns results.
///
/// # Arguments
/// * `query` - The GQL query string
/// * `params` - Optional query parameters
///
/// # Returns
/// A result iterator over query results
pub fn execute(self: *Client, query: []const u8, params: ?Params) !ResultIterator {
    // Implementation
}

// geode/src/tests/query_test.zig
test "query with parameters" {
    const allocator = std.testing.allocator;

    var client = try Client.connect(allocator, "localhost", 3141);
    defer client.deinit();

    const query = "MATCH (u:User {id: $id}) RETURN u.name";
    const params = .{ .id = 123 };

    var result = try client.execute(query, params);
    defer result.deinit();

    const row = try result.next();
    try std.testing.expectEqualStrings("Alice", row.?.get("u.name").?.string);
}

# API changes - Update API_REFERENCE.md
# New features - Update FEATURES_OVERVIEW.md
# User-facing changes - Update relevant guides
# Breaking changes - Update CHANGELOG.md and migration guides

// CANARY-START:FEATURE:GQL-COMPLIANCE:MATCH-CLAUSE
// Implementation of ISO/IEC 39075:2024 MATCH clause
pub fn executeMatch(self: *QueryEngine, pattern: Pattern) !ResultSet {
    // Implementation that satisfies GQL spec
}
// CANARY-END:FEATURE:GQL-COMPLIANCE:MATCH-CLAUSE

# Commit message format
git commit -m "type(scope): description

Longer description of the change, why it was needed,
and any relevant context.

Closes #issue-number"

# Types:
# - feat: New feature
# - fix: Bug fix
# - docs: Documentation only
# - style: Formatting, no code change
# - refactor: Code restructuring
# - perf: Performance improvement
# - test: Adding tests
# - chore: Build process, dependencies

# Examples:
git commit -m "feat(query): add support for OPTIONAL MATCH

Implements optional pattern matching per ISO/IEC 39075:2024
section 7.3. Includes comprehensive tests and updates to
query planner.

Closes #234"

git commit -m "fix(mvcc): prevent snapshot leak in long transactions

Fixes memory leak when transactions are held open for >1 hour.
Adds test case to verify cleanup.

Closes #456"

# Push your branch
git push -u origin feature/your-feature-name

# Create merge request on GitLab
# Fill in the MR template:
# - Description of changes
# - Testing performed
# - Documentation updates
# - Breaking changes (if any)
# - Related issues

# MR title format:
# "feat: Add vector search support"
# "fix: Resolve deadlock in transaction manager"
# "docs: Update client library examples"

# Make changes based on feedback
git add .
git commit -m "Address review feedback: improve error handling"
git push

# Merge requests are updated automatically
# Continue discussion in MR comments
# Resolve conversations as addressed

// Test individual functions
test "transaction rollback releases locks" {
    var tx = try Transaction.begin(allocator);
    defer tx.deinit();

    try tx.acquireLock(.exclusive, node_id);
    try tx.rollback();

    // Verify lock is released
    try std.testing.expect(!lock_manager.isLocked(node_id));
}

-- Test full query execution
-- tests/integration/query_test.gql

CREATE (:User {name: 'Alice', email: 'alice@example.com'})
CREATE (:User {name: 'Bob', email: 'bob@example.com'})

MATCH (u:User)
WHERE u.name = 'Alice'
RETURN u.email
-- EXPECT: alice@example.com

// Test ISO/IEC 39075:2024 compliance
test "GQL compliance: MATCH with WHERE" {
    // Test implementation against GQL spec section X.Y.Z
    const query = "MATCH (n:Node) WHERE n.prop > 10 RETURN n";
    // Verify behavior matches spec
}

// Benchmark critical paths
test "query execution performance" {
    const iterations = 10000;
    const start = std.time.nanoTimestamp();

    for (0..iterations) |_| {
        _ = try client.execute(query, params);
    }

    const elapsed = std.time.nanoTimestamp() - start;
    const avg_ns = elapsed / iterations;

    // Verify performance target (e.g., < 1ms average)
    try std.testing.expect(avg_ns < 1_000_000);
}

/// Executes a GQL query with parameters.
///
/// This function parses the query, creates an execution plan,
/// and returns an iterator over results. The query is executed
/// within the current transaction context if one exists.
///
/// # Arguments
/// * `query` - GQL query string (must be valid per ISO/IEC 39075:2024)
/// * `params` - Optional map of query parameters
///
/// # Returns
/// * `ResultIterator` - Iterator over query results
/// * `QueryError` - If query is invalid or execution fails
///
/// # Example
/// ```zig
/// var result = try client.execute(
///     "MATCH (u:User {id: $id}) RETURN u.name",
///     .{ .id = 123 }
/// );
/// while (try result.next()) |row| {
///     std.debug.print("{s}\n", .{row.get("u.name")});
/// }
/// ```
pub fn execute(
    self: *Client,
    query: []const u8,
    params: ?Params,
) !ResultIterator {
    // Implementation
}

# Update relevant documentation files:
# - README.md for overview changes
# - docs/FEATURES_OVERVIEW.md for features
# - docs/API_REFERENCE.md for API changes
# - docs/QUICK_REFERENCE.md for syntax
# - CHANGELOG.md for all user-visible changes

# Example CHANGELOG.md entry:

## [Unreleased]

### Added
- Vector search with HNSW indexing (#234)
- Support for OPTIONAL MATCH clause (#245)

### Fixed
- Deadlock in concurrent transactions (#256)
- Memory leak in long-running queries (#267)

### Changed
- Improved query planner performance by 30% (#278)

### Breaking Changes
- Configuration file format changed (see migration guide)

# Read the project guide
cat geode/CLAUDE.md

# Key sections:
# - Implementation Methodology (evidence-based development)
# - Architecture Overview (system design)
# - CANARY governance system
# - Development guidelines

// Before implementing a GQL feature:
// 1. Read relevant section of ISO/IEC 39075:2024
// 2. Understand spec requirements
// 3. Implement per spec
// 4. Add compliance tests
// 5. Add CANARY markers

// Example: Implementing EXISTS predicate per spec section 8.4
// CANARY-START:COMPLIANCE:GQL:EXISTS-PREDICATE
pub fn evaluateExists(self: *Evaluator, pattern: Pattern) !bool {
    // Implementation must match spec behavior exactly
}
// CANARY-END:COMPLIANCE:GQL:EXISTS-PREDICATE