Участие в проекте CulicidaeLab¶

Добро пожаловать в проект CulicidaeLab! Мы рады, что вы заинтересованы в участии в этой платформе с открытым исходным кодом для идентификации комаров и исследований. Это руководство поможет вам эффективно начать участие в проекте.

Содержание¶

Начало работы
Рабочий процесс разработки
Типы участия
Стандарты кода
Требования к тестированию
Руководящие принципы подачи
Руководящие принципы сообщества
Получение помощи

Начало работы¶

Предварительные требования¶

Перед участием убедитесь, что у вас есть:

Среда разработки: Настройте среду разработки, следуя нашему Руководству по настройке разработки
Понимание проекта: Прочитайте Документацию по архитектуре и Руководство по структуре проекта
Стиль кода: Ознакомьтесь с нашим Руководством по стилю кода

Первоначальная настройка¶

Форкните репозиторий

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

Добавьте upstream remote

git remote add upstream https://github.com/culicidaelab/culicidaelab-mobile.git

Установите зависимости
```
flutter pub get
```
Проверьте настройку
```
flutter doctor
flutter test
```

Рабочий процесс разработки¶

Стратегия ветвления¶

Мы используем рабочий процесс feature branch:

Основная ветка: main - Готовый к продакшну код
Feature ветки: feature/description - Новые функции
Bug Fix ветки: fix/description - Исправления ошибок
Documentation ветки: docs/description - Обновления документации

Создание Feature ветки¶

# Обновите вашу main ветку
git checkout main
git pull upstream main

# Создайте и переключитесь на новую feature ветку
git checkout -b feature/mosquito-species-filter

# Внесите изменения и зафиксируйте
git add .
git commit -m "Add species filter to mosquito gallery"

# Отправьте в ваш форк
git push origin feature/mosquito-species-filter

Руководящие принципы сообщений коммитов¶

Следуйте формату conventional commit:

type(scope): description

[optional body]

[optional footer]

Типы: - feat: Новая функция - fix: Исправление ошибки - docs: Изменения документации - style: Изменения стиля кода (форматирование и т.д.) - refactor: Рефакторинг кода - test: Добавление или обновление тестов - chore: Задачи обслуживания

Примеры:

feat(gallery): add species filtering functionality
fix(classification): resolve model loading timeout issue
docs(api): update classification service documentation
test(services): add unit tests for user service

Типы участия¶

1. Исправления ошибок¶

Процесс: 1. Проверьте, не сообщалось ли уже об ошибке в Issues 2. Если нет, создайте новую задачу, используя шаблон отчета об ошибке 3. Создайте ветку исправления: fix/issue-number-description 4. Напишите тесты, воспроизводящие ошибку 5. Реализуйте исправление 6. Убедитесь, что все тесты проходят 7. Отправьте pull request

Требования: - Включите тестовые случаи, проверяющие исправление - Обновите документацию, если исправление изменяет поведение - Ссылайтесь на номер задачи в описании PR

2. Новые функции¶

Процесс: 1. Сначала обсудите функцию в задаче 2. Дождитесь одобрения сопровождающего перед началом работы 3. Создайте feature ветку: feature/feature-name 4. Реализуйте функцию, следуя нашим архитектурным паттернам 5. Добавьте комплексные тесты 6. Обновите документацию 7. Отправьте pull request

Требования: - Следуйте архитектурному паттерну MVVM - Включите модульные тесты для бизнес-логики - Включите тесты виджетов для компонентов UI - Обновите пользовательскую документацию при необходимости - Добавьте документацию API для новых сервисов

3. Улучшения документации¶

Процесс: 1. Создайте ветку документации: docs/improvement-description 2. Внесите изменения 3. Протестируйте сборки документации локально 4. Отправьте pull request

Требования: - Следуйте нашему руководству по стилю документации - Включите примеры кода где уместно - Убедитесь, что все ссылки работают правильно - Обновите содержание при необходимости

4. Улучшения производительности¶

Процесс: 1. Создайте задачу, описывающую проблему производительности 2. Включите бенчмарки или данные профилирования 3. Создайте ветку производительности: perf/improvement-description 4. Реализуйте улучшения 5. Предоставьте метрики производительности до/после 6. Отправьте pull request

Требования: - Включите бенчмарки производительности - Убедитесь, что функциональность не нарушена - Документируйте любые изменения API - Добавьте тесты для критичного к производительности кода

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

