Development Guide

Contributing to and developing Chisel CLI with setup instructions, code standards, and testing procedures

Comprehensive guide for contributing to Chisel CLI development, from setup to submitting contributions.

Quick Start for Contributors

1. Fork and Clone

   Fork the repository and clone it locally:

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

2. Setup Environment

   Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # Linux/Mac
   # OR .venv\Scripts\activate  # Windows
   

3. Install in Development Mode

   Install Chisel CLI in development mode with all dependencies:

   pip install -e .[dev]
   

4. Verify Setup

   Run tests to ensure everything works:

   ruff check src/ examples/
   pytest tests/
   

Development Setup

Prerequisites

System Requirements

• Python: 3.8 or higher
• Git: For version control
• Virtual Environment: Recommended for isolation
• Code Editor: VS Code, PyCharm, or similar with Python support

Verify Prerequisites:

python --version  # Should be 3.8+
git --version     # Any recent version
pip --version     # Should be recent

Development Dependencies

The development setup includes additional tools for code quality and testing:

# Included in [dev] extra dependencies:
# - ruff: Linting and formatting
# - pytest: Testing framework  
# - black: Code formatting (backup)
# - mypy: Type checking
# - pre-commit: Git hooks

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

# Or install manually
pip install ruff pytest black mypy pre-commit

Project Structure

Understanding the codebase organization:

Core Structure

chisel/
├── src/chisel/               # Main package
│   ├── __init__.py          # CLI entry point and exports
│   ├── core.py              # ChiselApp functionality
│   ├── auth.py              # Authentication system
│   ├── spinner.py           # UI utilities and progress
│   └── constants.py         # GPU types and configuration
├── examples/                # Usage examples
├── tests/                   # Test suite
├── docs/                    # Documentation
├── pyproject.toml          # Package configuration
└── README.md               # Main project README

Code Standards

Linting and Formatting

We use Ruff for both linting and formatting to ensure consistent code quality:

Check Code Style

# Check for style and quality issues
ruff check src/ examples/ tests/

# Auto-fix issues where possible
ruff check src/ examples/ tests/ --fix

# Format code
ruff format src/ examples/ tests/

# Check if formatting is needed
ruff format src/ examples/ tests/ --check

Code Style Guidelines

Python Style Standards

Line Length: 100 characters maximum Quote Style: Double quotes for strings Indentation: 4 spaces (no tabs) Import Order: Standard library, third-party, local imports

# Good example
from typing import Optional
import os

import torch
import requests

from chisel.constants import GPUType
from chisel.auth import authenticate


class ChiselApp:
    """Main application class for GPU acceleration."""
    
    def __init__(self, name: str, gpu: Optional[GPUType] = None):
        self.name = name
        self.gpu = gpu
        
    def capture_trace(self, trace_name: str = "default"):
        """Decorator for capturing execution traces."""
        def decorator(func):
            return func
        return decorator

Documentation Standards

Docstrings: Use Google-style docstrings for all public functions and classes Type Hints: Include type hints for all function parameters and return values Comments: Explain complex logic and business decisions

def authenticate(backend_url: str = "http://localhost:8000") -> str:
    """Authenticate with the Chisel backend.
    
    Opens a browser window for user authentication and stores
    the resulting API key securely.
    
    Args:
        backend_url: The backend URL to authenticate against.
        
    Returns:
        The API key string on successful authentication.
        
    Raises:
        RuntimeError: If authentication fails or is cancelled.
        
    Example:
        >>> api_key = authenticate("https://api.herdora.com")
        >>> print(f"Authenticated with key: {api_key[:8]}...")
    """
    # Implementation here
    pass

Error Handling Standards

Exception Types: Use appropriate built-in exceptions or create custom ones Error Messages: Clear, actionable error messages with context Logging: Use logging module for debugging information

import logging
from typing import Optional

logger = logging.getLogger(__name__)


class ChiselAuthenticationError(RuntimeError):
    """Raised when authentication with Chisel backend fails."""
    pass


def load_credentials() -> Optional[dict]:
    """Load stored credentials from file.
    
    Returns:
        Credentials dictionary or None if not found/invalid.
        
    Raises:
        ChiselAuthenticationError: If credentials are corrupted.
    """
    try:
        with open(credentials_path) as f:
            credentials = json.load(f)
            
        if not validate_credentials(credentials):
            raise ChiselAuthenticationError(
                "Stored credentials are invalid. Please re-authenticate."
            )
            
        return credentials
        
    except FileNotFoundError:
        logger.debug("No credentials file found")
        return None
        
    except json.JSONDecodeError as e:
        raise ChiselAuthenticationError(
            f"Credentials file is corrupted: {e}. Please re-authenticate."
        ) from e

