Skip to content

contributing.md

Latest commit

 

History

History
341 lines (243 loc) · 9.77 KB

contributing.md

File metadata and controls

341 lines (243 loc) · 9.77 KB
Raw

Developer Guide

How to set up your development environment, create feature branches, and submit pull requests for Ask RITA.

Prerequisites

  • Python 3.11+ (3.11, 3.12, 3.13, or 3.14)
  • Poetry for dependency management
  • Git for version control
  • Docker (optional, for cross-version compatibility testing)

Development Setup

1. Clone the Repository

git clone https://github.com/cvs-health/askRITA.git
cd askRITA

2. Install Poetry

pip install poetry

3. Install Dependencies

poetry install --with dev,test

This installs all production, development, and test dependencies in a virtual environment managed by Poetry.

To also install optional export dependencies (PPTX, PDF, Excel):

poetry install --with dev,test --extras exports

4. Activate the Virtual Environment

poetry shell

Or prefix commands with poetry run:

poetry run pytest tests/ -v

5. Install Pre-Commit Hooks

pre-commit install

Pre-commit hooks automatically run Black (formatting), isort (import sorting), and flake8 (linting) on every commit.

6. Verify Setup

poetry run pytest tests/ -v

All tests should pass before you begin development.

Branch Workflow

Ask RITA uses a feature-branch workflow. All changes go through pull requests — direct pushes to main are not allowed.

flowchart LR
    A[main] -->|checkout| B[feature branch]
    B -->|code + test| C[commit]
    C -->|push| D[pull request]
    D -->|CI pipeline| E{checks pass?}
    E -->|no| C
    E -->|yes| F[code review]
    F -->|approved| G[merge to main]
    G -->|auto| H[publish pipeline]
    style A fill:#2F5496,color:#fff
    style B fill:#00897B,color:#fff
    style C fill:#4CAF50,color:#fff
    style D fill:#4CAF50,color:#fff
    style E fill:#FF9800,color:#fff
    style F fill:#4CAF50,color:#fff
    style G fill:#4CAF50,color:#fff
    style H fill:#7B1FA2,color:#fff
Loading

Creating a Feature Branch

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Use a descriptive branch name that reflects the change:

Branch Type Naming Convention Example
New feature feature/description feature/snowflake-streaming
Bug fix fix/description fix/bigquery-auth-timeout
Documentation docs/description docs/add-bedrock-guide
Refactor refactor/description refactor/schema-decorators
Test test/description test/nosql-edge-cases

Making Changes

  1. Write your code following the project's code style
  2. Add or update tests for any new or changed functionality
  3. Run the full test suite to verify nothing is broken
poetry run pytest tests/ -v
  1. Check code coverage to ensure new code is tested:
poetry run pytest tests/ --cov=askrita --cov-report=term-missing

Committing Changes

git add .
git commit -m "Add Snowflake streaming support for large result sets"

Write clear, descriptive commit messages:

  • Use imperative mood: "Add feature" not "Added feature"
  • First line should be a concise summary (50-72 characters)
  • Include context in the body if the change is complex

Pre-commit hooks will automatically format your code. If the hooks modify files, stage the changes and commit again:

git add .
git commit -m "Add Snowflake streaming support for large result sets"

Pushing Your Branch

git push origin feature/your-feature-name

Submitting a Pull Request

1. Create the Pull Request

Push your branch and open a pull request against main. Include:

  • Title: Clear summary of the change
  • Description: What was changed and why
  • Testing: How the change was verified
  • Related issues: Link any relevant issue numbers

2. CI Pipeline

When you open a pull request, the CI pipeline runs automatically:

Step What It Does
Lint Black, isort, Flake8, Mypy — formatting and type safety
Security Bandit (SAST) and Safety (dependency CVEs)
Test matrix Full pytest suite across Python 3.11, 3.12, 3.13, and 3.14 — 80% coverage enforced
Build Verifies the package builds correctly (wheel + sdist)

The PR cannot be merged until all CI checks pass (CI ✓ status check).

