Перейти к содержанию

Участие в Разработке HistorySync

Спасибо за интерес к участию! Исправления ошибок, новые экстракторы браузеров, улучшения документации, переводы и покрытие тестами особенно приветствуются.

С Чего Начать

  1. Просмотрите открытые Issues — ищите метки good first issue или help wanted.
  2. Прокомментируйте issue перед началом значительной работы, чтобы избежать дублирования усилий.
  3. Для небольших исправлений (опечатки, однострочные ошибки) открывайте PR напрямую без предварительного issue.

Настройка Окружения Разработки

Требования

Инструмент Требуемая версия
Python 3.12 рекомендуется (соответствует CI-среде)
Git Любая актуальная версия

HistorySync поддерживает Python 3.10+, но используйте 3.12 при участии в разработке, чтобы ваша среда соответствовала линтингу, тестам и заблокированным зависимостям.

Шаги

# 1. Форкните репозиторий на GitHub, затем клонируйте ваш форк
git clone https://github.com/YOUR_USERNAME/HistorySync.git
cd HistorySync

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

# 3. Установить зависимости времени выполнения
pip install -r requirements.txt

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

# 5. (Рекомендуется) Установить хуки pre-commit
pre-commit install

# 6. Проверить настройку
python -m src.main --fresh

Стиль Кода

Этот проект использует Ruff для линтинга и форматирования. Конфигурация находится в ruff.toml.

# Проверить на проблемы
ruff check .

# Автоматически исправить там, где возможно
ruff check . --fix

# Форматировать код
ruff format .

# Запустить все хуки pre-commit вручную
pre-commit run --all-files

Общие заметки по стилю:

  • Следуйте существующим паттернам в редактируемом файле.
  • Держите код GUI (PySide6) и бизнес-логику строго разделёнными — сервисы не должны импортировать Qt.
  • Предпочитайте ясность над хитроумностью.
  • Добавляйте или обновляйте докстринги при изменении публичных API.

Запуск Тестов

# Запустить полный набор тестов
pytest

# Запустить конкретный файл тестов
pytest tests/test_chromium_extractor.py

# Подробный вывод
pytest -v

# С покрытием (требует pytest-cov, включён в requirements-test.txt)
pytest --cov=src --cov-report=term-missing

# Те же проверки линтера, что и в CI
ruff check src/ tests/
ruff format --check src/ tests/

Все тесты должны проходить перед слиянием PR. При добавлении новой функциональности включайте соответствующие тесты.

Руководство по Коммитам

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

<тип>(<область>): <тема>

Примеры: 

fix(extractor): handle missing WAL file during Chromium extraction
feat(browser): add Arc browser support on macOS
docs(webdav): document merge behaviour
test(search): add unit tests for query DSL parser
chore(dev): update Ruff to 0.15

Типы: fix, feat, refactor, docs, test, chore, perf, style, ci, build

Правила: - Строка темы ≤ 72 символа. - Используйте повелительный глагол в нижнем регистре (add, fix, remove — не added, fixes). - Добавляйте тело для объяснения почему для неочевидных изменений.

Сертификат Происхождения Разработчика (DCO)

Каждый коммит должен быть подписан. PR с неподписанными коммитами не будут слиты.

git commit -s -m "fix: handle missing WAL file"
# Добавляет: Signed-off-by: Ваше Имя <ваш@email.com>

Убедитесь, что ваша идентификация Git настроена: 

git config --global user.name "Ваше Имя"
git config --global user.email "ваш@email.com"

Забыли подписать?

# Только последний коммит
git commit --amend --no-edit --signoff
git push --force-with-lease

# Несколько коммитов (последние N)
git rebase --signoff HEAD~N
git push --force-with-lease

Рабочий Процесс Pull Request

  1. Создайте ветку от main: 

    git checkout -b fix/edge-history-extraction-utf8
git checkout -b feat/opera-browser-support
git checkout -b docs/webdav-setup-guide

  2. Внесите изменения — делайте коммиты сфокусированными и атомарными.

  3. Запустите тесты и линтер локально.

  4. Отправьте ветку и откройте PR против main: 

    git push origin your-branch-name

  5. Следуйте правилам PR:

  6. Одно изменение или один связанный набор изменений на PR.
  7. Чёткое описание что изменилось и почему.
  8. Свяжите соответствующий issue с Closes #123.
  9. Добавьте скриншоты / записи для UI-изменений.

  10. Каждый коммит должен быть подписан.

  11. Оперативно отвечайте на отзывы по проверке.

Что Мы Ищем

Особенно приветствуется:

  • Новые экстракторы браузеров — поддержка дополнительных форков Chromium/Firefox.
  • Исправления ошибок — особенно платформенно-специфичные проблемы (пути macOS, разрешения Linux, Windows UAC).
  • Улучшения производительности — оптимизация запросов, скорость извлечения, использование памяти.
  • Улучшения UI/UX — доступность, навигация с клавиатуры, согласованность тем.
  • Покрытие тестами — новые тесты для непроверенных путей кода.
  • Документация — улучшение этого сайта, добавление встроенных докстрингов, исправление опечаток.
  • Переводы — обновления файлов .po в src/resources/locales/.

Сначала обсудите (откройте issue перед написанием кода):

  • Крупные архитектурные изменения.
  • Новые сторонние зависимости.
  • Изменения в протоколе синхронизации WebDAV или схеме базы данных.

Уязвимости Безопасности

Не открывайте публичный GitHub issue для уязвимостей безопасности.

Сообщайте в частном порядке по электронной почте 0x4fe6@gmail.com. Включите описание, шаги воспроизведения и возможное воздействие. Вы получите ответ в течение 72 часов.

Лицензия

Отправляя pull request, вы соглашаетесь, что ваш вклад будет лицензирован под Apache 2.0, и подтверждаете DCO для каждого коммита.