Pre-commit Hooks

Set up automated quality checks before each commit:

1. Install pre-commit

   pip install pre-commit
   

2. Create configuration

   Create .pre-commit-config.yaml:

   repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.1.9
     hooks:
       - id: ruff
         args: [--fix]
       - id: ruff-format
   
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-toml
   

3. Install hooks

   pre-commit install
   

   Now quality checks run automatically before each commit!

Testing

Running Tests

Basic Testing

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_core.py

# Run specific test
pytest tests/test_core.py::test_app_creation

Writing Tests

Test Structure and Patterns

Follow these patterns for consistent, maintainable tests:

import pytest
import os
from unittest.mock import patch, MagicMock

from chisel import ChiselApp, GPUType
from chisel.auth import authenticate, clear_credentials


class TestChiselApp:
    """Test suite for ChiselApp functionality."""
    
    def test_app_creation_with_gpu_type(self):
        """Test ChiselApp creation with GPU type."""
        app = ChiselApp("test-app", gpu=GPUType.A100_80GB_2)
        
        assert app.name == "test-app"
        assert app.gpu == "A100-80GB:2"
        
    def test_app_creation_defaults(self):
        """Test ChiselApp creation with default values."""
        app = ChiselApp("test-app")
        
        assert app.name == "test-app"
        assert app.gpu is None
        assert app.upload_dir == "."
        
    @patch.dict(os.environ, {'CHISEL_ACTIVATED': '1'})
    def test_app_activation(self):
        """Test ChiselApp activation with environment variable."""
        app = ChiselApp("test-app")
        
        assert app.activated is True
        
    @patch('chisel.core.requests.post')
    def test_job_submission(self, mock_post):
        """Test job submission with mocked backend."""
        mock_post.return_value.json.return_value = {
            'job_id': 'test-123',
            'status': 'success'
        }
        
        app = ChiselApp("test-app", gpu=GPUType.A100_80GB_1)
        
        # Test functionality that submits jobs
        # ...
        
        # Verify backend was called correctly
        mock_post.assert_called_once()

Mocking and Fixtures

Use mocking to isolate tests and avoid external dependencies:

import pytest
from unittest.mock import patch, MagicMock, mock_open


@pytest.fixture
def mock_credentials_file():
    """Fixture providing mock credentials file."""
    credentials = {
        "api_key": "test-api-key-123",
        "backend_url": "http://localhost:8000",
        "expires_at": "2024-12-31T23:59:59Z"
    }
    return json.dumps(credentials)


@pytest.fixture
def temp_credentials_dir(tmp_path):
    """Fixture providing temporary credentials directory."""
    creds_dir = tmp_path / ".chisel"
    creds_dir.mkdir()
    return creds_dir


class TestAuthentication:
    """Test authentication functionality."""
    
    def test_load_existing_credentials(self, mock_credentials_file):
        """Test loading valid credentials from file."""
        with patch('builtins.open', mock_open(read_data=mock_credentials_file)):
            with patch('os.path.exists', return_value=True):
                credentials = load_credentials()
                
        assert credentials['api_key'] == 'test-api-key-123'
        
    @patch('webbrowser.open')
    @patch('requests.post')
    def test_browser_authentication(self, mock_post, mock_browser):
        """Test browser-based authentication flow."""
        mock_post.return_value.json.return_value = {'api_key': 'new-key-456'}
        
        result = authenticate()
        
        mock_browser.assert_called_once()
        assert result == 'new-key-456'

Integration Tests

Test real functionality with external services (when safe):

import pytest
import os


@pytest.mark.integration
@pytest.mark.skipif(
    not os.getenv('CHISEL_INTEGRATION_TESTS'),
    reason="Integration tests disabled"
)
class TestIntegration:
    """Integration tests requiring real backend."""
    
    def test_full_authentication_flow(self):
        """Test complete authentication with real backend."""
        # Only run if explicitly enabled
        if not os.getenv('CHISEL_TEST_API_KEY'):
            pytest.skip("No test API key provided")
            
        # Test real authentication flow
        # (but use test backend, not production)
        pass
        
    @pytest.mark.slow
    def test_gpu_job_execution(self):
        """Test actual GPU job execution."""
        # Only run if GPU testing is enabled
        if not os.getenv('CHISEL_GPU_TESTS'):
            pytest.skip("GPU tests disabled")
            
        # Test real GPU execution
        # (expensive, so marked as slow)
        pass

