semantica/CONTRIBUTING.md

Contributing to Semantica

Thank you for your interest in contributing! Every contribution, no matter how small, is valuable. 🎉

⭐ Give us a Star • 🍴 Fork Semantica • 💬 Join our Discord

New to contributing? Start with a good first issue or join our Discord community.

---

🚀 Quick Start

1. Find a good first issue
2. Fork Semantica & clone the repository
3. Make your changes
4. Submit a pull request!

Need help? Join Discord or GitHub Discussions

---

🗂️ Working on an Existing Issue

If you want to work on an open GitHub issue, please follow these steps to keep things coordinated and avoid duplicate effort:

1. Check the issue. Look at the issue's assignees and recent comments. If someone is already actively working on it, consider a different issue or ask in the comments whether help is welcome.

2. Comment before you start. Leave a comment on the issue saying you'd like to work on it — something like "I'd like to take this on" is enough. This gives maintainers the context they need to assign the issue appropriately.

3. Wait for assignment. A maintainer will review the request and assign the issue when appropriate. Please wait for this before investing significant time in implementation, as priorities and approaches can shift.

4. Create a branch and implement. Once assigned, fork the repository (if you haven't already), create a dedicated branch, and begin your work.

   git checkout -b fix/short-description   # or feature/short-description
   

5. Open a focused PR and link the issue. When you're ready, open a pull request and reference the issue in the description (e.g., Closes #123). Keep the PR scoped to the work described in the issue.

Why this matters: Commenting before opening a PR helps maintainers track who is working on what, assign issues correctly, and prevent two contributors from solving the same problem independently. It also gives you a chance to align on the expected approach before writing code.

Not sure where to start? Try a good first issue or ask in Discord.

---

🎯 Ways to Contribute

💻 Code

What you can do:

• Fix bugs
• Add new features
• Improve code quality (add type hints, docstrings, improve error messages)
• Optimize performance

Where: semantica/ directory

Good first issues: Add docstrings, type hints, or improve error messages

---

📝 Documentation

What you can do:

• Fix typos and grammar errors
• Improve clarity and readability
• Add code examples and tutorials
• Create new cookbook notebooks
• Improve API documentation (docstrings)
• Create troubleshooting guides
• Update installation instructions
• Add missing documentation

Where: README.md, docs/, cookbook/, docstrings in code

Good first issues: Fix typos, add examples, create cookbook tutorials, improve docstrings

Documentation formatting:

• Use clear, concise language
• Include code examples where helpful
• Follow markdown best practices
• Use proper headings hierarchy
• Add links to related sections
• Include screenshots for UI-related docs

---

🧪 Testing

What you can do:

• Add unit tests
• Improve test coverage
• Add integration tests

Where: tests/ directory

Good first issues: Add tests for specific functions or classes

---

🐛 Bug Reports

What: Report bugs you find

How: Use the bug report template

Include: Description, steps to reproduce, expected vs actual behavior, environment details

---

💡 Feature Requests

What: Suggest new features or improvements

How: Use the feature request template

Include: Problem statement, proposed solution, use cases

---

🎨 Cookbook & Examples

What: Create tutorials and examples

Where: cookbook/ directory

Examples: Create new notebooks, add examples, improve existing tutorials

---

💬 Community Support

What: Help others in the community

Where: Discord, GitHub Discussions

Examples: Answer questions, review PRs, share your projects

---

🎓 Educational Content

What: Create educational materials

Examples: Blog posts, video tutorials, talks, workshops, case studies

---

🔧 Other Contributions

• Design & Graphics: Logos, diagrams, visualizations
• Tools & Integrations: CLI tools, integrations with other frameworks
• Infrastructure: CI/CD improvements, Docker optimization
• Security: Report security vulnerabilities (privately)

---

📋 Getting Started

1. Fork & Clone

First, fork Semantica on GitHub, then:

git clone https://github.com/your-username/semantica.git
cd semantica
git remote add upstream https://github.com/semantica-agi/semantica.git

2. Set Up Environment

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pre-commit install

Pinned CI dependencies

requirements-ci.txt pins every transitive dependency at exact versions so CI, security scans, and release builds install the same packages every run (the Python equivalent of explorer/package-lock.json + npm ci). It is a separate build environment: every package carries a SHA-256 hash (--generate-hashes), so installs are reproducible and supply-chain safe — never install into your local dev environment from it.

Regenerate it after changing pyproject.toml dependencies:

pip install uv==0.12.1
uv pip compile pyproject.toml --python-version 3.11 --extra all --generate-hashes -o requirements-ci.txt

The all extra is the repo's cross-platform dependency set (GPU extras like faiss-gpu/cupy are excluded and installed separately on Linux — see pyproject.toml). Keep the pinned uv version in sync with CI so regeneration is deterministic.

CI's staleness check re-resolves with the committed lockfile as a constraint and compares version lines only: upstream package releases never fail CI — the lockfile changes only when pyproject.toml changes intentionally.

CI fails if requirements-ci.txt is stale relative to pyproject.toml (the version-line comparison detects new/removed/changed dependencies).

Build-system pins: [build-system].requires is pinned to exact versions (setuptools==84.0.0, wheel==0.48.0) and release builds run python -m build --no-isolation against the lockfile — no unpinned build-time isolation anywhere.

3. Create Branch

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

4. Make Changes

• Follow code style (see below)
• Add tests for new features
• Update documentation

5. Run Checks

pytest                          # Run tests
black semantica/ tests/        # Format code
isort semantica/ tests/         # Sort imports
flake8 semantica/ tests/        # Lint

Or use pre-commit hooks: pre-commit run --all-files

6. Commit & Push

git commit -m "feat(module): add new feature"
git push origin feature/your-feature-name

Then create a pull request on GitHub!

---

📐 Code Style

We use automated tools:

Tool	Purpose	Command
Black	Code formatting	black semantica/ tests/
isort	Import sorting	isort semantica/ tests/
flake8	Style enforcement	flake8 semantica/ tests/
mypy	Type checking	mypy semantica/

Run all: black semantica/ tests/ && isort semantica/ tests/ && flake8 semantica/ tests/ && mypy semantica/

---

🧪 Testing

pytest                          # Run all tests
pytest --cov=semantica         # With coverage
pytest tests/test_file.py      # Specific file

Coverage goal: 80% minimum, 90%+ for critical modules

---

📝 Commit Messages

Use Conventional Commits:

feat(kg): add temporal graph support
fix(parse): handle empty PDF files
docs(readme): add installation guide
test(extract): add unit tests

Types: feat, fix, docs, test, refactor, perf, style, chore

---

✅ PR Checklist

Before submitting:

• Code follows style guidelines
• Tests pass locally
• New tests added (if applicable)
• Documentation updated
• Commit messages follow conventions
• No merge conflicts

---

📖 Documentation Standards

Code Documentation (Docstrings)

Format: Use Google-style docstrings

def extract_entities(text: str, model: str = "transformer") -> List[Entity]:
    """Extract named entities from text.
    
    Args:
        text: Input text to process
        model: NER model to use (default: "transformer")
    
    Returns:
        List of extracted Entity objects
    
    Raises:
        ValueError: If text is empty or model is invalid
    
    Example:
        >>> from semantica.semantic_extract import NERExtractor
        >>> ner = NERExtractor(method="ml", model="en_core_web_sm")
        >>> entities = ner.extract("Apple Inc. was founded in 1976.")
        >>> len(entities)
        2
    """

Markdown Documentation Formatting

General Guidelines:

• Use clear headings (H1 for title, H2 for main sections, H3 for subsections)
• Keep paragraphs short and focused
• Use bullet points for lists
• Add code blocks with syntax highlighting
• Include links to related documentation

Code Blocks:

• Use triple backticks with language identifier: ```python, ```bash
• Include comments in code examples
• Show expected output when helpful

Examples:

## Section Title

Brief introduction paragraph.

### Subsection

- Bullet point 1
- Bullet point 2

**Code example:**

```python
from semantica import SomeClass

instance = SomeClass()
result = instance.method()

Note: Additional context or warnings.

**Best Practices:**
- Start with an overview/introduction
- Use consistent terminology
- Include "See also" links
- Add examples for complex concepts
- Keep formatting consistent across docs

---

## 🆘 Getting Help

- 💬 [Discord](https://discord.gg/sV34vps5hH) - Real-time chat
- 💭 [GitHub Discussions](https://github.com/semantica-agi/semantica/discussions) - Q&A
- 🐛 [GitHub Issues](https://github.com/semantica-agi/semantica/issues) - Bug reports

**Before asking:** Check existing documentation, search issues/discussions, review cookbook examples

---

## 🏆 Recognition

All contributors are recognized in:
- [CONTRIBUTORS.md](CONTRIBUTORS.md)
- GitHub contributors page
- Release notes

We follow the [all-contributors](https://allcontributors.org) specification!

---

## 📜 Code of Conduct

This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). Be respectful and inclusive.

---

## 📚 Resources

- [README.md](README.md) - Project overview
- [Cookbook](cookbook/) - Tutorials and examples
- [Documentation](docs/) - Comprehensive guides

---

**Thank you for contributing!** 🚀

Every contribution matters - whether it's a single line of code, a typo fix, a helpful answer, or a bug report. We appreciate you! 🙏

⭐ **Give us a Star** • 🍴 **[Fork Semantica](https://github.com/semantica-agi/semantica/fork)** • 💬 **Join our [Discord](https://discord.gg/sV34vps5hH)**