Welcome Contributors!

Thank you for your interest in contributing to JARVIS! This guide will help you get started.

Code of Conduct

Be respectful, inclusive, and professional. We’re building a community where everyone feels welcome to contribute.

Getting Started

Fork the repository

Fork the JARVIS repository to your GitHub account.

Clone your fork

git clone https://github.com/YOUR_USERNAME/jarvis.git
cd jarvis

Set up development environment

Follow the Local Setup guide to configure your environment.

Create a branch

git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions/improvements

Development Workflow

Making Changes

Write your code following the Code Style guidelines
Add tests for new functionality
Update documentation if needed
Run tests to ensure everything passes
Commit your changes with clear commit messages

Running Tests

Before committing, ensure all tests pass:

cd backend
pytest

Check code style:

ruff check .
ruff format .

Commit Messages

Use clear, descriptive commit messages following Conventional Commits:

feat: add Twitter agent for social media research
fix: handle timeout in PimEyes search
docs: update configuration guide
refactor: simplify agent orchestration logic
test: add tests for face detection

Format:

<type>: <description>

[optional body]

[optional footer]

Types:

feat - New feature
fix - Bug fix
docs - Documentation changes
refactor - Code refactoring
test - Test additions/improvements
chore - Build process, dependencies
perf - Performance improvements

Code Style

Python (Backend)

JARVIS uses Ruff for linting and formatting:

# Check code
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

Key style guidelines:

# Good: Type hints on all functions
async def detect_faces(
    image_bytes: bytes,
    min_confidence: float = 0.7,
) -> list[DetectedFace]:
    """Detect faces in an image.
    
    Args:
        image_bytes: Raw image data
        min_confidence: Minimum detection confidence (0.0-1.0)
    
    Returns:
        List of detected faces with bounding boxes
    """
    # Implementation...

# Good: Descriptive variable names
face_detection_result = await detector.detect_faces(image)

# Bad: Unclear variable names
r = await d.detect(i)

# Good: Use f-strings
logger.info(f"Detected {len(faces)} faces in {duration:.2f}s")

# Bad: % formatting
logger.info("Detected %d faces" % len(faces))

# Good: Use pathlib for file paths
from pathlib import Path
config_file = Path("config") / "settings.json"

# Bad: String concatenation
config_file = "config/" + "settings.json"

TypeScript (Frontend)

Follow Next.js and React best practices:

// Good: Functional components with TypeScript
interface PersonCardProps {
  person: Person;
  onSelect: (id: string) => void;
}

export function PersonCard({ person, onSelect }: PersonCardProps) {
  return (
    <div onClick={() => onSelect(person.id)}>
      {person.name}
    </div>
  );
}

// Good: Use hooks
import { useQuery } from "convex/react";

export function Corkboard() {
  const persons = useQuery(api.persons.list);
  
  if (!persons) return <Loading />;
  
  return <div>{/* ... */}</div>;
}

Testing Guidelines

Writing Tests

Every new feature should include tests:

tests/test_new_feature.py

import pytest
from mymodule import my_function

@pytest.mark.asyncio
async def test_my_function_success():
    """Test my_function with valid input."""
    result = await my_function(valid_input)
    assert result.success is True
    assert result.value == expected_value

@pytest.mark.asyncio
async def test_my_function_handles_errors():
    """Test my_function handles errors gracefully."""
    with pytest.raises(ValueError):
        await my_function(invalid_input)

Test Coverage

Maintain at least 70% code coverage:

pytest --cov=. --cov-report=html
open htmlcov/index.html

Focus coverage on:

Core pipeline logic
Agent orchestration
API endpoints
Error handling

Pull Request Process

Before Submitting

Submitting a PR

Push your branch

git push origin feature/your-feature-name

Create a pull request on GitHub

Fill out the PR template:

## Description
Brief description of your changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
Describe how you tested your changes

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] Code follows style guidelines

Request review from maintainers

PR Review Process

Maintainers will review your PR and may:

Request changes
Ask questions
Suggest improvements
Approve and merge

Be responsive to feedback and make requested changes promptly.

Documentation

When to Update Docs

Update documentation when you:

Add a new feature
Change API endpoints
Modify configuration options
Add new environment variables
Change deployment procedures

Documentation Structure

docs/
├── getting-started/       # User-facing guides
├── core-concepts/         # Architecture & concepts
├── api-reference/         # API documentation
├── development/           # Developer guides
└── deployment/            # Deployment guides

Writing Documentation

Use clear, concise language:

# Good: Clear, actionable
## Configure Laminar Tracing