3. Code Review

  • At least one code owner must approve the PR
  • Address all review feedback with additional commits on the same branch
  • Re-request review after making changes

4. Merge

Once approved and all checks pass, the PR is merged to main. The publish pipeline then runs automatically on main to build, test across Python 3.11–3.14, and publish the package.

Code Quality

Running Checks Locally

Run these before pushing to catch issues early:

Check Command
Run tests poetry run pytest tests/ -v
Tests with coverage poetry run pytest tests/ --cov=askrita --cov-report=term-missing
Format code poetry run black askrita tests
Sort imports poetry run isort askrita tests
Lint poetry run flake8 askrita tests
Type check poetry run mypy askrita
Security scan poetry run bandit -r askrita
All checks (tox) tox

Code Style

Ask RITA uses these tools for consistent code style:

  • Black — code formatting (line length: 88)
  • isort — import sorting (Black-compatible profile)
  • flake8 — linting
  • mypy — static type checking

Configuration is in pyproject.toml. Pre-commit hooks enforce these automatically.

Requirements for All Code Changes

  • All functions must include type hints and docstrings
  • New features must have unit tests with >80% coverage
  • Overall project coverage must stay above 80%
  • No hardcoded credentials — use ${ENV_VAR} substitution
  • Follow existing design patterns (Strategy, Decorator, Chain of Responsibility)

Project Structure

askRITA/
├── askrita/                    # Main package
│   ├── __init__.py             # Public API exports
│   ├── cli.py                  # CLI entry point
│   ├── config_manager.py       # YAML config loading and validation
│   ├── exceptions.py           # Custom exception hierarchy
│   ├── mcp_server.py           # MCP stdio server
│   ├── models/                 # Shared Pydantic models
│   ├── utils/                  # LLM, tokens, PII, CoT utilities
│   ├── sqlagent/               # SQL/NoSQL agents
│   │   ├── workflows/          # LangGraph workflow definitions
│   │   ├── database/           # DB strategies, schema decorators
│   │   ├── formatters/         # Chart data formatting
│   │   └── exporters/          # PPTX, PDF, Excel export
│   ├── research/               # CRISP-DM research agent
│   └── dataclassifier/         # Data classification workflow
├── tests/                      # Test suite
├── example-configs/            # Example YAML configurations
├── benchmarks/                 # BIRD benchmark tooling
├── docs/                       # MkDocs documentation
└── pyproject.toml              # Project metadata and dependencies

Testing

Running Tests

poetry run pytest tests/ -v

Running Specific Tests

poetry run pytest tests/test_config_manager.py -v
poetry run pytest tests/test_sql_agent.py::TestSQLWorkflow -v
poetry run pytest tests/ -k "test_bigquery" -v

Coverage Report

poetry run pytest tests/ --cov=askrita --cov-report=term-missing --cov-report=html

Open htmlcov/index.html in a browser for a detailed visual report.

Cross-Version Compatibility

Use Docker Testing to verify your changes work across Python 3.11, 3.12, 3.13, and 3.14 in isolated environments.

Versioning

See the Versioning & Releases guide for how to bump versions, cut releases, and keep version numbers in sync across pyproject.toml, setup.py, and askrita/__init__.py.

Documentation

Documentation lives in docs/ and is built with MkDocs Material.

Previewing Docs Locally

pip install mkdocs-material
mkdocs serve

Open http://localhost:8000 to preview.

Key Documentation Files

File Content
docs/index.md Home page and documentation map
docs/configuration/ Full YAML configuration reference
docs/guides/ Feature and workflow guides
docs/charts/ Chart type reference and framework integration
docs/benchmarks/ BIRD benchmark results and per-model analysis
example-configs/ Example YAML configurations
CHANGELOG.md Version history

When to Update Docs

  • New feature — add or update the relevant guide in docs/guides/
  • New config option — update docs/configuration/
  • New database/LLM support — update docs/supported-platforms.md
  • API changes — update docs/usage-examples.md
  • New chart type — add a page in docs/charts/