Contributing Guide

Contributing Guide

Development Setup

Prerequisites

• Python 3.10+
• Node.js 20+ (for GUI)
• uv package manager (recommended)

Clone and Install

git clone https://github.com/maref-org/maref.git
cd maref
pip install -e ".[dev]"

Run Tests

# Full test suite
pytest tests/ -v --cov=src/maref --cov-report=term-missing

# Security-specific tests
pytest tests/security/ -v

# Type checking
mypy src/

# Linting
ruff check src/

---

Code Style

Python

• PEP 8 style guide
• ruff for linting
• mypy strict mode for type checking

TypeScript

• ESLint + TypeScript strict mode
• React 19+ with hooks

---

Commit Convention

We use Conventional Commits:

feat(module): add new feature
fix(module): fix bug
docs(module): update documentation
chore(module): maintenance task
test(module): add tests
refactor(module): code refactoring

---

Pull Request Process

1. Fork the repository
2. Create a branch from main (git checkout -b feature/my-feature)
3. Make changes following code style guidelines
4. Run tests — all must pass
5. Commit with conventional commit message
6. Push to your fork
7. Open a PR with a clear description

PR Requirements

• All tests pass (pytest tests/ -v --cov)
• Type checking passes (mypy src/)
• Linting passes (ruff check src/)
• Code follows project style
• Self-review completed
• Documentation updated if needed
• Tests added for new functionality

Merge Requirements

Branch	Review	CI	Auto-merge
main	≥1 PMC approval	All green	No
develop	≥1 core contributor	All green	Docs only
feature/*	None required	Recommended	No

---

CLA (Contributor License Agreement)

All external contributors must sign our CLA before their first PR is merged.

1. Open a PR
2. The CLA bot will comment with a signing link
3. Sign the ICLA (Individual Contributor License Agreement)
4. Your PR will be unblocked

---

Reporting Security Issues

Do not open a public issue for security vulnerabilities.

Please report security issues via SECURITY.md.

---

← Back to Home