Регламент работы с GitHub и VCS

[Vl-Tershch]

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

Командное пространство организовано на платформе GitHub в рамках репозитория. Управление задачами, планирование, хранение документов и артефактов разработки ведется в нем.

Работа с репозиторием

Issues, Projects & Discussions

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

GitFlow

Контроль изменений осуществляется в соответствии с практиками GitFlow и конвенциями использования системы git. Разработка ведется в ветке development, в master’e только готовый код, из которого потом собирается актуальная версия приложения. Каждый человек ведет разработку своей задачи/фичи в отдельной ветке и затем выполняется слияние рабочей ветки в development с помощью механизма Pull Requests, после этого ветка удаляется. Каждое сообщение о коммите пишется на английском языке в соответствии с общими гит-конвенциями(feat/fix/refactor/docs/...). Каждый коммит состоит из префикса типа изменений + : + (номер задачи) + сообщение, например "[feat]: #9999 added new algorithm".

Название ветки формируется из аббревиатуры проекта (E) и уникального кода над задачей. Таким образом, в качестве примера, название рабочей ветки разработчика может иметь вид: E-2.

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

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

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

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

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

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

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

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