# Руководство по вкладу в проект

Спасибо за интерес к участию в разработке ExcC14N! Этот документ описывает процесс внесения изменений.

## Процесс разработки

### 1. Настройка среды разработки

```bash
# Клонирование репозитория
git clone <repository-url>
cd xmlcanon

# Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

# Установка в режиме разработки
pip install -e ".[dev]"
```

### 2. Запуск тестов

```bash
# Запуск всех тестов
python -m pytest tests/ -v

# Запуск с покрытием
python -m pytest tests/ --cov=exc_c14n --cov-report=html

# Запуск конкретного теста
python -m pytest tests/test_transform.py::TestExclusiveC14NTransform::test_simple_element
```

### 3. Проверка качества кода

```bash
# Форматирование кода
black exc_c14n/ tests/ examples/

# Проверка стиля
flake8 exc_c14n/ tests/ examples/

# Проверка типов
mypy exc_c14n/
```

## Стандарты кодирования

### Стиль кода

- Используйте [Black](https://black.readthedocs.io/) для форматирования
- Следуйте [PEP 8](https://pep8.org/)
- Максимальная длина строки: 88 символов (Black default)
- Используйте type hints везде где возможно

### Документация

- Все публичные функции и классы должны иметь docstrings
- Используйте Google style docstrings
- Комментарии должны быть на русском языке для внутренней логики
- Публичная документация на русском языке

### Тестирование

- Каждая новая функция должна иметь тесты
- Стремитесь к 100% покрытию кода
- Тесты должны быть понятными и самодокументирующимися
- Используйте описательные имена тестов на русском языке

## Типы изменений

### Исправления багов

1. Создайте issue с описанием бага
2. Создайте ветку: `fix/issue-number-short-description`
3. Напишите тест, воспроизводящий баг
4. Исправьте баг
5. Убедитесь что все тесты проходят
6. Создайте Pull Request

### Новые функции

1. Создайте issue с описанием предлагаемой функции
2. Обсудите дизайн в issue
3. Создайте ветку: `feature/issue-number-short-description`
4. Реализуйте функцию с тестами
5. Обновите документацию
6. Создайте Pull Request

### Улучшение документации

1. Создайте ветку: `docs/short-description`
2. Внесите изменения
3. Создайте Pull Request

## Требования к Pull Request

### Контрольный список

- [ ] Код соответствует стандартам стиля
- [ ] Все тесты проходят
- [ ] Добавлены тесты для новой функциональности
- [ ] Документация обновлена
- [ ] CHANGELOG.md обновлен
- [ ] Коммиты имеют понятные сообщения

### Шаблон описания PR

```markdown
## Описание
Краткое описание изменений.

## Тип изменения
- [ ] Исправление бага
- [ ] Новая функция
- [ ] Улучшение производительности
- [ ] Обновление документации
- [ ] Рефакторинг

## Тестирование
Описание проведенного тестирования.

## Контрольный список
- [ ] Код соответствует стилю проекта
- [ ] Тесты добавлены/обновлены
- [ ] Документация обновлена
- [ ] CHANGELOG.md обновлен
```

## Соглашения о коммитах

Используйте понятные сообщения коммитов:

```bash
# Хорошо
git commit -m "fix: исправление обработки пустых пространств имен"
git commit -m "feat: добавление поддержки принудительных пространств имен"
git commit -m "docs: обновление README с примерами использования"

# Плохо
git commit -m "fix"
git commit -m "updates"
git commit -m "работает"
```

Префиксы:
- `feat`: новая функция
- `fix`: исправление бага
- `docs`: изменения документации
- `style`: форматирование кода
- `refactor`: рефакторинг
- `test`: добавление тестов
- `chore`: обновление инструментов сборки

## Архитектурные решения

### Принципы проектирования

1. **Простота**: API должен быть интуитивно понятным
2. **Производительность**: оптимизация для типичных случаев использования
3. **Совместимость**: поддержка разных версий Python и библиотек
4. **Надежность**: обработка ошибок и валидация входных данных

### Структура кода

```
exc_c14n/
├── __init__.py          # Публичный API
├── transform.py         # Основная логика трансформации
├── exceptions.py        # Пользовательские исключения
└── utils.py            # Утилиты (при необходимости)
```

## Релизы

### Семантическое версионирование

- **MAJOR** (x.0.0): несовместимые изменения API
- **MINOR** (0.x.0): новая функциональность, обратно совместимая
- **PATCH** (0.0.x): исправления багов

### Процесс релиза

1. Обновите версию в `setup.py` и `__init__.py`
2. Обновите `CHANGELOG.md`
3. Создайте тег: `git tag v1.0.0`
4. Опубликуйте релиз на GitHub

## Вопросы и поддержка

- **Вопросы**: создайте issue с тегом "question"
- **Баги**: создайте issue с тегом "bug"
- **Предложения**: создайте issue с тегом "enhancement"

## Лицензия

Внося изменения в проект, вы соглашаетесь с тем, что ваш код будет лицензирован под MIT License.

---

Спасибо за ваш вклад в развитие проекта! 🚀