Contributing to OpenComplai¶

Thank you for your interest in contributing! OpenComplai is an open-source project and we welcome contributions from everyone.

Ways to Contribute¶

🐛 Report Bugs¶

Found a bug? Open an issue with: - Description of the bug - Steps to reproduce - Expected vs actual behavior - Your environment (OS, Python/Node version)

💡 Suggest Features¶

Have an idea? Open a discussion or create an issue with: - Use case and motivation - Proposed solution - Alternative solutions considered

📝 Write Documentation¶

Fix typos or improve clarity
Add examples or tutorials
Improve API documentation
Translate to other languages (planned)

🔧 Submit Code¶

Bug fixes
New features
Performance improvements
Refactoring

🧪 Write Tests¶

Unit tests
Integration tests
End-to-end tests
Test coverage improvements

🎨 Improve Design¶

UI/UX improvements
Accessibility enhancements
Performance optimizations
Architecture improvements

Getting Started¶

1. Development Setup ¶

Set up your local development environment: - Fork and clone the repository - Install dependencies - Set up pre-commit hooks - Run tests locally

2. Coding Standards ¶

Follow our code standards: - Python: PEP 8 with type hints - JavaScript: Prettier + ESLint - Documentation: Markdown best practices - Commit messages: Conventional commits

3. Testing ¶

Write and run tests: - Unit tests with pytest (Python) / Jest (JS) - Integration tests - Coverage requirements - CI/CD test pipeline

4. Code Review ¶

Submit and review code: - Create pull request - Request code review - Address feedback - Merge to main

5. Release Process ¶

How releases work: - Semantic versioning - Changelog updates - Tag releases - Publish packages

Contribution Workflow¶

1. Fork & Clone¶

# Fork the repository on GitHub

# Clone your fork
git clone https://github.com/YOUR_USERNAME/opencomplai.git
cd opencomplai

# Add upstream remote
git remote add upstream https://github.com/Checkref-co/opencomplai.git

2. Create Feature Branch¶

# Update main
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/short-description
# or for bugs: bug/issue-number-description
# or for docs: docs/description

3. Make Changes¶

# Install development dependencies
pip install -e ".[dev]"  # Python
npm install              # JavaScript

# Make your changes and test locally
python -m pytest         # Run tests
npm test                 # Run JS tests

4. Commit Changes¶

# Follow conventional commit format
git add .
git commit -m "feat: add new feature

Optional longer description explaining the change.
Closes #123"

# Good commit messages:
# feat: add document export to PDF
# fix: handle rate limit errors correctly
# docs: improve authentication guide
# test: add test for document creation
# refactor: simplify document processing

5. Push & Create PR¶

# Push to your fork
git push origin feature/short-description

# Create pull request on GitHub
# Fill in the PR template with:
# - Description of changes
# - Related issues (Closes #123)
# - Screenshots (if UI changes)
# - Test plan

6. Address Feedback¶

# Make requested changes
git add .
git commit -m "refactor: address review feedback"
git push origin feature/short-description

# GitHub will update the PR automatically

7. Merge¶

Once approved: - Maintainers will merge to main - Your feature goes into next release - You're now a contributor! 🎉

Development Quick Start¶

Python Development¶

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

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

# Run tests
pytest

# Run linters
black .          # Format code
mypy .           # Type checking
ruff check .     # Linting

# Build locally
python -m build

JavaScript Development¶

# Install dependencies
npm install

# Run tests
npm test

# Run linters
npm run lint
npm run format

# Build
npm run build

Code Standards Summary¶

Python¶

Python 3.9+
PEP 8 style (enforced by Black)
Type hints required
Docstrings for public functions
Tests required for new features

JavaScript¶

TypeScript preferred
Prettier formatting
ESLint checks
JSDoc comments
Tests required for new features

Documentation¶

Markdown format
Clear and concise
Links to related docs
Code examples
Keep up to date

Testing Requirements¶

Coverage¶

Minimum 80% code coverage
New features require tests
Bug fixes should include regression tests

Test Files¶

src/            ← Source code
src/foo.py      ← Module
tests/
tests/test_foo.py  ← Test file (parallel structure)

Running Tests¶

# Python
pytest                    # Run all
pytest tests/test_foo.py  # Run specific file
pytest -cov              # With coverage

# JavaScript
npm test                 # Run all
npm test -- test_foo.js  # Run specific file
npm test -- --coverage   # With coverage

Pull Request Checklist¶

Before submitting a PR:

Feature branch created from main
Code follows style guidelines
Tests added/updated and passing
Documentation updated
Commit messages follow convention
No breaking changes (or documented)
Changelog updated (if applicable)
Changes reviewed locally

Community Guidelines¶

Be Respectful¶

Treat everyone with respect
Assume good intentions
Provide constructive feedback

Be Helpful¶

Help others learn
Answer questions patiently
Share knowledge

Be Constructive¶

Focus on ideas, not people
Provide specific feedback
Suggest improvements

Be Inclusive¶

Welcome diverse perspectives
Be mindful of language
Support new contributors

Communication Channels¶

Issues: Bug reports and feature requests
Discussions: Ideas, questions, announcements
Pull Requests: Code changes and reviews
Email: open@checkref.co (for private concerns)

Recognition¶

All contributors are recognized: - In CONTRIBUTORS.md - In release notes - On our website