Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
239 lines (171 loc) · 4.68 KB

CONTRIBUTING.md

File metadata and controls

239 lines (171 loc) · 4.68 KB

Contributing to react-native-cozo

Thank you for your interest in contributing to react-native-cozo! This document provides guidelines and instructions for contributors.

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on the code, not the person

Getting Started

Prerequisites

  • Node.js 18+ (use nvm for version management)
  • React Native development environment set up
  • Xcode (for iOS development)
  • Android Studio (for Android development)

Setup

# Clone the repository
git clone https://github.com/AdebisiJoe/react-native-cozo.git
cd react-native-cozo

# Install dependencies
npm install

# Build the library
npm run build

Development Workflow

Branch Naming

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
  • test/ - Test additions/updates

Commit Messages

Follow Conventional Commits:

feat: add new feature
fix: fix bug in translator
docs: update README
test: add translator tests
refactor: improve code structure

Testing

Running Tests

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run specific test file
npm test -- --testPathPattern=translator

# Run tests in watch mode (re-runs on file changes)
npm test -- --watch

# Run only failed tests
npm test -- --onlyFailures

Test Suites

Test File Description Tests
translator.test.ts Cypher-to-Datalog translation 75+
lexer.test.ts Cypher query tokenization 50+
parser.test.ts Cypher AST parsing 60+
database.test.ts Database operations (mocked) 20+
serialization.test.ts Value serialization utilities 15+
errors.test.ts Error handling 10+

Coverage Requirements

All PRs must maintain minimum coverage thresholds:

  • Branches: 70%
  • Functions: 80%
  • Lines: 80%
  • Statements: 80%

Run npm run test:coverage to check coverage before submitting.

Writing Tests

When adding new features:

  1. Write tests first (TDD encouraged)
  2. Ensure tests are descriptive
  3. Cover edge cases
  4. Include both positive and negative test cases

Example test structure:

describe('FeatureName', () => {
  describe('methodName', () => {
    it('should handle normal case', () => {
      // Test code
    });

    it('should handle edge case', () => {
      // Test code
    });

    it('should throw error for invalid input', () => {
      expect(() => method(invalidInput)).toThrow();
    });
  });
});

Code Quality

Linting

# Run ESLint
npm run lint

# Auto-fix linting issues
npm run lint -- --fix

Type Checking

# Run TypeScript compiler
npm run typecheck

Code Style

  • Use TypeScript for all new code
  • Follow existing code patterns
  • Add JSDoc comments for public APIs
  • Keep functions small and focused
  • Avoid premature optimization

Building

# Build the library
npm run build

# Build the config plugin
npm run build:plugin

# Clean build artifacts
npm run clean

Testing on Devices

iOS

cd example
npm install
cd ios && pod install && cd ..
npx expo run:ios

Android

cd example
npm install
npx expo run:android

Pull Request Process

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: npm test
  5. Run linting: npm run lint
  6. Run type check: npm run typecheck
  7. Update documentation if needed
  8. Submit PR with clear description

PR Checklist

  • Tests pass locally
  • Coverage thresholds maintained
  • Linting passes
  • TypeScript compiles without errors
  • Documentation updated (if applicable)
  • Commit messages follow conventions
  • PR description explains the changes

Cypher Translator Guidelines

When modifying the Cypher-to-Datalog translator:

  1. Test with real CozoDB - Ensure generated Datalog actually executes
  2. Match CozoDB syntax - Use *Relation{col1, col2} format
  3. Comma separation - Datalog clauses are comma-separated
  4. Add tests - Every new feature needs corresponding tests
  5. Document limitations - Note any unsupported Cypher features

Example valid CozoDB output:

?[name, title] := *Employee{name, title, department}, department == "Engineering"

Reporting Issues

When reporting bugs:

  1. Check existing issues first
  2. Include reproduction steps
  3. Include environment info (OS, Node version, RN version)
  4. Include error messages/stack traces
  5. Include minimal code example if possible

Questions?

  • Open a GitHub issue for questions
  • Tag with question label

Thank you for contributing!