mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-09-10 04:00:35 +00:00
Mohd Kaif
a326c7d3bd
* fix: replace invalid Mintlify theme 'venus' with 'mint' * docs: replace em dashes with colons across all docs files * fix: strip UTF-8 BOM from all docs files (broke frontmatter detection)
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
---
|
|
title: "Contributing"
|
|
description: "How to contribute code, documentation, tests, and community support to Semantica."
|
|
icon: "code-pull-request"
|
|
---
|
|
|
|
Contributions of all kinds are welcome: code, documentation, tests, and community support. Every contribution is recognized in release notes and the GitHub contributors list.
|
|
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Fork the repo on GitHub, then:
|
|
git clone https://github.com/your-username/semantica.git
|
|
cd semantica
|
|
pip install -e ".[dev]"
|
|
pytest
|
|
```
|
|
|
|
New to the project? Start with [`good-first-issue`](https://github.com/semantica-agi/semantica/labels/good-first-issue) labeled tickets: they're scoped to be completable in a few hours without deep codebase knowledge.
|
|
|
|
|
|
## Ways to Contribute
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Code" icon="code">
|
|
Fix bugs, implement features, optimize performance, or add new ingestors, parsers, and exporters using the plugin registry.
|
|
</Card>
|
|
<Card title="Documentation" icon="book">
|
|
Fix typos, improve clarity, add missing examples, write tutorials, or keep the API reference accurate as modules evolve.
|
|
</Card>
|
|
<Card title="Testing" icon="flask">
|
|
Add test coverage for untested modules or edge cases, reproduce reported bugs with minimal repros, or improve cross-platform reliability.
|
|
</Card>
|
|
<Card title="Community" icon="users">
|
|
Answer questions in GitHub Issues and Discussions, review pull requests with constructive feedback, or share Semantica in blog posts and talks.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
|
|
## Development Setup
|
|
|
|
```bash
|
|
git clone https://github.com/your-username/semantica.git
|
|
cd semantica
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
**Code style tools:**
|
|
|
|
```bash
|
|
pytest # full test suite
|
|
black semantica/ tests/ # auto-format
|
|
isort semantica/ tests/ # sort imports
|
|
flake8 semantica/ # lint
|
|
```
|
|
|
|
Style conventions: **Black** for formatting, **isort** for imports, **flake8** for linting. All three run in CI.
|
|
|
|
|
|
## Reporting Issues
|
|
|
|
**Bug reports** should include:
|
|
|
|
- What happened vs. what you expected
|
|
- Minimal steps to reproduce
|
|
- Your environment: Python version, OS, Semantica version (`python -c "import semantica; print(semantica.__version__)"`)
|
|
|
|
**Feature requests** should include:
|
|
|
|
- Your concrete use case
|
|
- What you'd like Semantica to do
|
|
- Why it benefits a broad set of users, not just your specific workflow
|
|
|
|
|
|
## Pull Request Checklist
|
|
|
|
Before submitting a PR, confirm:
|
|
|
|
<Check>Tests pass locally: `pytest`</Check>
|
|
<Check>New features include documentation with working code examples</Check>
|
|
<Check>Code follows project style: Black, isort, flake8</Check>
|
|
<Check>Commit messages are clear and describe the *why*, not just the *what*</Check>
|
|
<Check>No unresolved merge conflicts</Check>
|
|
|
|
|
|
## Code of Conduct
|
|
|
|
All contributors are expected to follow the [Contributor Covenant Code of Conduct](https://github.com/semantica-agi/semantica/blob/main/CODE_OF_CONDUCT.md). Be respectful, patient, and constructive: especially toward newcomers. Report violations by opening an issue with the `[CoC]` prefix.
|
|
|
|
|
|
## Help
|
|
|
|
- [GitHub Issues](https://github.com/semantica-agi/semantica/issues)
|
|
- [GitHub Discussions](https://github.com/semantica-agi/semantica/discussions)
|
|
- [Discord](https://discord.gg/sV34vps5hH)
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Community" icon="users" href="community">
|
|
Community guidelines and values.
|
|
</Card>
|
|
<Card title="Governance" icon="scale-balanced" href="governance">
|
|
How decisions are made and the project is run.
|
|
</Card>
|
|
</CardGroup>
|