Соглашения о командной разработке проектов в рамках лаборатории LISA-ITMO

Основные пространства

  1. Проектные репозитории команды должны быть расположены в организации LISA-ITMO;
  2. Командное пространство предлагается организовать на платформе GitHub в рамках репозитория. Управление задачами, планирование, хранение документов/артефактов разработки ведется в нем.

❗ Однако на усмотрение команды возможно использование других инструментов для организации командной работы, например платформу Space. В таком случае все задачи должны дублироваться в раздел Issues на GitHub’е и каждый запрос на слияние (Pull Request) должен быть связан с этими задачами. Все важные моменты/соглашения должны дублироваться в раздел Issues, а дискуссионные моменты - в обсуждения (раздел Discussions) репозитория на GitHub.

Работа с репозиторием на платформе GitHub и контроль версий

Issues, Projects & Discussions

В рамках работы над проектом формируется набор задач, которые нужно выполнить для достижения целей проекта, или текущей итерации разработки. Каждой задаче назначается исполнитель (или несколько), который ведет непосредственную работу над ней. Дополнительно навешиваются тематические теги для упрощения навигации, привязывается Project и проставляется текущий Milestone. Задачи размещаются на доске в GitHub (или другом аналоге), и каждый участник команды обязан вовремя менять их статус в рамках разделов доски.

Все задачи, при использовании другой системы контроля проекта, дублируются в раздел Issues на платформе GitHub, им назначаются аналогичные исполнители, добавляется описание, навешиваются теги. В комментариях к задачам английским (желательно) языком пишутся важные нюансы, возникшие в процессе ее решения. Обсуждения в разделе Discussions на GitHub также ведутся на английском (желательно) языке. Если у команды есть желание, можно использовать подписи на русском языке, как дополнительные.

GitFlow

Контроль изменений осуществляется в соответствии с практиками GitFlow и конвенциями использования системы git. Разработка ведется в ветке development, в main’e только готовый код, из которого потом собирается актуальная версия приложения. Каждый человек ведет разработку своей задачи/фичи отдельной ветке и затем выполняется слияние рабочей ветки в development с помощью механизма Pull Requests, после этого ветка удаляется. Каждое сообщение о коммите пишется на английском языке в соответствии с общими гит-конвенциями(feat/fix/refactor/docs/…). Предлагается формировать название веток из аббревиатуры проекта и уникального кода над задачей. Таким образом, в качестве примера, название рабочей ветки разработчика может иметь вид: E-2.

После окончания разработки изменения необходимо отправить на GitHub, и разработчик задачи открывает запрос на слияние(Pull Request) в ветку development. Страница Pull Request’a заполняется полностью по аналогии с задачей и происходит связывание с Issue в разделе Development, когда открывается запрос на слияние необходимо назначить ваших менторов и коллег по задачам в поле Assignees для проведения Code Review. После прохождения ревью, исправления замечаний (если они возникли), выполняется слияние задачи, удаление ветки и закрытие задачи.

Какие-то моменты/баги вносятся в раздел Issues на GitHub, из которого формируются новые задачи на разработку или в иные системы управления проектом, которые дублируются в Issues.

❗ ВАЖНО: слияние открытого запроса выполняется при наличии одобрения от ревьюеров.

❗ ВАЖНО: если вы понимаете, что необходимо добавить какую-то новую задачу, или декомпозировать текущую - смело можете создавать новые задачи после обсуждения с вашими менторами.

Написание кода проекта

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

Весь код должен иметь док-комментарии (javadoc, docstring) для методов/функций, объектов. Важные строки кода помечаются обычными комментариями. Весь написаный новый код должен быть сразу покрыт модульными тестами. Таким образом код-ревью нового функционала не должно быть пройдено, если они не имеют тестов, если не проходят старые тесты (в этом случае может потребоваться изменение старых тестов) или если не принято решение ведущими разработчиками/руководителем о необходимости слиянии таких изменений.

Оформление репозитория

Репозиторий должен иметь понятную архитектуру с точки зрения структурирования кода и содержать пакеты с исходным кодом проекта, модульными/интеграционными тестами, документацией, примерами использования, файлы LICENSE.md и README.md. README-файл должен быть заполнен и содержать следующие разделы:

  1. Шапка файла содержит бэйджи с полезной информацией о проекте (например версии языков, результаты выполнения пайплайнов, отчеты о тестировании);
  2. Description - короткое описание проекта;
  3. Features - описание самых главных функциональных особенностей проекта;
  4. Installation - детальное описание как начать работать с проектом и запустить его у себя;
  5. Getting Started/Examples - описание как начать работать с продуктом, или ссылка на примеры работы из пакета examples;
  6. Documentation - короткая документация кодовой базы проекта, содержащая ссылку на более обширную;
  7. Requirements - используемые в проекте зависимости/библиотеки/фреймворки;
  8. Contacts - раздел с информацией для получения обратной связи/откликов/вопросов;
  9. Conferences - результаты апробации исследования.

❗ ВАЖНО: если разработка ведется в рамках репозиториев лабораторий МФ ТиНТ, в организации LISA-ITMO должен быть заведен отдельный репозиторий, содержащий README.md файл с информацией о проекте и ссылками с описанием вашего вклада(коммиты, PRs).

CI/CD и другие интеллектуальные инструменты

В каждом проектном репозитории должен быть настроен CI/CD для работы с GitHub Actions. Его содержимое может быть любым, однако минимально он должен содержать запуск модульных тестов проекта, которые будут запускаться при каждом Push’е и Pull Requets’е. Дополнительно можно настроить пайплайн по сборке и публикации документации на основании имеющихся в проекте docstrings. Вы можете настроить ряд других инструментов, для повышения качества вашей кодовой базы, например pep8speaks или CodeCov. Подробнее об этом можно узнать в записи встречи.

Также рекомендуется изучить опыт оформления и ведения проектных репозиториев коллег AimClub и ознакомиться с подготовленными ими материалами, за что мы выражаем им огромную благодарность!

Вы можете опираться на следующие проектные репозитории для вдохновения: