Category: Contributing

Contributing to Geode means joining a vibrant open-source community dedicated to building a production-ready, ISO/IEC 39075:2024-compliant graph database. Whether you’re fixing bugs, adding features, improving documentation, or helping other users, your contributions help make Geode better for everyone. This category provides comprehensive guidance for contributing effectively, understanding the codebase, following project conventions, and participating in the community. Geode is written primarily in Zig, with polyglot client libraries in Go, Python, Rust, Node.js, and Zig. The project maintains rigorous quality standards including 97.4% test coverage, evidence-based development with CANARY governance markers tracking 2,190+ requirements, and comprehensive documentation. Understanding these standards and the contribution workflow ensures your contributions can be reviewed, merged, and maintained effectively. This guide covers everything from setting up your development environment through submitting pull requests, writing tests, maintaining documentation, and participating in design discussions. Whether you’re making your first open-source contribution or you’re an experienced contributor, this guide provides the information you need. <h3 id="getting-started" class="position-relative d-flex align-items-center group"> Getting Started <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="getting-started" aria-haspopup="dialog" aria-label="Share link: Getting Started"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script> <h4 id="development-environment-setup" class="position-relative d-flex align-items-center group"> Development Environment Setup <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="development-environment-setup" aria-haspopup="dialog" aria-label="Share link: Development Environment Setup"> Share link </button> </h4> <h5 id="prerequisites" class="position-relative d-flex align-items-center group"> Prerequisites <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="prerequisites" aria-haspopup="dialog" aria-label="Share link: Prerequisites"> Share link </button> </h5><ul> <li>Zig 0.1.0+: For server and Zig client development</li> <li>Go 1.24.0+: For Go client development</li> <li>Python 3.9+: For Python client development</li> <li>Rust 1.70+: For Rust client development</li> <li>Git: For version control</li> </ul> <h5 id="clone-the-repository" class="position-relative d-flex align-items-center group"> Clone the Repository <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="clone-the-repository" aria-haspopup="dialog" aria-label="Share link: Clone the Repository"> Share link </button> </h5><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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 </code></pre></div> <h5 id="server-development-setup" class="position-relative d-flex align-items-center group"> Server Development Setup <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="server-development-setup" aria-haspopup="dialog" aria-label="Share link: Server Development Setup"> Share link </button> </h5><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">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 </code></pre></div> <h5 id="client-development-setup" class="position-relative d-flex align-items-center group"> Client Development Setup <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="client-development-setup" aria-haspopup="dialog" aria-label="Share link: Client Development Setup"> Share link </button> </h5><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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 </code></pre></div> <h3 id="contribution-workflow" class="position-relative d-flex align-items-center group"> Contribution Workflow <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="contribution-workflow" aria-haspopup="dialog" aria-label="Share link: Contribution Workflow"> Share link </button> </h3> <h4 id="1-find-or-create-an-issue" class="position-relative d-flex align-items-center group"> 1. Find or Create an Issue <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="1-find-or-create-an-issue" aria-haspopup="dialog" aria-label="Share link: 1. Find or Create an Issue"> Share link </button> </h4>Before starting work, check if an issue exists: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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 </code></pre></div> <h4 id="2-create-a-feature-branch" class="position-relative d-flex align-items-center group"> 2. Create a Feature Branch <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="2-create-a-feature-branch" aria-haspopup="dialog" aria-label="Share link: 2. Create a Feature Branch"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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 </code></pre></div> <h4 id="3-make-your-changes" class="position-relative d-flex align-items-center group"> 3. Make Your Changes <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="3-make-your-changes" aria-haspopup="dialog" aria-label="Share link: 3. Make Your Changes"> Share link </button> </h4>Follow the project’s coding standards and architecture: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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 } </code></pre></div> <h4 id="4-write-tests" class="position-relative d-flex align-items-center group"> 4. Write Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="4-write-tests" aria-haspopup="dialog" aria-label="Share link: 4. Write Tests"> Share link </button> </h4>All code changes must include tests: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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); } </code></pre></div>Test coverage requirements: <ul> <li>All new features must have tests</li> <li>Bug fixes must include regression tests</li> <li>Maintain or improve overall coverage (currently 97.4%)</li> <li>Use <code>make geodetestlab-comprehensive</code> to run full suite</li> </ul> <h4 id="5-update-documentation" class="position-relative d-flex align-items-center group"> 5. Update Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="5-update-documentation" aria-haspopup="dialog" aria-label="Share link: 5. Update Documentation"> Share link </button> </h4>Documentation updates are required for: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"># 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 </code></pre></div> <h4 id="6-add-canary-markers" class="position-relative d-flex align-items-center group"> 6. Add CANARY Markers <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="6-add-canary-markers" aria-haspopup="dialog" aria-label="Share link: 6. Add CANARY Markers"> Share link </button> </h4>Geode uses CANARY governance markers to track requirements: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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 </code></pre></div>CANARY markers track: <ul> <li>Feature implementations</li> <li>Compliance requirements</li> <li>Security measures</li> <li>Performance guarantees</li> <li>Test coverage</li> </ul> <h4 id="7-commit-your-changes" class="position-relative d-flex align-items-center group"> 7. Commit Your Changes <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="7-commit-your-changes" aria-haspopup="dialog" aria-label="Share link: 7. Commit Your Changes"> Share link </button> </h4>Follow conventional commit format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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" </code></pre></div> <h4 id="8-push-and-create-merge-request" class="position-relative d-flex align-items-center group"> 8. Push and Create Merge Request <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="8-push-and-create-merge-request" aria-haspopup="dialog" aria-label="Share link: 8. Push and Create Merge Request"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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" </code></pre></div> <h3 id="code-review-process" class="position-relative d-flex align-items-center group"> Code Review Process <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="code-review-process" aria-haspopup="dialog" aria-label="Share link: Code Review Process"> Share link </button> </h3> <h4 id="what-reviewers-look-for" class="position-relative d-flex align-items-center group"> What Reviewers Look For <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="what-reviewers-look-for" aria-haspopup="dialog" aria-label="Share link: What Reviewers Look For"> Share link </button> </h4><ol> <li>Correctness: Does the code work as intended?</li> <li>Tests: Are there comprehensive tests?</li> <li>Performance: Are there performance regressions?</li> <li>Standards: Does it follow ISO/IEC 39075:2024?</li> <li>Documentation: Are user-facing changes documented?</li> <li>Code quality: Is the code maintainable?</li> <li>CANARY markers: Are requirements tracked?</li> </ol> <h4 id="addressing-review-feedback" class="position-relative d-flex align-items-center group"> Addressing Review Feedback <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="addressing-review-feedback" aria-haspopup="dialog" aria-label="Share link: Addressing Review Feedback"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 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 </code></pre></div> <h3 id="testing-guidelines" class="position-relative d-flex align-items-center group"> Testing Guidelines <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="testing-guidelines" aria-haspopup="dialog" aria-label="Share link: Testing Guidelines"> Share link </button> </h3> <h4 id="unit-tests" class="position-relative d-flex align-items-center group"> Unit Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="unit-tests" aria-haspopup="dialog" aria-label="Share link: Unit Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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)); } </code></pre></div> <h4 id="integration-tests" class="position-relative d-flex align-items-center group"> Integration Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="integration-tests" aria-haspopup="dialog" aria-label="Share link: Integration Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- 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 </code></pre></div> <h4 id="compliance-tests" class="position-relative d-flex align-items-center group"> Compliance Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="compliance-tests" aria-haspopup="dialog" aria-label="Share link: Compliance Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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 } </code></pre></div> <h4 id="performance-tests" class="position-relative d-flex align-items-center group"> Performance Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-tests" aria-haspopup="dialog" aria-label="Share link: Performance Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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); } </code></pre></div> <h3 id="documentation-guidelines" class="position-relative d-flex align-items-center group"> Documentation Guidelines <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="documentation-guidelines" aria-haspopup="dialog" aria-label="Share link: Documentation Guidelines"> Share link </button> </h3> <h4 id="code-documentation" class="position-relative d-flex align-items-center group"> Code Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="code-documentation" aria-haspopup="dialog" aria-label="Share link: Code Documentation"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">/// 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 } </code></pre></div> <h4 id="user-documentation" class="position-relative d-flex align-items-center group"> User Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="user-documentation" aria-haspopup="dialog" aria-label="Share link: User Documentation"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"># 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) </code></pre></div> <h3 id="architecture-and-design" class="position-relative d-flex align-items-center group"> Architecture and Design <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="architecture-and-design" aria-haspopup="dialog" aria-label="Share link: Architecture and Design"> Share link </button> </h3> <h4 id="read-claudemd-first" class="position-relative d-flex align-items-center group"> Read CLAUDE.md First <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="read-claudemd-first" aria-haspopup="dialog" aria-label="Share link: Read CLAUDE.md First"> Share link </button> </h4>Before making architectural changes: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Read the project guide cat geode/CLAUDE.md # Key sections: # - Implementation Methodology (evidence-based development) # - Architecture Overview (system design) # - CANARY governance system # - Development guidelines </code></pre></div> <h4 id="consult-for-major-changes" class="position-relative d-flex align-items-center group"> Consult for Major Changes <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="consult-for-major-changes" aria-haspopup="dialog" aria-label="Share link: Consult for Major Changes"> Share link </button> </h4>For significant architectural changes: <ol> <li>Create a design document</li> <li>Open a discussion issue</li> <li>Get feedback before implementation</li> <li>Update architecture docs after approval</li> </ol> <h4 id="isoiec-390752024-compliance" class="position-relative d-flex align-items-center group"> ISO/IEC 39075:2024 Compliance <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="isoiec-390752024-compliance" aria-haspopup="dialog" aria-label="Share link: ISO/IEC 39075:2024 Compliance"> Share link </button> </h4>All GQL features must comply with the standard: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// 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 </code></pre></div> <h3 id="community-participation" class="position-relative d-flex align-items-center group"> Community Participation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="community-participation" aria-haspopup="dialog" aria-label="Share link: Community Participation"> Share link </button> </h3> <h4 id="communication-channels" class="position-relative d-flex align-items-center group"> Communication Channels <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="communication-channels" aria-haspopup="dialog" aria-label="Share link: Communication Channels"> Share link </button> </h4><ul> <li>GitLab Issues: Bug reports and feature requests</li> <li>Merge Requests: Code review and discussion</li> <li>Documentation: Improvements and corrections</li> </ul> <h4 id="code-of-conduct" class="position-relative d-flex align-items-center group"> Code of Conduct <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="code-of-conduct" aria-haspopup="dialog" aria-label="Share link: Code of Conduct"> Share link </button> </h4><ul> <li>Be respectful and professional</li> <li>Focus on technical merit</li> <li>Welcome newcomers</li> <li>Assume good intentions</li> <li>Give constructive feedback</li> </ul> <h4 id="helping-others" class="position-relative d-flex align-items-center group"> Helping Others <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="helping-others" aria-haspopup="dialog" aria-label="Share link: Helping Others"> Share link </button> </h4><ul> <li>Answer questions in issues</li> <li>Review merge requests</li> <li>Improve documentation</li> <li>Write tutorials and examples</li> <li>Report bugs clearly</li> </ul> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3> <h4 id="development-workflow" class="position-relative d-flex align-items-center group"> Development Workflow <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="development-workflow" aria-haspopup="dialog" aria-label="Share link: Development Workflow"> Share link </button> </h4><ol> <li>Pull latest changes before starting work</li> <li>Work in small increments (easier to review)</li> <li>Run tests frequently during development</li> <li>Write tests first (TDD when appropriate)</li> <li>Update docs as you go</li> <li>Commit often with clear messages</li> <li>Request review early for large changes</li> </ol> <h4 id="code-quality" class="position-relative d-flex align-items-center group"> Code Quality <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="code-quality" aria-haspopup="dialog" aria-label="Share link: Code Quality"> Share link </button> </h4><ul> <li>Follow existing code style</li> <li>Keep functions small and focused</li> <li>Avoid premature optimization</li> <li>Write self-documenting code</li> <li>Add comments for non-obvious logic</li> <li>Handle errors properly</li> </ul> <h4 id="performance-considerations" class="position-relative d-flex align-items-center group"> Performance Considerations <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-considerations" aria-haspopup="dialog" aria-label="Share link: Performance Considerations"> Share link </button> </h4><ul> <li>Profile before optimizing</li> <li>Add benchmarks for hot paths</li> <li>Document performance characteristics</li> <li>Test with production-scale data</li> <li>Monitor memory usage</li> <li>Avoid blocking operations</li> </ul> <h3 id="getting-help" class="position-relative d-flex align-items-center group"> Getting Help <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="getting-help" aria-haspopup="dialog" aria-label="Share link: Getting Help"> Share link </button> </h3> <h4 id="documentation-resources" class="position-relative d-flex align-items-center group"> Documentation Resources <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="documentation-resources" aria-haspopup="dialog" aria-label="Share link: Documentation Resources"> Share link </button> </h4><ul> <li><code>geode/CLAUDE.md</code> - Project overview and guidelines</li> <li><code>geode/docs/</code> - Comprehensive documentation</li> <li><code>README.md</code> files - Component-specific guides</li> <li>Code comments - Implementation details</li> </ul> <h4 id="asking-questions" class="position-relative d-flex align-items-center group"> Asking Questions <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="asking-questions" aria-haspopup="dialog" aria-label="Share link: Asking Questions"> Share link </button> </h4>When asking for help: <ol> <li>Search existing issues first</li> <li>Provide clear reproduction steps</li> <li>Include relevant code/configuration</li> <li>Specify your environment</li> <li>Show what you’ve tried</li> </ol> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="/tags/development/" >Development Guide</a> - Detailed development workflows</li> <li><a href="/categories/architecture/" >Architecture</a> - System architecture</li> <li><a href="/tags/gql-compliance/" >GQL Compliance</a> - ISO standard compliance</li> <li><a href="/tags/debugging/" >Testing Guide</a> - Testing strategies</li> <li><a href="/categories/performance/" >Performance</a> - Optimization guide</li> </ul>

Popular

Related Articles

Development