CONTRIBUTING.md

Contributing to text2speech-py

Thank you for your interest in contributing to text2speech-py! This document provides guidelines and instructions for contributing.

Code of Conduct

Please be respectful and considerate in all interactions. We aim to maintain a welcoming and inclusive environment.

Development Setup

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended) or pip
• Git

Setting Up Your Development Environment

1. Fork and clone the repository:

   git clone https://github.com/yourusername/text2speech-py.git
   cd text2speech-py

2. Create a virtual environment:

   # Using uv (recommended)
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Or using standard Python
   python -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   # Install main dependencies
   uv pip install -e .
   
   # Install development dependencies
   uv pip install -e ".[dev]"

Code Style and Quality

We enforce strict code quality standards. Please ensure your code follows these guidelines:

Python Style Guidelines

• Follow PEP 8 style guidelines
• Use type hints for all function signatures
• Write docstrings for all public functions, classes, and methods
• Use 4 spaces for indentation (never tabs)
• Limit line length to 88 characters
• No emoji in code (except in tests for multibyte character testing)

Code Quality Tools

We use the following tools to maintain code quality:

# Format code with Ruff
ruff format .

# Check code with Ruff linter
ruff check . --fix

# Type check with mypy
mypy *.py

# Run tests
pytest

Pre-commit Checklist

Before committing, ensure:

• All tests pass: pytest
• Code is formatted: ruff format .
• No linting errors: ruff check .
• Type checking passes: mypy *.py
• All functions have type hints
• All functions have docstrings
• No commented-out code
• No debug print statements

Making Changes

Branch Naming

Use descriptive branch names:

• feature/add-vietnamese-support
• fix/audio-processing-bug
• docs/update-readme
• refactor/cleanup-helpers

Commit Messages

Write clear, descriptive commit messages:

Add Vietnamese text preprocessing function

- Implement tone marker handling
- Add text splitting for long sentences
- Include parameter recommendations

Format:

• First line: Brief summary (50 chars or less)
• Blank line
• Detailed description (wrap at 72 characters)

Pull Request Process

1. Update documentation if you've changed functionality
2. Add tests for new features
3. Update CHANGELOG.md with your changes
4. Ensure all tests pass and code quality checks succeed
5. Create a pull request with a clear description

Pull Request Template

## Description
Brief description of the changes

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

## Testing
How has this been tested?

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code where needed
- [ ] I have updated the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests
- [ ] All tests pass locally

Testing

Writing Tests

• Place tests in the tests/ directory
• Use pytest as the testing framework
• Mock external dependencies (APIs, file systems, etc.)
• Follow the Arrange-Act-Assert pattern

Example:

def test_prepare_vietnamese_text():
    """Test Vietnamese text preparation."""
    helper = VietnameseTTSHelper()
    
    # Arrange
    text = "Xin chào,thế giới!"
    
    # Act
    result = helper.prepare_vietnamese_text(text)
    
    # Assert
    assert result == "Xin chào, thế giới! "

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_vietnamese_helper.py

Documentation

Docstring Format

Use Google-style docstrings:

def function_name(param1: str, param2: int = 0) -> bool:
    """Brief description of function.

    Longer description if needed.

    Args:
        param1: Description of param1
        param2: Description of param2 (default: 0)

    Returns:
        Description of return value

    Raises:
        ValueError: When invalid input is provided
    """
    pass

Getting Help

• Open an issue for bugs or feature requests
• Join discussions in existing issues
• Ask questions in pull request comments

Recognition

Contributors will be recognized in:

• CHANGELOG.md
• Project README.md
• Git commit history

Thank you for contributing to text2speech-py!