Architecture

Core Components

ChiselApp (core.py)

Purpose: Main application class for GPU acceleration

Key Responsibilities:

• GPU configuration and validation
• Code packaging and upload management
• Job submission and tracking
• Function decoration and tracing

Key Methods:

class ChiselApp:
    def __init__(self, name: str, upload_dir: str = ".", gpu: Optional[GPUType] = None)
    def capture_trace(self, trace_name: str = None, **kwargs) -> Callable
    def _submit_job(self, script_path: str, args: List[str]) -> str
    def _package_code(self) -> bytes

Execution Modes

Local Mode (CHISEL_ACTIVATED != '1')

When: Running without chisel command

Behavior:

• ChiselApp runs in inactive mode
• Decorators are pass-through (no-op)
• Code executes normally on local machine
• No authentication or upload required

# Local execution
python my_script.py
# → Decorators do nothing
# → Runs on local CPU/GPU

Chisel Mode (chisel command)

When: Using chisel command

Behavior:

• Sets CHISEL_ACTIVATED=1 environment variable
• Activates GPU functionality in ChiselApp
• Handles authentication automatically
• Uploads code and runs on cloud GPU

# Cloud execution
chisel python my_script.py
# → Sets environment variable
# → Uploads and runs on cloud

Backend Mode (CHISEL_BACKEND_RUN=1)

When: Code executing on backend infrastructure

Behavior:

• Detects execution on cloud environment
• Skips authentication and upload steps
• Executes functions with GPU tracing enabled
• Streams output back to client

# Backend execution (automatic)
# → Code runs on cloud GPU
# → Output streamed to client

Contributing Workflow

Making Changes

1. Create Feature Branch

   Create a new branch for your changes:

   git checkout -b feature/add-new-gpu-type
   # OR
   git checkout -b fix/authentication-bug
   # OR  
   git checkout -b docs/improve-examples
   

2. Make Your Changes

   Implement your feature or fix:

   • Write code following the style guidelines
   • Add or update tests for your changes
   • Update documentation if needed
   • Ensure all quality checks pass

   # Run quality checks frequently
   ruff check src/ --fix
   pytest tests/
   

3. Test Changes

   Run comprehensive tests:

   # All quality checks
   ruff check src/ examples/ tests/
   ruff format src/ examples/ tests/ --check
   
   # All tests
   pytest tests/ -v
   
   # Test examples still work
   python examples/basic_usage.py
   

4. Commit Changes

   Write clear, descriptive commit messages:

   git add .
   git commit -m "Add support for H100 GPU type
   
   - Add H100_80GB variants to GPUType enum
   - Update GPU selection logic in core.py  
   - Add tests for new GPU types
   - Update configuration documentation"
   

Commit Message Guidelines

Good Commit Messages

Format: Brief summary + detailed explanation

# Good examples
git commit -m "Add support for custom GPU types

- Extend GPUType enum with custom type support
- Add validation for custom GPU configurations
- Update documentation with custom GPU examples
- Add tests for custom GPU functionality"

git commit -m "Fix argument passing in CLI wrapper

- Resolve issue where quoted arguments were split incorrectly
- Add proper shell escaping for complex arguments
- Add tests for various argument scenarios
- Fixes #123"

git commit -m "Improve error messages for authentication failures

- Add specific error messages for different failure modes
- Include troubleshooting hints in error output
- Add logging for authentication debugging
- Update troubleshooting documentation"

Poor Commit Messages

Avoid: Vague or uninformative messages

# Poor examples (don't do this)
git commit -m "fix bug"
git commit -m "updates"
git commit -m "changes"
git commit -m "wip"
git commit -m "refactor"

Pull Request Process

1. Push Your Branch

   Push your feature branch to your fork:

   git push origin feature/your-feature-name
   

2. Create Pull Request

   Create a PR with a clear description:

   Title: Brief, descriptive summary Description: Include:

   • What the PR does
   • Why it’s needed
   • How to test it
   • Any breaking changes
   • Related issues

   ## Description
   Add support for H100 GPU types to expand hardware options.
   
   ## Changes
   - Added H100_80GB_1, H100_80GB_2, H100_80GB_4, H100_80GB_8 to GPUType enum
   - Updated GPU memory calculations for H100 architecture
   - Added validation tests for new GPU types
   - Updated configuration documentation
   
   ## Testing
   - [ ] All existing tests pass
   - [ ] New tests added for H100 GPU types
   - [ ] Manual testing with example scripts
   - [ ] Documentation updated
   
   ## Breaking Changes
   None - this is a backwards-compatible addition.
   
   Fixes #142
   

