🤝 Contributing Guidelines

Thank you for your interest in contributing to the Audio Transcription Tool! This document provides guidelines and best practices for contributing to the project.

Getting Started
Development Workflow
Code Standards
Testing Requirements
Pull Request Process
Issue Guidelines
Architecture Guidelines

Getting Started

Prerequisites

Before contributing, ensure you have:

Development Environment: Follow the Setup Guide
Understanding of the Project: Review the Architecture Documentation
Familiarity with APIs: Check the API Reference

First-Time Contributors

Fork the Repository: Create your own fork on GitHub

Clone Your Fork:

git clone git@github.com:YOUR_USERNAME/agent.git
cd agent

Set Up Development Environment: Follow the Setup Guide
Explore the Codebase: Run demo scripts to understand functionality

Development Workflow

Branch Strategy

We use a feature branch workflow:

main (production-ready)
├── feature/new-feature-name
├── bugfix/issue-description
├── docs/documentation-update
└── refactor/component-name

Creating a Feature Branch

# Update main branch
git checkout main
git pull origin main

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

# Example branch names
git checkout -b feature/android-trd-generation
git checkout -b bugfix/audio-upload-validation
git checkout -b docs/api-documentation-update

Development Process

Make Changes: Implement your feature or fix
Test Locally: Run tests and demo scripts
Format Code: Use Black and check with Pylint
Commit Changes: Use descriptive commit messages
Push Branch: Push to your fork
Create Pull Request: Submit for review

Commit Message Guidelines

Use clear, descriptive commit messages:

# Good commit messages
git commit -m "Add Android TRD generation service"
git commit -m "Fix audio file validation for large files"
git commit -m "Update API documentation for new endpoints"
git commit -m "Refactor UI components for better reusability"

# Avoid vague messages
git commit -m "Fix bug"
git commit -m "Update code"
git commit -m "Changes"

Commit Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(services): add Android TRD generation service
fix(ui): resolve audio upload validation issue
docs(api): update services API documentation
refactor(components): improve ComponentFactory pattern

Code Standards

Python Code Style

We follow PEP 8 with some modifications:

Formatting with Black

# Format all code
black .

# Check specific files
black services/ ui/ config/

Linting with Pylint

# Check all code
pylint services/ ui/ config/

# Check specific file
pylint services/openai_service.py

Code Style Guidelines

Line Length: Maximum 88 characters (Black default)
Imports: Group imports (standard library, third-party, local)
Docstrings: Use Google-style docstrings
Type Hints: Use type hints for function parameters and returns
Variable Names: Use descriptive names (snake_case)
Constants: Use UPPER_CASE for constants

Example Code Style

"""
Module docstring describing the purpose.
"""

import os
from typing import Optional, Dict, Any

from openai import OpenAI
from config.settings import settings


