mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-08-30 04:40:16 +00:00
KaifAhmad1
ba04b0bbc6
- 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
392 lines
7.7 KiB
Markdown
392 lines
7.7 KiB
Markdown
# 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
|
|
|
|
```
|
|
<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
|
|
|
|
1. **Update your fork**:
|
|
```bash
|
|
git fetch upstream
|
|
git checkout main
|
|
git merge upstream/main
|
|
```
|
|
|
|
2. **Create a feature branch**:
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
# or
|
|
git checkout -b fix/bug-description
|
|
```
|
|
|
|
3. **Make your changes** and commit following our conventions
|
|
|
|
4. **Run all checks**:
|
|
```bash
|
|
pytest
|
|
black semantica/ tests/
|
|
isort semantica/ tests/
|
|
flake8 semantica/ tests/
|
|
mypy semantica/
|
|
```
|
|
|
|
5. **Push to your fork**:
|
|
```bash
|
|
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
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
Example:
|
|
```python
|
|
def extract_entities(
|
|
text: str,
|
|
model: str = "transformer",
|
|
confidence_threshold: float = 0.7
|
|
) -> List[Entity]:
|
|
"""Extract named entities from text.
|
|
|
|
Args:
|
|
text: Input text to process
|
|
model: NER model to use (default: "transformer")
|
|
confidence_threshold: Minimum confidence score (default: 0.7)
|
|
|
|
Returns:
|
|
List of extracted Entity objects
|
|
|
|
Raises:
|
|
ValueError: If text is empty or model is invalid
|
|
|
|
Example:
|
|
>>> ner = NamedEntityRecognizer()
|
|
>>> entities = ner.extract("Apple Inc. was founded in 1976.")
|
|
>>> len(entities)
|
|
2
|
|
"""
|
|
...
|
|
```
|
|
|
|
### Documentation Files
|
|
|
|
- Update relevant documentation in `docs/`
|
|
- Add examples to cookbook if applicable
|
|
- Update API reference if adding new public APIs
|
|
- Keep README.md up to date
|
|
|
|
## Types of Contributions
|
|
|
|
### Code Contributions
|
|
|
|
- Bug fixes
|
|
- New features
|
|
- Performance improvements
|
|
- Refactoring
|
|
|
|
### Documentation Contributions
|
|
|
|
- Fix typos and grammar
|
|
- Improve clarity
|
|
- Add examples
|
|
- Create tutorials
|
|
- Translate documentation
|
|
|
|
### Testing Contributions
|
|
|
|
- Add test coverage
|
|
- Improve test quality
|
|
- Add integration tests
|
|
- Performance benchmarks
|
|
|
|
### Other Contributions
|
|
|
|
- Answer questions in discussions
|
|
- Help with issues
|
|
- Review pull requests
|
|
- Share use cases
|
|
- Report bugs
|
|
- Suggest features
|
|
|
|
## Getting Help
|
|
|
|
### Communication Channels
|
|
|
|
- **GitHub Discussions**: General questions and discussions
|
|
- **GitHub Issues**: Bug reports and feature requests
|
|
- **Discord**: Real-time chat and community support
|
|
|
|
### Before Asking for Help
|
|
|
|
1. Check existing documentation
|
|
2. Search GitHub issues and discussions
|
|
3. Review code examples in cookbook
|
|
4. Check FAQ in documentation
|
|
|
|
### Asking Good Questions
|
|
|
|
- Provide context and environment details
|
|
- Include code examples
|
|
- Show what you've tried
|
|
- Include error messages and logs
|
|
- Be specific about what you need
|
|
|
|
## Recognition
|
|
|
|
Contributors are recognized in:
|
|
- [CONTRIBUTORS.md](CONTRIBUTORS.md)
|
|
- GitHub contributors page
|
|
- Release notes for significant contributions
|
|
|
|
Thank you for contributing to Semantica! 🎉
|
|
|