Требования к архитектуре¶

Паттерн MVVM: Все экраны UI должны следовать паттерну Model-View-ViewModel
Внедрение зависимостей: Используйте паттерн service locator для управления зависимостями
Паттерн Repository: Доступ к данным должен проходить через интерфейсы репозиториев
Сервисный слой: Бизнес-логика принадлежит классам сервисов

Стандарты качества кода¶

Null Safety: Весь код должен быть null-safe
Обработка ошибок: Правильная обработка исключений со специфическими типами исключений
Управление ресурсами: Правильное освобождение ресурсов (потоки, контроллеры и т.д.)
Производительность: Эффективное построение виджетов и использование памяти

Пример реализации¶

// Хорошо: Следование паттерну MVVM
class MosquitoGalleryViewModel extends ChangeNotifier {
  final MosquitoRepository _repository;

  List<MosquitoModel> _mosquitoes = [];
  bool _isLoading = false;
  String? _error;

  MosquitoGalleryViewModel({required MosquitoRepository repository})
      : _repository = repository;

  List<MosquitoModel> get mosquitoes => _mosquitoes;
  bool get isLoading => _isLoading;
  String? get error => _error;

  Future<void> loadMosquitoes() async {
    _setLoading(true);
    try {
      _mosquitoes = await _repository.getAllMosquitoes();
      _error = null;
    } catch (e) {
      _error = 'Failed to load mosquitoes: $e';
    } finally {
      _setLoading(false);
    }
  }

  void _setLoading(bool loading) {
    _isLoading = loading;
    notifyListeners();
  }
}

Требования к тестированию¶

Ожидания покрытия тестами¶

Модульные тесты: Все классы сервисов и модели представления должны иметь модульные тесты
Тесты виджетов: Все пользовательские виджеты должны иметь тесты виджетов
Интеграционные тесты: Критические пользовательские потоки должны иметь интеграционные тесты

Структура тестов¶

void main() {
  group('MosquitoGalleryViewModel', () {
    late MosquitoGalleryViewModel viewModel;
    late MockMosquitoRepository mockRepository;

    setUp(() {
      mockRepository = MockMosquitoRepository();
      viewModel = MosquitoGalleryViewModel(repository: mockRepository);
    });

    group('loadMosquitoes', () {
      test('should load mosquitoes successfully', () async {
        // Arrange
        final mosquitoes = [MosquitoModel(id: 1, name: 'Aedes aegypti')];
        when(mockRepository.getAllMosquitoes())
            .thenAnswer((_) async => mosquitoes);

        // Act
        await viewModel.loadMosquitoes();

        // Assert
        expect(viewModel.mosquitoes, equals(mosquitoes));
        expect(viewModel.isLoading, isFalse);
        expect(viewModel.error, isNull);
      });

      test('should handle errors gracefully', () async {
        // Arrange
        when(mockRepository.getAllMosquitoes())
            .thenThrow(Exception('Network error'));

        // Act
        await viewModel.loadMosquitoes();

        // Assert
        expect(viewModel.mosquitoes, isEmpty);
        expect(viewModel.isLoading, isFalse);
        expect(viewModel.error, contains('Network error'));
      });
    });
  });
}

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

# Запустить все тесты
flutter test

# Запустить конкретный тестовый файл
flutter test test/unit/view_models/mosquito_gallery_view_model_test.dart

# Запустить тесты с покрытием
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html

Руководящие принципы подачи¶

Процесс Pull Request¶

Чек-лист перед подачей
Код следует руководящим принципам стиля
Все тесты проходят
Документация обновлена
Сообщения коммитов следуют соглашениям
Ветка актуальна с main
Шаблон Pull Request Используйте наш шаблон PR для обеспечения включения всей необходимой информации:
Описание изменений
Тип изменения (исправление ошибки, функция и т.д.)
Выполненное тестирование
Скриншоты (для изменений UI)
Критические изменения (если есть)
Процесс рецензирования
Требуется как минимум одно рецензирование сопровождающего
Все проверки CI должны пройти
Обратитесь ко всей обратной связи рецензирования
Сожмите коммиты при запросе

Руководящие принципы рецензирования кода¶

Для участников: - Отвечайте на обратную связь оперативно - Задавайте вопросы, если обратная связь неясна - Вносите запрошенные изменения в отдельных коммитах - Обновляйте тесты и документацию по мере необходимости