3. Address Review Feedback

   Respond to code review comments:

   • Make requested changes
   • Add clarifying comments
   • Update tests if needed
   • Push updates to the same branch

   # Address feedback
   git add .
   git commit -m "Address review feedback
   
   - Add input validation as requested
   - Clarify error message wording
   - Add edge case test for empty input"
   
   git push origin feature/your-feature-name
   

Release Process

Version Management

Versioning Strategy

We follow Semantic Versioning:

• MAJOR: Breaking changes (e.g., 1.0.0 → 2.0.0)
• MINOR: New features, backwards compatible (e.g., 1.0.0 → 1.1.0)
• PATCH: Bug fixes, backwards compatible (e.g., 1.0.0 → 1.0.1)

Update locations:

# Version must be updated in both places:
# 1. pyproject.toml
version = "0.2.0"

# 2. src/chisel/__init__.py  
__version__ = "0.2.0"

Release Checklist

Before creating a release:

• Update version numbers in both files
• Run complete test suite: pytest tests/
• Test examples manually: python examples/*.py
• Update CHANGELOG.md with new features and fixes
• Update documentation for any API changes
• Create git tag: git tag v0.2.0
• Push tag: git push origin v0.2.0

Testing script:

#!/bin/bash
echo "🚀 Pre-release testing..."

echo "🔍 Code quality..."
ruff check src/ examples/ tests/
ruff format src/ examples/ tests/ --check

echo "🧪 Test suite..."  
pytest tests/ -v

echo "📝 Example scripts..."
for example in examples/*.py; do
    echo "Testing $example"
    python "$example" || exit 1
done

echo "✅ All checks passed! Ready for release."

IDE Setup

VS Code Configuration

Settings

Create .vscode/settings.json:

{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.linting.enabled": false,
    "python.formatting.provider": "none",
    "ruff.enable": true,
    "ruff.organizeImports": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": true,
            "source.organizeImports.ruff": true
        }
    },
    "python.testing.pytestEnabled": true,
    "python.testing.pytestPath": "./.venv/bin/pytest"
}

PyCharm Configuration

Interpreter Setup

1. Go to File → Settings → Project → Python Interpreter
2. Click gear icon → Add → Existing Environment
3. Select .venv/bin/python (or .venv\Scripts\python.exe on Windows)
4. Click OK to apply

Verify setup:

• Check that packages like ruff and pytest are listed
• Test by running a Python file in the IDE

Code Quality Tools

1. Install Ruff plugin from marketplace
2. Go to Settings → Tools → Ruff
3. Configure paths:
   • Ruff executable: .venv/bin/ruff
   • Configuration file: pyproject.toml
4. Enable Format on save and Lint on save

Testing setup:

1. Go to Settings → Tools → Python Integrated Tools
2. Set Default test runner to pytest
3. Set pytest executable to .venv/bin/pytest

Community and Support

Getting Help

GitHub Discussions

Ask questions, share ideas, and get community help

Email Support

Direct support for development questions and contributions

GitHub Issues

Report bugs, request features, and track development

Documentation

Complete API reference and user guides

Community Guidelines

Be respectful, collaborative, and helpful when contributing to Chisel CLI.

Best Practices:

1. Start Small: Begin with documentation improvements or small bug fixes
2. Ask Questions: Use GitHub Discussions for questions before starting work
3. Follow Standards: Adhere to code style and testing requirements
4. Test Thoroughly: Ensure your changes work correctly and don’t break existing functionality
5. Document Changes: Update relevant documentation and examples

Contributing Areas:

• 🐛 Bug Fixes: Fix issues reported by users
• ✨ Features: Add new GPU types, authentication methods, or CLI improvements
• 📚 Documentation: Improve guides, examples, and API documentation
• 🧪 Testing: Add test coverage and improve test reliability
• 🎨 UI/UX: Improve CLI output, error messages, and user experience

Thank you for contributing to Chisel CLI! 🚀

Related Documentation

API Reference

Complete function and class documentation

Examples

Working examples and usage patterns

Configuration

Setup and optimization guides

Troubleshooting

Debug issues and get solutions