Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
292 lines (224 loc) · 5.91 KB

CONTRIBUTING.md

File metadata and controls

292 lines (224 loc) · 5.91 KB
Raw

Contributing to SynthoraAI OCR

Thank you for your interest in contributing to the SynthoraAI OCR system! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project follows the same code of conduct as the main SynthoraAI project. Please be respectful and constructive in all interactions.

Getting Started

  1. Fork the Repository

    # Click 'Fork' on GitHub
git clone https://github.com/YOUR_USERNAME/Optical-Character-Recognition.git
cd Optical-Character-Recognition

  2. Set Up Development Environment

    ./scripts/install.sh

  3. Create a Branch

    git checkout -b feature/your-feature-name

Development Setup

Python Backend

cd ocr_backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies

Node.js API

cd ocr_api
npm install
npm install -D nodemon jest  # Development dependencies

Environment Configuration

Create a .env file from .env.example and configure for development:

cp .env.example .env
# Edit .env with your local configuration

Making Changes

Branch Naming Convention

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Adding or updating tests

Commit Message Format

Follow conventional commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance

Example:

feat(ocr): add support for TrOCR handwriting recognition

Implement TrOCR engine integration for handwritten text recognition.
Includes preprocessing pipeline and model loading.

Closes #123

Pull Request Process

  1. Update Documentation

    • Update README.md if needed
    • Add/update code comments
    • Update API documentation

  2. Write Tests

    • Add unit tests for new features
    • Update existing tests if needed
    • Ensure all tests pass

  3. Run Linters

    # Python
cd ocr_backend
black .
flake8 .

# Node.js
cd ocr_api
npm run lint
npm run format

  4. Create Pull Request

    • Fill out the PR template
    • Link related issues
    • Request review from maintainers

  5. Address Review Comments

    • Make requested changes
    • Reply to comments
    • Request re-review

Coding Standards

Python

  • Follow PEP 8 style guide
  • Use type hints
  • Write docstrings for functions and classes
  • Maximum line length: 100 characters

Example:

def process_image(
    image_data: bytes,
    engine: str = "tesseract",
    languages: List[str] = None
) -> Dict[str, Any]:
    """
    Process image with OCR engine.

    Args:
        image_data: Input image bytes
        engine: OCR engine name
        languages: List of language codes

    Returns:
        Dict containing extracted text and metadata

    Raises:
        ValueError: If engine is not supported
    """
    pass

JavaScript/Node.js

  • Use ES6+ features
  • Use async/await for asynchronous code
  • Write JSDoc comments
  • Use Prettier for formatting

Example:

/**
 * Process image with OCR
 * @param {Buffer} imageBuffer - Image data
 * @param {string} engine - OCR engine name
 * @returns {Promise<Object>} OCR result
 */
async function processImage(imageBuffer, engine = 'tesseract') {
  // Implementation
}

Testing

Running Tests

# Python backend
cd ocr_backend
pytest tests/ -v
pytest tests/ --cov=.  # With coverage

# Node.js API
cd ocr_api
npm test
npm run test:coverage

Writing Tests

Python (pytest):

import pytest
from processors.ocr_processor import OCRProcessor

def test_ocr_processor_initialization():
    processor = OCRProcessor()
    assert processor is not None
    assert len(processor.get_available_engines()) > 0

@pytest.mark.asyncio
async def test_image_processing():
    processor = OCRProcessor()
    # Mock image data
    result = await processor.process_image(
        image_data=b'...',
        engine='tesseract'
    )
    assert 'text' in result
    assert 'confidence' in result

JavaScript (Jest):

const request = require('supertest');
const app = require('../index');

describe('OCR API', () => {
  test('GET /health returns 200', async () => {
    const response = await request(app).get('/health');
    expect(response.statusCode).toBe(200);
    expect(response.body.status).toBe('healthy');
  });

  test('POST /api/ocr/image processes image', async () => {
    const response = await request(app)
      .post('/api/ocr/image')
      .attach('file', 'tests/fixtures/test.jpg')
      .field('engine', 'tesseract');

    expect(response.statusCode).toBe(200);
    expect(response.body.success).toBe(true);
  });
});

Documentation

Code Documentation

  • All public functions must have docstrings/JSDoc
  • Include parameter types and return types
  • Document exceptions/errors
  • Add usage examples for complex functions

API Documentation

Update API documentation when adding/changing endpoints:

  • Request/response formats
  • Status codes
  • Example requests
  • Error responses

README Updates

Update README.md for:

  • New features
  • Changed dependencies
  • New configuration options
  • New API endpoints

Questions?

  • Open an issue for bugs or feature requests
  • Join discussions on GitHub Discussions
  • Contact maintainers: hoangson091104@gmail.com

Thank you for contributing to SynthoraAI OCR! 🎉