Contributing to ai4rag¶

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

Code of Conduct¶

We are committed to fostering a welcoming and inclusive community. Please be respectful and professional in all interactions.

Ways to Contribute¶

Report Bugs¶

Found a bug? Help us fix it:

Check existing issues to avoid duplicates
Use the bug report template (coming soon)
Include:
- Detailed description
- Steps to reproduce
- Expected vs actual behavior
- Environment details (Python version, OS, etc.)
- Minimal code example

Suggest Features¶

Have an idea for a new feature? Open an issue and describe it. Proper template is coming soon...

Improve Documentation¶

Documentation improvements are always welcome:

Fix typos or unclear explanations
Add examples or tutorials
Improve API documentation
Translate documentation (future)

Submit Code¶

Ready to contribute code? Great!

Read the Development Workflow
Follow our Code Style guidelines
Write tests for your changes
Update documentation as needed

Getting Started¶

Prerequisites¶

Python >=3.12,<=3.13
Git
GitHub account

Setup Development Environment¶

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/ai4rag.git
cd ai4rag

# Add upstream remote
git remote add upstream https://github.com/IBM/ai4rag.git

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

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

# Verify installation
pytest

Development Process¶

1. Find or Create an Issue¶

Browse open issues
Comment on the issue to claim it
Get feedback from maintainers before starting

2. Create a Branch¶

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

3. Make Changes¶

Follow these practices:

One feature per PR: Keep changes focused
Write tests: All new code needs tests
Update docs: Document new features
Follow style: Use Black and Pylint
Commit often: Small, logical commits

4. Test Your Changes¶

# Run all tests
pytest

# Run with coverage
pytest --cov=ai4rag --cov-report=term-missing

# Check code style
black ai4rag/
pylint ai4rag/

# Build docs
mkdocs build --strict

5. Commit with Sign-Off¶

git add .
git commit -s -m "feat: add your feature

Detailed description of what changed and why.

Signed-off-by: Your Name <your.email@example.com>"

Developer Certificate of Origin

All commits must be signed off (-s flag) to indicate you accept the DCO.

6. Push and Create PR¶

# Push to your fork
git push origin feature/your-feature-name

# Open PR on GitHub targeting `main` branch

Pull Request Guidelines¶

PR Checklist¶

Before submitting, ensure:

PR Template¶

Use this structure:

## Description
Brief summary of changes

## Motivation
Why is this change needed?

## Changes
- Bullet point list of changes
- Another change

## Testing
How did you test this?

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guide
- [ ] All checks passing

Review Process¶

Maintainers will review within 3-5 business days
Address feedback promptly
Need at least 1 "LGTM" from maintainers
Once approved, maintainers will merge

Code Style Guidelines¶

See Code Style Guide for detailed formatting rules.

Quick Summary:

Line Length: 120 characters
Formatter: Black
Linter: Pylint
Imports: Sorted with isort
Docstrings: Google style
Type Hints: Required for public APIs

Testing Guidelines¶

See Testing Guide for comprehensive testing practices.

Quick Summary:

Write unit tests for all new functions/classes
Write integration tests for component interactions
Aim for >80% code coverage
Use pytest fixtures for common setups
Mock external dependencies

Documentation Guidelines¶

Docstring Format¶

Use NumPy docstrings:

def my_function(param1: str, param2: int) -> bool:
    """Brief description of function.

    Longer description if needed, explaining the function's
    purpose and behavior.

    Parameters
    ----------
    param1 : str
        Description of param1

    param2 : int
        Description of param2

    Returns
    -------
    bool
        Description of return value

    Raises
    ------
    ValueError
        When param2 is negative

    Examples
    --------
    >>> my_function("test", 42)
    True
    """
    pass

User Documentation¶

When adding features:

Update relevant user guide pages
Add examples to quick start if appropriate
Update API reference (auto-generated from docstrings)
Consider adding a tutorial

License¶

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

All source files must include the license header:

# -----------------------------------------------------------------------------
# Copyright IBM Corp. 2025-2026
# SPDX-License-Identifier: Apache-2.0
# -----------------------------------------------------------------------------

Developer Certificate of Origin¶

We use the Developer's Certificate of Origin 1.1 (DCO) to manage contributions.

By signing off your commits, you certify that:

You created the contribution
You have the right to submit it
You submit it under the Apache 2.0 license
You understand it will be publicly available

Sign commits with:

git commit -s

Getting Help¶

Questions: Open a discussion
Stuck?: Comment on your PR or issue

Thank you for contributing to ai4rag!