# CI Pipeline Documentation

## Overview

The Pinecone Python SDK uses GitHub Actions for continuous integration and verification. The pipeline ensures code quality, type safety, and test coverage on every commit.

## Workflow: Verification

**File:** `.github/workflows/verification.yaml`

### Triggers

The verification workflow runs on:
- Pull requests to `main` branch
- Pushes to `main` branch
- Manual trigger via `workflow_dispatch`

### Concurrency

The workflow uses concurrency groups to ensure only one verification runs per PR at a time, canceling in-progress runs when new commits are pushed.

## Jobs

### 1. Lint Job

**Purpose:** Ensure code follows style guidelines and best practices

**Steps:**
- Checks code formatting with `ruff format --check`
- Checks code quality with `ruff check`

**Runtime:** ~2-3 minutes

**Python Version:** 3.12

**Configuration:**
- Uses ruff configuration from `pyproject.toml`
- Fails on formatting or linting issues

### 2. Type Check Job

**Purpose:** Verify type safety across all supported Python versions

**Steps:**
- Runs `mypy` with strict type checking
- Tests on Python 3.10, 3.11, and 3.12 (matrix)

**Runtime:** ~3-5 minutes per Python version

**Configuration:**
- Uses mypy configuration from `pyproject.toml`
- Strict mode enabled
- All public APIs must be fully typed

### 3. Specification Tests Job

**Purpose:** Verify protocol compliance and API surface contracts

**Steps:**
- Runs protocol compliance tests (`tests/protocols/`)
- Runs API surface tests (`tests/api_surface/`)

**Runtime:** ~2-4 minutes

**Python Version:** 3.12

**Notes:**
- Tests verify implementations satisfy protocol contracts
- Tests verify public API surface matches specifications
- Gracefully handles missing test directories

### 4. Unit Tests Job

**Purpose:** Test individual components with coverage reporting

**Steps:**
- Runs unit tests from `tests/unit/`
- Generates coverage reports (terminal, XML, HTML)
- Uploads coverage to Codecov (Python 3.12 only)
- Tests on Python 3.10, 3.11, and 3.12 (matrix)

**Runtime:** ~5-8 minutes per Python version

**Configuration:**
- Uses pytest configuration from `pyproject.toml`
- Coverage configuration from `pyproject.toml`
- Uploads HTML coverage report as artifact (7-day retention)

**Coverage Requirements:**
- Overall coverage target: >= 90%
- Coverage reports available as artifacts
- Codecov integration for PR comments

### 5. Integration Tests Job

**Purpose:** Test integration with external services (Pinecone API)

**Runtime:** ~10-15 minutes

**Python Version:** 3.12

**Trigger Conditions:**
- Runs on `main` branch pushes
- Runs on PRs with `run-integration-tests` label

**Configuration:**
- Requires `PINECONE_API_KEY` secret
- Tests run against real Pinecone API
- Gracefully handles missing test directory

**Note:** Integration tests are intentionally limited to avoid excessive API usage and costs. Use the label to run on specific PRs when needed.

### 6. Verification Complete Job

**Purpose:** Summary job that reports overall status

**Steps:**
- Checks results of all required jobs
- Fails if any required job failed
- Provides clear success/failure message

**Dependencies:**
- lint
- type-check
- specification-tests
- unit-tests

**Note:** Integration tests are NOT a required dependency to allow PRs to merge without them.

## Pipeline Flow

```mermaid
graph TB
    START[Push/PR] --> PARALLEL{Run in Parallel}
    
    PARALLEL --> LINT[Lint Job]
    PARALLEL --> TYPE[Type Check<br/>3.10, 3.11, 3.12]
    PARALLEL --> SPEC[Specification Tests]
    PARALLEL --> UNIT[Unit Tests<br/>3.10, 3.11, 3.12]
    
    LINT --> SUMMARY[Verification Complete]
    TYPE --> SUMMARY
    SPEC --> SUMMARY
    UNIT --> SUMMARY
    
    START --> INT_CHECK{Main branch or<br/>has label?}
    INT_CHECK -->|Yes| INT[Integration Tests]
    INT_CHECK -->|No| SKIP[Skip Integration]
    
    style LINT fill:#e3f2fd
    style TYPE fill:#fff3e0
    style SPEC fill:#e8f5e9
    style UNIT fill:#f3e5f5
    style INT fill:#fce4ec
    style SUMMARY fill:#4caf50
```

