mirror of https://github.com/semantica-agi/semantica.git synced 2026-08-29 04:26:20 +00:00

Files

T

KaifAhmad1 ba04b0bbc6 docs: remove email addresses and add discussion templates

- Remove email addresses from support, security, contributing, and community docs
- Replace email contacts with GitHub Issues and Security Advisories
- Add discussion templates for Q&A, Ideas, Showcase, and General discussions
- Update SUPPORT.md with Discussions section

2025-12-03 11:19:07 +05:30

7.7 KiB

Raw Blame History

Contributing to Semantica

Thank you for your interest in contributing to Semantica! This document provides guidelines and instructions for contributing to the project.

Code of Conduct
Getting Started
Development Setup
Code Style Guidelines
Testing Requirements
Commit Message Conventions
Pull Request Process
Documentation Standards
Types of Contributions
Getting Help

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/your-username/semantica.git
cd semantica

Add the upstream remote:

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

Create a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the project in editable mode with dev dependencies:
```
pip install -e ".[dev]"
```
Install pre-commit hooks:
```
pre-commit install
```

Verify Installation

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)
```
black semantica/
```
isort: Import sorting
```
isort semantica/
```

Linting

flake8: Style guide enforcement
```
flake8 semantica/
```
mypy: Static type checking
```
mypy semantica/
```

Running All Checks

# 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):

pre-commit run --all-files

Testing Requirements

Running Tests

# 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:

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 specification:

Format

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

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks
perf: Performance improvements
ci: CI/CD changes

Examples

feat(kg): add temporal graph support

Add support for temporal knowledge graphs with version tracking
and time-based queries.

Closes #123

fix(parse): handle empty PDF files gracefully

Previously, empty PDF files would cause a crash. Now they return
an empty document with appropriate warnings.

Fixes #456

Pull Request Process

Before Submitting

Update your fork:

git fetch upstream
git checkout main
git merge upstream/main

Create a feature branch:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Make your changes and commit following our conventions

Run all checks:

pytest
black semantica/ tests/
isort semantica/ tests/
flake8 semantica/ tests/
mypy semantica/

Push to your fork:

git push origin feature/your-feature-name

PR Checklist

Code follows style guidelines
Tests pass locally
New tests added for new features
Documentation updated
Commit messages follow conventions
No merge conflicts
PR description is clear and complete

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Closes #123
Related to #456

## Testing
- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Updated existing tests

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

Documentation Standards

Code Documentation

Use Google-style docstrings
Include type hints
Document all public functions and classes
Include examples for complex functions