class ExampleService:
    """
    Example service class demonstrating code style.
    
    This class shows proper formatting, documentation,
    and type hints according to project standards.
    """
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the service.
        
        Args:
            api_key: Optional API key override
        """
        self.api_key = api_key or settings.openai_api_key
        self.client = None
    
    def process_data(self, input_data: str, options: Dict[str, Any]) -> str:
        """
        Process input data with given options.
        
        Args:
            input_data: The data to process
            options: Processing options
            
        Returns:
            Processed data as string
            
        Raises:
            ValueError: If input_data is empty
        """
        if not input_data.strip():
            raise ValueError("Input data cannot be empty")
        
        # Processing logic here
        result = self._internal_process(input_data, options)
        return result
    
    def _internal_process(self, data: str, options: Dict[str, Any]) -> str:
        """Internal processing method."""
        # Implementation details
        return f"Processed: {data}"

Documentation Standards

Docstring Format

Use Google-style docstrings:

def example_function(param1: str, param2: int = 10) -> bool:
    """
    Brief description of the function.
    
    Longer description if needed, explaining the purpose,
    behavior, and any important details.
    
    Args:
        param1: Description of the first parameter
        param2: Description of the second parameter with default value
        
    Returns:
        Description of the return value
        
    Raises:
        ValueError: When param1 is empty
        TypeError: When param2 is not an integer
        
    Example:
        >>> result = example_function("test", 20)
        >>> print(result)
        True
    """
    if not param1:
        raise ValueError("param1 cannot be empty")
    
    return len(param1) > param2

Code Comments

# Good comments explain WHY, not WHAT
def calculate_tokens(text: str) -> int:
    # OpenAI uses approximately 4 characters per token for English text
    # This is a rough estimation for token counting
    return len(text) // 4

# Avoid obvious comments
def get_file_size(file_path: str) -> int:
    # Don't do this: "Get the size of the file"
    return os.path.getsize(file_path)

Testing Requirements

Test Structure

Tests are organized in the tests/ directory:

tests/
├── __init__.py
├── test_services.py          # Service layer tests
├── test_ui_components.py     # UI component tests
├── test_configuration.py     # Configuration tests
└── test_integration.py       # Integration tests

Writing Tests

Unit Tests

import pytest
from services.openai_service import OpenAIService


class TestOpenAIService:
    """Test cases for OpenAIService."""
    
    def setup_method(self):
        """Set up test fixtures."""
        self.service = OpenAIService()
    
    def test_is_available_with_valid_key(self):
        """Test service availability with valid API key."""
        # Arrange
        self.service.client = "mock_client"
        
        # Act
        result = self.service.is_available()
        
        # Assert
        assert result is True
    
    def test_is_available_without_key(self):
        """Test service availability without API key."""
        # Arrange
        self.service.client = None
        
        # Act
        result = self.service.is_available()
        
        # Assert
        assert result is False
    
    @pytest.mark.parametrize("input_text,expected", [
        ("", False),
        ("   ", False),
        ("valid text", True),
    ])
    def test_input_validation(self, input_text, expected):
        """Test input validation with various inputs."""
        result = self.service._validate_input(input_text)
        assert result == expected

Integration Tests

def test_complete_transcription_workflow():
    """Test the complete transcription workflow."""
    # This test would use actual services but with test data
    from services.whisper_service import WhisperService
    from services.file_service import FileService
    
    whisper = WhisperService(model_name="tiny")  # Use fastest model for tests
    file_service = FileService()
    
    # Test with a small audio file
    test_audio_path = "tests/fixtures/test_audio.wav"
    
    # Test transcription
    transcription, temp_file = whisper.transcribe_audio(test_audio_path)
    
    assert transcription is not None
    assert len(transcription) > 0
    assert temp_file is not None
    
    # Clean up
    file_service.cleanup_temp_file(temp_file)

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=services --cov=ui --cov=config --cov-report=html

# Run specific test file
python -m pytest tests/test_services.py

# Run specific test method
python -m pytest tests/test_services.py::TestOpenAIService::test_is_available

# Run tests with verbose output
python -m pytest -v

# Run tests and stop on first failure
python -m pytest -x

Test Coverage Requirements

Minimum Coverage: 80% for new code
Critical Components: 90%+ coverage for services
Test Types: Unit tests, integration tests, and demo script tests

Pull Request Process

Before Creating a Pull Request

Update Your Branch:

git checkout main
git pull origin main
git checkout your-feature-branch
git rebase main

Run All Tests:
```
python -m pytest
python -m demos all
```
Format and Lint Code:
```
black .
pylint services/ ui/ config/
```
Update Documentation: If you've added features or changed APIs

Pull Request Template

When creating a pull request, include:

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Changes Made
- List specific changes
- Include any new files or modified files
- Mention any configuration changes

## Testing
- [ ] All existing tests pass
- [ ] New tests added for new functionality
- [ ] Manual testing completed
- [ ] Demo scripts run successfully

## Documentation
- [ ] Code is properly documented
- [ ] API documentation updated (if applicable)
- [ ] README updated (if applicable)

## Checklist
- [ ] Code follows the project's style guidelines
- [ ] Self-review of code completed
- [ ] Code is properly commented
- [ ] No unnecessary console.log or debug statements
- [ ] Changes generate no new warnings

Review Process

Automated Checks: GitHub Actions will run tests and linting
Code Review: At least one maintainer will review your code
Feedback: Address any feedback or requested changes
Approval: Once approved, your PR will be merged

Review Criteria

Reviewers will check for:

Code Quality: Follows style guidelines and best practices
Functionality: Changes work as intended
Tests: Adequate test coverage for new code
Documentation: Proper documentation for new features
Architecture: Follows project architecture patterns
Performance: No significant performance regressions

Issue Guidelines

Reporting Bugs

Use the bug report template:

**Bug Description**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected Behavior**
A clear and concise description of what you expected to happen.

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Environment:**
- OS: [e.g. macOS, Windows, Linux]
- Python Version: [e.g. 3.9.0]
- Browser: [e.g. chrome, safari]
- Version: [e.g. 1.0.0]

**Additional Context**
Add any other context about the problem here.

Feature Requests

Use the feature request template:

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is.

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.

Architecture Guidelines

Adding New Services

When adding new services:

Follow the Service Pattern:

class NewService:
    def __init__(self):
        # Initialize service
        pass
    
    def main_method(self, input_data):
        # Main functionality
        pass
    
    def _private_method(self):
        # Internal helper methods
        pass

Add Configuration: Update config/settings.py and config/constants.py
Create Tests: Add comprehensive tests
Update Documentation: Add to API documentation

Adding New UI Components

When adding UI components:

Follow the Component Pattern: Use the existing component structure
Add to ComponentFactory: Include factory method
Update Interfaces: Integrate with existing interfaces
Test Components: Add UI component tests

Configuration Changes

When modifying configuration:

Update Settings: Modify config/settings.py
Add Constants: Update config/constants.py
Environment Variables: Document new variables
Validation: Add validation for new settings

Code Review Guidelines

For Contributors

Self-Review: Review your own code before submitting
Small PRs: Keep pull requests focused and reasonably sized
Clear Description: Explain what and why, not just what
Test Coverage: Include tests for new functionality

For Reviewers

Be Constructive: Provide helpful feedback
Focus on Important Issues: Don't nitpick minor style issues
Ask Questions: If something is unclear, ask for clarification
Approve When Ready: Don't delay approval for minor issues

Getting Help

Resources

Setup Guide: Development environment setup
Architecture Documentation: Technical architecture
API Reference: Complete API documentation
Demo Scripts: Working examples

Communication

GitHub Issues: For bugs and feature requests
GitHub Discussions: For questions and general discussion
Pull Request Comments: For code-specific discussions

Mentorship

New contributors are welcome! If you're new to the project:

Start Small: Begin with documentation or small bug fixes
Ask Questions: Don't hesitate to ask for help
Learn the Codebase: Explore existing code and patterns
Follow Guidelines: Adhere to the established patterns

Recognition

Contributors are recognized in:

README.md: Contributors section
Release Notes: Major contributions mentioned
GitHub: Contributor statistics and graphs

Thank you for contributing to the Audio Transcription Tool! 🎉

Contributing Guidelines Version: 1.0.0
Last Updated: January 2025
Maintainer: Development Team

FilesExpand file tree

contributing.md

Latest commit

History