## Performance Characteristics

### Target Completion Time

**Goal:** Pipeline completes in < 10 minutes (excluding integration tests)

**Typical Times:**
- Lint: 2-3 minutes
- Type Check (all versions): 3-5 minutes each = 9-15 minutes total (run in parallel)
- Specification Tests: 2-4 minutes
- Unit Tests (all versions): 5-8 minutes each = 15-24 minutes total (run in parallel)
- Verification Complete: < 1 minute

**Actual Wall Clock Time:** ~5-8 minutes (jobs run in parallel)

**With Integration Tests:** +10-15 minutes

### Optimization Features

1. **Parallel Execution:** All jobs run concurrently where possible
2. **Pip Caching:** Python package cache speeds up dependency installation
3. **Fail Fast:** Matrix strategy with `fail-fast: false` shows all failures
4. **Concurrency Control:** Cancels outdated runs on new commits
5. **Conditional Integration Tests:** Runs only when necessary

## Required Secrets

### Repository Secrets

- `PINECONE_API_KEY`: API key for integration tests
  - Required for: Integration tests job
  - Access: Main branch and PRs with label

## Branch Protection Rules

### Recommended Settings

**Protected Branch:** `main`

**Required Status Checks:**
- `lint`
- `type-check (3.10)`
- `type-check (3.11)`
- `type-check (3.12)`
- `specification-tests`
- `unit-tests (3.10)`
- `unit-tests (3.11)`
- `unit-tests (3.12)`
- `verification-complete`

**Additional Rules:**
- Require branches to be up to date before merging
- Require pull request reviews (1+ reviewers)
- Dismiss stale reviews on new commits
- Require linear history

**Note:** Integration tests are NOT required for merge to avoid blocking PRs when API is unavailable.

## Local Development

### Run All Checks Locally

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

# Run linting
ruff format --check .
ruff check .

# Run type checking
mypy pinecone

# Run tests with coverage
pytest tests/unit -v --cov=pinecone --cov-report=term-missing

# Run protocol tests
pytest tests/protocols -v

# Run integration tests (requires API key)
export PINECONE_API_KEY="your-api-key"
pytest tests/integration -v
```

### Pre-commit Hooks

Consider installing pre-commit hooks for automatic verification:

```bash
pip install pre-commit
pre-commit install
```

## Troubleshooting

### Common Issues

**1. Type Check Failures**
- Ensure all functions have type hints
- Check mypy configuration in `pyproject.toml`
- Use `# type: ignore` sparingly with comments

**2. Lint Failures**
- Run `ruff format .` to auto-format code
- Run `ruff check --fix .` to auto-fix issues
- Review remaining issues manually

**3. Coverage Below Threshold**
- Add tests for uncovered code
- Check coverage report artifact for details
- Use `pytest --cov-report=html` locally to investigate

**4. Integration Test Failures**
- Verify `PINECONE_API_KEY` secret is set
- Check API service status
- Review test logs for specific errors

**5. Matrix Job Failures**
- Review which Python versions failed
- Check for version-specific issues
- Ensure dependencies support all versions

## Monitoring and Maintenance

### Workflow Health

Monitor:
- Success rate of verification runs
- Duration trends (alert if > 10 minutes regularly)
- Flaky test patterns
- Coverage trends

### Updates

Regularly update:
- GitHub Actions versions (`actions/checkout`, `actions/setup-python`, etc.)
- Python versions in matrix (when new versions release)
- Dependencies in `pyproject.toml`
- Timeout values if needed

### Badge Status

The README includes badges that show:
- Verification workflow status
- Code coverage percentage
- Python version support
- License information

## Related Documentation

- [Verification Architecture](../architecture/verification.md) - Overall testing strategy
- [Testing Conventions](../conventions/testing.md) - Test writing guidelines
- [Development Workflow](./development-workflow.md) - Complete development process