Для рецензентов: - Будьте конструктивными и конкретными в обратной связи - Объясняйте обоснование предложений - Одобряйте, когда код соответствует стандартам - Тестируйте функциональность когда возможно

Руководящие принципы сообщества¶

Кодекс поведения¶

Мы привержены созданию гостеприимной и инклюзивной среды для всех участников. Пожалуйста, прочитайте и следуйте нашему Кодексу поведения:

Будьте уважительными: Относитесь ко всем членам сообщества с уважением и добротой
Будьте инклюзивными: Приветствуйте новичков и помогайте им начать
Будьте конструктивными: Предоставляйте полезную обратную связь и предложения
Будьте профессиональными: Поддерживайте профессиональный тон во всех взаимодействиях

Каналы коммуникации¶

GitHub Issues: Отчеты об ошибках, запросы функций и обсуждения
Pull Requests: Рецензирование кода и технические обсуждения
Discussions: Общие вопросы и обсуждения сообщества

Признание¶

Мы ценим все вклады в проект:

Участники перечислены в нашем README
Значительные вклады выделяются в заметках о релизе
Регулярные участники могут быть приглашены присоединиться к команде сопровождающих

Получение помощи¶

Ресурсы¶

Документация: Сначала проверьте нашу комплексную документацию
Issues: Поищите существующие задачи для похожих проблем
Discussions: Используйте GitHub Discussions для вопросов
Примеры кода: Посмотрите на существующий код для паттернов и примеров

Просьба о помощи¶

При просьбе о помощи, пожалуйста, предоставьте:

Четкое описание: Что вы пытаетесь сделать и что не работает
Детали окружения: ОС, версия Flutter, информация об устройстве
Примеры кода: Минимальный воспроизводимый пример
Сообщения об ошибках: Полные сообщения об ошибках и трассировки стека
Предпринятые шаги: Что вы уже попробовали

Наставничество¶

Новые участники могут запросить наставничество:

Комментируйте в задачах, прося руководства
Упоминайте @maintainers в обсуждениях
Начинайте с элементов, помеченных как "good first issue"
Работайте в паре с опытными участниками над сложными функциями

Лучшие практики разработки¶

Соображения производительности¶

Оптимизация виджетов
Используйте const конструкторы где возможно
Реализуйте shouldRebuild для дорогих виджетов
Избегайте создания виджетов в методах build
Управление памятью
Правильно освобождайте контроллеры и потоки
Используйте слабые ссылки для обратных вызовов
Отслеживайте использование памяти во время разработки
Оптимизация модели ИИ
Оптимизируйте загрузку модели и вывод
Реализуйте правильные стратегии кэширования
Эффективно обрабатывайте обновления модели

Соображения безопасности¶

Конфиденциальность данных
Следуйте руководящим принципам GDPR и конфиденциальности
Минимизируйте сбор данных
Обеспечьте безопасную передачу данных
Безопасность API
Валидируйте все входы
Используйте безопасную аутентификацию
Реализуйте ограничение скорости

Доступность¶

Поддержка программы чтения с экрана
Добавьте семантические метки ко всем интерактивным элементам
Предоставьте альтернативный текст для изображений
Обеспечьте правильное управление фокусом
Визуальная доступность
Поддерживайте достаточный цветовой контраст
Поддерживайте системное масштабирование шрифтов
Предоставьте визуальную обратную связь для взаимодействий

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

Управление версиями¶

Мы следуем семантическому версионированию (SemVer): - Major: Критические изменения - Minor: Новые функции (обратно совместимые) - Patch: Исправления ошибок (обратно совместимые)

Цикл релиза¶

Разработка: Функции разрабатываются в feature ветках
Тестирование: Комплексное тестирование перед релизом
Release Candidate: Тестирование перед релизом
Релиз: Помеченный релиз с журналом изменений
После релиза: Мониторинг проблем и hotfixes

Заключение¶

Спасибо за участие в CulicidaeLab! Ваши вклады помогают продвигать исследования комаров и инициативы общественного здравоохранения по всему миру. Следуя этим руководящим принципам, вы помогаете поддерживать качество кода и обеспечиваете положительный опыт для всех участников.

По вопросам об этих руководящих принципах или процессе участия, пожалуйста, откройте задачу или начните обсуждение. Мы здесь, чтобы помочь вам преуспеть как участнику проекта.

Удачного участия! 🦟🔬📱