Contributing Guide

​

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Set up development environment (Setup Guide)
4. Create a branch for your changes
5. Make your changes with tests
6. Submit a pull request

​

Development Workflow

# Update main
git checkout main
git pull upstream main

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

# Or for bug fixes
git checkout -b fix/bug-description

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy src/myspellchecker

# Run tests
pytest tests/

# Features
git commit -m "feat: add colloquial variant detection"

# Bug fixes
git commit -m "fix: handle empty input in normalize()"

# Documentation
git commit -m "docs: update API reference for i18n"

# Performance
git commit -m "perf: optimize syllable validation loop"

# Refactoring
git commit -m "refactor: extract validation strategies"

git push origin feature/my-feature

​

Code Style

​

Python Style

# Check style
ruff check .

# Auto-fix issues
ruff check . --fix

# Format code
ruff format .

​

Key Style Rules

• Line length: 100 characters max
• Imports: Sorted, grouped (stdlib, third-party, local)
• Docstrings: Google style
• Type hints: Required for public APIs

from typing import Optional

def normalize(
    text: str,
    form: str = "NFC",
    remove_zero_width: bool = True,
) -> str:
    """Normalize Myanmar text.

    Args:
        text: Input text to normalize.
        form: Unicode normalization form (NFC, NFD, NFKC, NFKD).
        remove_zero_width: Whether to remove zero-width characters.

    Returns:
        Normalized text.

    Example:
        >>> normalize("မြန်မာ")
        'မြန်မာ'
    """
    ...

​

Cython Style

​

Testing Requirements

​

Coverage

• Minimum 75% code coverage
• All new features need tests
• Bug fixes should include regression tests

​

Test Types

import pytest

@pytest.mark.unit
def test_unit():
    """Fast, isolated test."""
    pass

@pytest.mark.integration
def test_integration():
    """Test with dependencies."""
    pass

​

Running Tests

# All tests
pytest tests/

# With coverage
pytest tests/ --cov=myspellchecker --cov-fail-under=75

# Specific file
pytest tests/test_validators.py

​

Documentation

​

When to Update Docs

• New features → Add to relevant feature doc
• API changes → Update API reference
• Breaking changes → Update migration guide

​

Documentation Style

• Use clear, concise language
• Include code examples
• Link to related documentation

​

Building Docs

# Preview locally
cd docs
mkdocs serve

# Open http://localhost:8000

​

Pull Request Guidelines

​

PR Title

• feat: Add feature description
• fix: Fix bug description
• docs: Update documentation

​

PR Description

1. Summary - What does this PR do?
2. Motivation - Why is this change needed?
3. Changes - List of changes made
4. Testing - How was this tested?

​

PR Template

## Summary
Brief description of changes.

## Motivation
Why is this change needed?

## Changes
- Change 1
- Change 2

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] Changelog updated (if applicable)

​

Review Process

1. Automated checks run (tests, linting)
2. Maintainer reviews code
3. Address feedback
4. Merge when approved

​

Issue Guidelines

​

Bug Reports

• Description - What’s the bug?
• Steps to reproduce - How can we see it?
• Expected behavior - What should happen?
• Actual behavior - What happens instead?
• Environment - Python version, OS, package version

​

Feature Requests

• Description - What feature do you want?
• Use case - Why do you need it?
• Proposed solution - How might it work?
• Alternatives - Other solutions considered?

​

Types of Contributions

​

Code Contributions

• Bug fixes - Fix reported issues
• Features - Implement new functionality
• Performance - Optimize existing code
• Tests - Add test coverage

​

Non-Code Contributions

• Documentation - Improve docs
• Examples - Add usage examples
• Bug reports - Report issues
• Feature requests - Suggest improvements
• Code review - Review PRs

​

Getting Help

• Questions - Open a GitHub Discussion
• Bugs - Open a GitHub Issue
• Chat - Join our Discord (if available)

​

Code of Conduct

​

Recognition

• CONTRIBUTORS.md file
• Release notes
• Project README

​

See Also

• Development Setup - Environment setup
• Testing Guide - Running tests
• Naming Conventions - Code style
• Cython Guide - Working with Cython