Contributing¶

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

Getting Started¶

Prerequisites¶

Python 3.11+
uv package manager
AWS CLI configured (for integration tests)
Git

Development Setup¶

# Clone the repository
git clone https://github.com/zhiweio/redshift-spectra.git
cd redshift-spectra

# Install dependencies (including dev tools)
task setup:install-dev

# Run tests to verify setup
task test:all

# Run linting
task lint:check

Development Workflow¶

flowchart LR
    FORK[Fork Repo] --> BRANCH[Create Branch]
    BRANCH --> CODE[Write Code]
    CODE --> TEST[Run Tests]
    TEST --> LINT[Run Linting]
    LINT --> COMMIT[Commit]
    COMMIT --> PR[Open PR]
    PR --> REVIEW[Code Review]
    REVIEW --> MERGE[Merge]

1. Fork and Clone¶

# Fork via GitHub UI, then:
git clone https://github.com/YOUR_USERNAME/redshift-spectra.git
cd redshift-spectra
git remote add upstream https://github.com/zhiweio/redshift-spectra.git

2. Create a Branch¶

# Create feature branch
git checkout -b feature/my-awesome-feature

# Or bugfix branch
git checkout -b fix/issue-123

3. Make Your Changes¶

Write your code following our style guidelines (see below).

4. Run Quality Checks¶

# Format code
task lint:format

# Run linting
task lint:check

# Run type checking
task lint:type-check

# Run tests
task test:all

5. Commit Your Changes¶

git add .
git commit -m "feat: add awesome feature"

Follow Conventional Commits:

Prefix	Description
`feat:`	New feature
`fix:`	Bug fix
`docs:`	Documentation only
`style:`	Formatting, no code change
`refactor:`	Code change, no new feature
`test:`	Adding tests
`chore:`	Maintenance tasks

6. Push and Open PR¶

git push origin feature/my-awesome-feature

Then open a Pull Request on GitHub.

Code Style¶

Python Style¶

We use Ruff for linting and formatting:

# Format code
task lint:format

# Check style
task lint:check

Key style points:

Line length: 100 characters
Use type hints for all function signatures
Use docstrings for public functions and classes
Follow PEP 8 conventions

Example Code Style¶

"""Module docstring explaining the purpose."""

from typing import Any

from pydantic import BaseModel


class QueryRequest(BaseModel):
    """Request model for query submission.

    Attributes:
        sql: The SQL query to execute.
        parameters: Optional query parameters.
        async_mode: Whether to execute asynchronously.
    """

    sql: str
    parameters: list[dict[str, Any]] | None = None
    async_mode: bool = True

    def validate_sql(self) -> None:
        """Validate the SQL query.

        Raises:
            ValueError: If SQL is invalid.
        """
        if not self.sql.strip():
            raise ValueError("SQL query cannot be empty")

Documentation Style¶

Use Markdown for all documentation
Include code examples where helpful
Use admonitions for tips, warnings, and notes
Add Mermaid diagrams for complex flows

Testing¶

Write Tests for New Code¶

All new features should include tests:

class TestNewFeature:
    def test_happy_path(self):
        """Test the normal use case."""
        ...

    def test_edge_case(self):
        """Test edge cases."""
        ...

    def test_error_handling(self):
        """Test error conditions."""
        ...

Test Coverage¶

Maintain at least 80% code coverage:

task test:cov

Pull Request Guidelines¶

PR Checklist¶

[ ] Code follows style guidelines
[ ] Tests pass locally
[ ] New code has tests
[ ] Documentation updated if needed
[ ] Commit messages follow convention
[ ] No merge conflicts

PR Description Template¶

## Description
Brief description of changes.

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

## Testing
Describe how you tested these changes.

## Related Issues
Fixes #123

Project Structure¶

redshift-spectra/
├── src/spectra/           # Main source code
│   ├── handlers/          # Lambda handlers
│   ├── services/          # Business logic
│   ├── models/            # Pydantic models
│   ├── middleware/        # Request middleware
│   └── utils/             # Utilities
├── tests/                 # Test files
├── docs/                  # Documentation
├── terraform/             # Infrastructure modules
├── terragrunt/            # Environment configs
└── scripts/               # Build scripts

Getting Help¶

Questions: Open a Discussion
Bugs: Open an Issue
Security: Email security@example.com (do not open public issues)

Recognition¶

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation

Thank you for contributing! 🎉