# Contributing to Semantica Thank you for your interest in contributing to Semantica! This document provides guidelines and instructions for contributing to the project. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [Getting Started](#getting-started) - [Development Setup](#development-setup) - [Code Style Guidelines](#code-style-guidelines) - [Testing Requirements](#testing-requirements) - [Commit Message Conventions](#commit-message-conventions) - [Pull Request Process](#pull-request-process) - [Documentation Standards](#documentation-standards) - [Types of Contributions](#types-of-contributions) - [Getting Help](#getting-help) ## Code of Conduct This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers. ## Getting Started 1. **Fork the repository** on GitHub 2. **Clone your fork** locally: ```bash git clone https://github.com/your-username/semantica.git cd semantica ``` 3. **Add the upstream remote**: ```bash git remote add upstream https://github.com/Hawksight-AI/semantica.git ``` ## Development Setup ### Prerequisites - Python 3.8 or higher (3.9+ recommended) - pip package manager - Git ### Installation 1. **Create a virtual environment** (recommended): ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 2. **Install the project in editable mode with dev dependencies**: ```bash pip install -e ".[dev]" ``` 3. **Install pre-commit hooks**: ```bash pre-commit install ``` ### Verify Installation ```bash python -c "import semantica; print(semantica.__version__)" pytest --version black --version ``` ## Code Style Guidelines We use several tools to maintain code quality and consistency: ### Formatting - **Black**: Code formatting (line length: 88) ```bash black semantica/ ``` - **isort**: Import sorting ```bash isort semantica/ ``` ### Linting - **flake8**: Style guide enforcement ```bash flake8 semantica/ ``` - **mypy**: Static type checking ```bash mypy semantica/ ``` ### Running All Checks ```bash # Format code black semantica/ tests/ # Sort imports isort semantica/ tests/ # Lint flake8 semantica/ tests/ # Type check mypy semantica/ ``` Or use pre-commit hooks (automatically runs on commit): ```bash pre-commit run --all-files ``` ## Testing Requirements ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=semantica --cov-report=html # Run specific test file pytest tests/test_specific.py # Run with verbose output pytest -v ``` ### Test Coverage - Minimum coverage: **80%** - Critical modules: **90%+** - Coverage reports are generated in `htmlcov/` ### Writing Tests - Follow pytest conventions - Use descriptive test names - Include docstrings for complex tests - Test both success and failure cases - Use fixtures for common setup Example: ```python def test_entity_extraction(): """Test basic entity extraction functionality.""" from semantica.semantic_extract import NamedEntityRecognizer ner = NamedEntityRecognizer() entities = ner.extract("Apple Inc. was founded by Steve Jobs.") assert len(entities) > 0 assert any(e.text == "Apple Inc." for e in entities) ``` ## Commit Message Conventions We follow [Conventional Commits](https://www.conventionalcommits.org/) specification: ### Format ``` ():