> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Guide

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

Whether you are fixing a bug, adding a feature, improving tests, or updating documentation, this guide walks you through the full workflow from fork to merged pull request.

## Getting Started

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

## Development Workflow

<Steps>
  <Step title="Create a Branch">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Make Changes">
    * Write code following [naming conventions](/development/naming-conventions)
    * Add tests for new functionality
    * Update documentation if needed
  </Step>

  <Step title="Run Quality Checks">
    ```bash theme={null}
    # Format code
    ruff format .

    # Lint code
    ruff check .

    # Type check
    mypy src/myspellchecker

    # Run tests
    pytest tests/
    ```
  </Step>

  <Step title="Commit Changes">
    Follow conventional commit format:

    ```bash theme={null}
    # 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"
    ```
  </Step>

  <Step title="Push and Create PR">
    ```bash theme={null}
    git push origin feature/my-feature
    ```

    Then create a Pull Request on GitHub.
  </Step>
</Steps>

## Code Style

### Python Style

We use **Ruff** for linting and formatting:

```bash theme={null}
# 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

```python theme={null}
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

For `.pyx` files, see [Cython Guide](/development/cython-guide).

## Testing Requirements

### Coverage

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

### Test Types

```python theme={null}
import pytest

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

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

### Running Tests

```bash theme={null}
# 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

Documentation lives in a separate repo (`myspellchecker-docs`) and uses Mintlify:

```bash theme={null}
# Clone the docs repo
git clone https://github.com/thettwe/myspellchecker-docs.git
cd myspellchecker-docs

# Install Mintlify CLI (one-time)
npm i -g mintlify

# Preview locally
mintlify dev

# Open http://localhost:3000
```

## Pull Request Guidelines

### PR Title

Use conventional commit format:

* `feat: Add feature description`
* `fix: Fix bug description`
* `docs: Update documentation`

### PR Description

Include:

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

```markdown theme={null}
## 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

Include:

* **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

Include:

* **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** - Comment on a relevant GitHub Issue or Discussion

## Code of Conduct

Be respectful and inclusive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/).

## Recognition

Contributors are recognized in:

* Release notes
* Project README

Thank you for contributing!

## See Also

* [Development Setup](/development/setup) - Environment setup
* [Testing Guide](/development/testing) - Running tests
* [Naming Conventions](/development/naming-conventions) - Code style
* [Cython Guide](/development/cython-guide) - Working with Cython