Contributing to OntoCast

We welcome contributions! This document provides guidelines for contributing to the project.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Install development dependencies:

   uv sync --all-extras
   

4. Install pre-commit hooks:

   pre-commit install
   

Development Workflow

1. Create a branch for your feature or bugfix:

   git checkout -b feature/your-feature-name
   

2. Run tests:

   bash -c 'set -a; source .env; set +a; uv run pytest test'
   

   Export variables from .env before pytest when integration tests need external services (QDRANT_URI, FUSEKI_URI, etc.).

3. Build docs locally after doc or API changes:

   uv run mkdocs build
   

4. Commit, push, and open a Pull Request

Documentation

• User-facing guides live in docs/ (MkDocs). Update mkdocs.yml nav when adding pages.
• API reference under docs/reference/ is generated at build time by docs/gen_pages.py from Python modules. Do not commit hand-written reference stubs; add docstrings in code instead.
• Workflow diagrams in docs/assets/graph* are generated by uv run plot-graph (requires optional pygraphviz for PNG/SVG).
• Keep README.md concise; put detailed explanations in docs/.
• Update CHANGELOG.md for user-visible changes.

Code Style

• Python 3.12+ with type hints everywhere
• Follow PEP 8; use pydantic.BaseModel for structured data in the library
• Google-style docstrings on public APIs
• Match existing naming and patterns in the module you edit

Pull Request Checklist

1. Tests pass (uv run pytest test)
2. Docs build (uv run mkdocs build) when docs or public API changed
3. CHANGELOG.md updated for notable changes
4. Clear PR description with problem and solution

Reporting Issues

Include Python version, OntoCast version, steps to reproduce, expected vs actual behavior, and relevant logs.