Вклад в проект Votobu

Спасибо за интерес к проекту! Мы рады любому вкладу - от исправления опечаток до добавления новых функций.

🎯 Как помочь проекту

1. 🐛 Сообщить об ошибке

Нашли баг? Создайте Issue с подробным описанием.

2. 💡 Предложить улучшение

Есть идея? Создайте Feature Request.

3. 📝 Улучшить документацию

Заметили опечатку или неточность? Отправьте PR с исправлением!

4. 💻 Написать код

Хотите добавить функцию или исправить баг? Следуйте инструкциям ниже.

---

🚀 Быстрый старт для разработчиков

Шаг 1: Fork и Clone

# 1. Сделайте Fork репозитория на GitHub

# 2. Клонируйте свой fork
git clone https://github.com/YOUR-USERNAME/Votobu.git
cd Votobu

# 3. Добавьте upstream remote
git remote add upstream https://github.com/ORIGINAL-OWNER/Votobu.git

Шаг 2: Установка для разработки

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

# Установить зависимости для разработки
pip install -r requirements-dev.txt

Шаг 3: Создать ветку

# Создайте ветку для своих изменений
git checkout -b feature/my-awesome-feature
# или
git checkout -b fix/bug-description

Шаг 4: Внести изменения

Пишите код, следуя стандартам проекта.

Шаг 5: Тестирование

# Запустить тесты
python test_components.py

# Проверить линтером (если есть)
flake8 src/
black src/ --check

# Протестировать вручную
python src/main.py

Шаг 6: Commit и Push

# Добавить изменения
git add .

# Commit с понятным сообщением
git commit -m "✨ Add feature: voice activation threshold"

# Push в ваш fork
git push origin feature/my-awesome-feature

Шаг 7: Создать Pull Request

1. Перейдите на GitHub
2. Нажмите "New Pull Request"
3. Заполните template
4. Дождитесь review

---

📋 Стандарты кода

Python Style Guide

Следуем PEP 8:

# ✅ Хорошо
def recognize_speech(audio_file: str) -> Optional[str]:
    """Распознать речь из аудио файла."""
    if not Path(audio_file).exists():
        return None
    return whisper.transcribe(audio_file)

# ❌ Плохо
def rec(f):
    if not os.path.exists(f):return None
    return whisper.transcribe(f)

Форматирование

• Отступы: 4 пробела (не табы)
• Длина строки: максимум 100 символов
• Кавычки: двойные " для строк
• Импорты: группируются и сортируются

Docstrings

def function_name(param1: str, param2: int) -> bool:
    """
    Краткое описание функции.
    
    Args:
        param1: Описание параметра 1
        param2: Описание параметра 2
        
    Returns:
        Описание возвращаемого значения
        
    Raises:
        ValueError: Когда возникает эта ошибка
    """
    pass

Комментарии

# ✅ Хорошо: объясняет "почему"
# Whisper требует 16kHz для оптимальной работы
sample_rate = 16000

# ❌ Плохо: объясняет "что" (и так видно)
# Установить sample_rate в 16000
sample_rate = 16000

---

🏗️ Структура проекта

Votobu/
├── src/                    # Исходный код
│   ├── main.py            # Точка входа
│   ├── config_manager.py  # Конфигурация
│   └── ...
├── assets/                # Ресурсы (иконки)
├── config/                # Конфиги
├── tests/                 # Тесты (если добавите)
├── docs/                  # Документация
└── ...

---

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

Минимальные требования

Перед PR убедитесь что:

• python test_components.py проходит
• Приложение запускается без ошибок
• Ваши изменения работают как ожидалось
• Документация обновлена (если нужно)

Добавление тестов

Если добавляете новую функцию, добавьте тесты:

# tests/test_audio_recorder.py
def test_audio_recorder_initialization():
    recorder = AudioRecorder(sample_rate=16000)
    assert recorder.sample_rate == 16000
    assert not recorder.is_recording()

---

📝 Commit Messages

Используем Conventional Commits:

<type>: <description>

[optional body]

[optional footer]

Types:

• ✨ feat: - новая функция
• 🐛 fix: - исправление бага
• 📝 docs: - изменения в документации
• 🎨 style: - форматирование кода
• ♻️ refactor: - рефакторинг
• ⚡ perf: - оптимизация
• ✅ test: - добавление тестов
• 🔧 chore: - изменения инфраструктуры

Примеры:

✨ feat: add GPU acceleration for Whisper
🐛 fix: resolve Qt platform plugin error on Windows
📝 docs: update TROUBLESHOOTING.md with ffmpeg solution
♻️ refactor: simplify audio recording logic

---

🔄 Pull Request Process

Перед созданием PR:

1. Синхронизируйте с upstream:

   git fetch upstream
   git rebase upstream/main

2. Убедитесь что все работает:

   python test_components.py
   python src/main.py

3. Обновите документацию (если нужно)

4. Обновите CHANGELOG.md

Во время review:

• Будьте открыты к фидбеку
• Отвечайте на комментарии
• Вносите запрошенные изменения
• Будьте терпеливы

После merge:

• Удалите свою ветку
• Синхронизируйте fork с upstream
• Празднуйте! 🎉

---

🎨 UI/UX Guidelines

При изменении интерфейса:

• Следуйте существующему стилю
• Добавьте скриншоты в PR
• Протестируйте на разных разрешениях
• Убедитесь что доступно для клавиатуры

Текст в UI:

• Краткий и понятный
• Без технического жаргона
• На русском языке (основной)
• С английским переводом (опционально)

---

🐛 Отладка

Включение детального логирования:

# В src/main.py добавьте:
import logging
logging.basicConfig(level=logging.DEBUG)

Проверка зависимостей:

python test_components.py

Профилирование:

python -m cProfile -o output.prof src/main.py

---

📚 Полезные ресурсы

Документация проекта:

• README.md - обзор проекта
• INSTALL.md - установка
• TROUBLESHOOTING.md - решение проблем
• PROJECT_STRUCTURE.md - архитектура

Внешние ресурсы:

• PyQt5 Documentation
• Whisper GitHub
• PEP 8 Style Guide
• Conventional Commits

---

💬 Коммуникация

Есть вопросы?

• Issues: Для багов и feature requests
• Discussions: Для общих вопросов и идей
• Pull Requests: Для code review

Будьте вежливы:

• Уважайте время других
• Будьте конструктивны
• Помогайте новичкам
• Радуйтесь успехам других

---

📜 Code of Conduct

Наши стандарты:

Приветствуется:

• ✅ Уважительное общение
• ✅ Конструктивная критика
• ✅ Помощь другим
• ✅ Признание ошибок

Неприемлемо:

• ❌ Оскорбления и травля
• ❌ Дискриминация
• ❌ Спам
• ❌ Деструктивная критика

---

🎓 Для новичков

Первый вклад в Open Source?

Отлично! Вот с чего начать:

1. Найдите простую задачу:

   • Поищите issues с меткой good first issue
   • Или исправьте опечатку в документации

2. Попросите помощь:

   • Не стесняйтесь задавать вопросы
   • Мы все когда-то были новичками

3. Начните с малого:

   • Не пытайтесь переписать все сразу
   • Маленькие PR легче ревьюить

Полезные туториалы:

• First Contributions
• How to Contribute to Open Source

---

🏆 Благодарности

Спасибо всем контрибьюторам! Каждый вклад ценен, будь то код, документация, баг-репорт или идея.

---

📄 Лицензия

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

---

Спасибо что делаете Votobu лучше! ❤️

⬅ Назад к README