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

Files

T

Ikko Eltociear Ashimine c0a051903f docs: update CONTRIBUTING.md (#976 )

fix GiHub link.

2026-08-14 11:51:16 +05:30

11 KiB

Raw Blame History

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

Find a good first issue
Fork Semantica & clone the repository
Make your changes
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:

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.
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.
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.
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
```
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

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)**

11 KiB Raw Blame History

Contributing to Semantica

🚀 Quick Start

🗂️ Working on an Existing Issue

🎯 Ways to Contribute

💻 Code

📝 Documentation

🧪 Testing

🐛 Bug Reports

💡 Feature Requests

🎨 Cookbook & Examples

💬 Community Support

🎓 Educational Content

🔧 Other Contributions

📋 Getting Started

1. Fork & Clone

2. Set Up Environment

3. Create Branch

4. Make Changes

5. Run Checks

6. Commit & Push

📐 Code Style

🧪 Testing

📝 Commit Messages

✅ PR Checklist

📖 Documentation Standards

Code Documentation (Docstrings)

Markdown Documentation Formatting

11 KiB

Raw Blame History