Set your Laminar API key in `.env`:
```bash
LMNR_PROJECT_API_KEY=your-key

Bad: Vague, passive

Laminar

Laminar can be configured by setting the appropriate environment variable.

## Areas for Contribution

### High Priority

<CardGroup cols={2}>
  <Card title="Agent Improvements" icon="robot">
    - Add more social platforms (Facebook, GitHub)
    - Improve LinkedIn data extraction
    - Optimize agent prompts
  </Card>
  
  <Card title="Performance" icon="gauge">
    - Reduce latency in capture pipeline
    - Optimize LLM calls
    - Implement caching strategies
  </Card>
  
  <Card title="Testing" icon="flask">
    - Add integration tests
    - Improve test coverage
    - Add performance benchmarks
  </Card>
  
  <Card title="Documentation" icon="book">
    - Add more code examples
    - Improve API reference
    - Create video tutorials
  </Card>
</CardGroup>

### Good First Issues

Looking for a place to start? Check for issues labeled:
- `good-first-issue` - Good for newcomers
- `help-wanted` - Community help needed
- `documentation` - Documentation improvements

## Community

### Getting Help

- **GitHub Discussions** - Ask questions, share ideas
- **Issues** - Report bugs, request features
- **Pull Requests** - Discuss code changes

### Communication Guidelines

- Be respectful and constructive
- Provide context and examples
- Search existing issues before creating new ones
- Use clear, descriptive titles
- Include code snippets when relevant

## Development Tips

### Debugging

```python
# Use loguru for debugging
from loguru import logger

logger.debug("Variable value: {}", variable)
logger.info("Processing started")
logger.error("Error occurred: {}", error)

# Add breakpoints with debugger
import pdb; pdb.set_trace()

Testing Locally

Test with mock services:

from unittest.mock import Mock

# Mock external API
mock_client = Mock()
mock_client.search.return_value = {"results": [...]}

# Test with mock
result = await agent.research(mock_client)
assert result["name"] == "Expected Name"

Environment Variables

Use different .env files for testing:

# Development
cp .env.example .env

# Testing
cp .env.example .env.test
SPECTER_ENV=test pytest

Recognition

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
Project README

Significant contributions may earn:

Maintainer status
Special acknowledgment
Invitation to core team

Questions?

If you have questions about contributing:

Check this documentation
Search existing GitHub issues
Ask in GitHub Discussions
Open a new issue with the question label

We’re here to help!

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank You!

Every contribution, no matter how small, makes JARVIS better. Thank you for being part of our community! 🚀

Local Setup

Set up your development environment

Testing

Write tests for your contributions

Architecture

Understand the system design

API Reference

Explore the API

Setup

Advanced

Contributing

Contributing Guidelines

Welcome Contributors!

Code of Conduct

Getting Started

Development Workflow

Making Changes

Running Tests

Commit Messages

Code Style

Python (Backend)

TypeScript (Frontend)

Testing Guidelines

Writing Tests

Test Coverage

Pull Request Process

Before Submitting

Submitting a PR

PR Review Process

Documentation

When to Update Docs

Documentation Structure

Writing Documentation

Bad: Vague, passive

Laminar

Testing Locally

Environment Variables

Recognition

Questions?

License

Thank You!

Local Setup

Testing

Architecture

API Reference

Build docs developers (and LLMs) love

Setup

Advanced

Contributing

​Welcome Contributors!

​Code of Conduct

​Getting Started

​Development Workflow

​Making Changes

​Running Tests

​Commit Messages

​Code Style

​Python (Backend)

​TypeScript (Frontend)

​Testing Guidelines

​Writing Tests

​Test Coverage

​Pull Request Process

​Before Submitting

​Submitting a PR

​PR Review Process

​Documentation

​When to Update Docs

​Documentation Structure

​Writing Documentation

​Bad: Vague, passive

​Laminar

​Testing Locally

​Environment Variables

​Recognition

​Questions?

​License

​Thank You!

Local Setup

Testing

Architecture

API Reference

Build docs developers (and LLMs) love

Welcome Contributors!

Code of Conduct

Getting Started

Development Workflow

Making Changes

Running Tests

Commit Messages

Code Style

Python (Backend)

TypeScript (Frontend)

Testing Guidelines

Writing Tests

Test Coverage

Pull Request Process

Before Submitting

Submitting a PR

PR Review Process

Documentation

When to Update Docs

Documentation Structure

Writing Documentation

Bad: Vague, passive

Laminar

Testing Locally

Environment Variables

Recognition

Questions?

License

Thank You!