# Contributing Guide

# Fork and clone
git clone https://github.com/yourusername/sonora.git
cd sonora

# Install dependencies
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Format code
black .

# Sort imports
isort .

# Lint code
ruff check .

# Type check
mypy sonora/

feat: add new autoplay strategy
fix: resolve memory leak in queue
docs: update API reference
style: format code with black
refactor: simplify player logic
test: add integration tests
chore: update dependencies

feature/add-autoplay-strategy
fix/memory-leak-queue
docs/update-api-reference

# tests/test_feature.py
import pytest
from sonora.feature import Feature

class TestFeature:
    def test_basic_functionality(self):
        feature = Feature()
        assert feature.do_something() == "expected"

    @pytest.mark.asyncio
    async def test_async_functionality(self):
        result = await feature.async_operation()
        assert result is not None

# tests/test_integration.py
@pytest.mark.asyncio
async def test_full_workflow():
    client = SonoraClient(...)
    await client.start()

    player = await client.get_player(guild_id)
    track = await player.play("query")

    assert track is not None
    assert player.current == track

    await client.close()

pytest --cov=sonora --cov-report=html
# Open htmlcov/index.html

def play(self, query: str) -> Track | None:
    """Play a track from a search query.

    Args:
        query: Search query or URL

    Returns:
        The loaded track, or None if failed

    Raises:
        TrackLoadError: If track loading fails

    Example:
        >>> track = await player.play("never gonna give you up")
        >>> print(track.title)
        Never Gonna Give You Up
    """

<!-- docs/api.md -->
### Player.play(query)

Plays a track from a search query.

**Parameters:**
- `query` (str): Search query or URL

**Returns:** `Track | None`

**Example:**
```python
track = await player.play("song name")

## Pull Request Process

### Before Submitting

1. **Update CHANGELOG.md** with your changes
2. **Run full test suite**
3. **Check code style**
4. **Update documentation**
5. **Test on multiple Python versions**

### PR Template

```markdown
## Description
Brief description of changes

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

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

## Checklist
- [ ] Code follows style guidelines
- [ ] Tests pass
- [ ] Documentation updated
- [ ] CHANGELOG updated

**Describe the bug**
Clear description of the issue

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What should happen

**Environment:**
- OS: [e.g. Ubuntu 20.04]
- Python: [e.g. 3.11]
- Sonora: [e.g. 1.2.7]

**Additional context**
Any other relevant information

**Is your feature request related to a problem?**
Description of the problem

**Describe the solution**
What you want to happen

**Describe alternatives**
Alternative solutions considered

**Additional context**
Screenshots, examples, etc.