Правила работы с репозиториями

Общие положения

Версионирование

Что это такое?

Заранее определенная методика назначения версий для разрабатываемых пакетов, модулей и т.п. Почти во всех случаях используется semver. Обязательно к прочтению: https://semver.org/lang/ru/

Для чего?

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

Как пользоваться?

Новые версии создаются с помощью lerna version. См. https://github.com/lerna/lerna/tree/master/commands/version Т.к. пушить в дев напрямую нельзя, то релизы заводятся через отдельную ветку с PR. Ветку называем chore/release. Льем на GH. После этого запускаем lerna version --conventional-commits. conventional-commits нужен для того, чтобы правильно собрать CHANGELOG.md. После выполнения команды льем коммиты в тукущую ветку и заводим PR. Релиз готов.

С какой версии начинать новые пакеты? (см. монорепо)

Новый пакет всегда начинается с 0.0.0. Не 0.0.1, не 1.0.0. Только 0.0.0. lerna version сам потом назначит нужную версию, если возникнет такая необходимость.

Структура репозиториев

В проектах используется монорепо. Т.е. бекенд, фронтенд, девопс и прочее, все находится одном репозитории. Разбивка выполнена в корневой части:

• backend
• devops
• frontend
• etc

Для чего?

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

Процесс работы с кодом

Работа с коммитами

• Conventional Commits

Как делать коммиты?

В проектах используется инструмент для создания коммитов, которые соответствуют commit conventional.

Команда для создания коммита: yarn commit. Запустится визард, в котором пошагово нужно будет заполнить необходимые параметры.

Скоупы выбираются в зависимости от модуля и места, в котором были внесены изменения.

Типы веток указываются в соотвествии с типом изменений. Новая фича - feat, фикс - fix, настройка окружения, обновление пакетов - chore. И т.д.

WIP Commit

Для чего нужно?

Используется при старте работы над объемной задачей. В этом коммите обозначаем наши намерения по изменению кода. Следует указать, что будет изменено, выпилено, сломано и т.п. Набросать скелет, оставить заглушки и реализовать фичи таким образом, чтобы проект запускался, но при этом бизнес логику в полном объеме можно не реализовывать. Это напоминает разработку mockов для тестов. Такой коммит позволит другим участникам подготовиться к изменениям. Также это способствует диалогу, который может возникнуть на ранней стадии разработки и который позволит избежать сложных ситуаций, когда движение идет не в том направлении.

Пример

Пример из жизни. Выпиливание визитов из avisits.

0. Изучается задача.
1. Создается ветка.
2. Из кода выпиливается сущность визита. Логика аннулируется, вместо нее вставляются заглушки, которые позволяют оценить принцип работы.
3. Проект приводится в рабочее состояние, которое позволит запустить его и выполнить взаимодействие с ним.
4. Формируется коммит WIP, в визарде yarn commit есть этот тип. При необходимости в коммите указываются breaking change.
5. Отправляется на github.
6. Создается PR.

Что происходит дальше?

PR с этим коммитом в dev не мержится до тех пор, пока не прилетят другие коммиты, которые восстанавливают бизнес логику в рабочее состояние.

Сам WIP коммит никуда не убирается, он остается. Выпилить и ребейзить не нужно.

Работа с пулл реквестами (PR)

Как создавать?

Creating a pull request

Когда создавать?

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

Кого ставить в assignee?

Указываем себя, как автора. Это позволит потом по PR делать фильтрацию и получает предсказуемые результаты.

Кого указывать в ревьюверах?

Фронт: @torinasakura Бекенд: @torinasakura, @aleserche

Что за статусы проверок?

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

Можно ли форсить ветку?

Можно, но только если от этого больше пользы, чем вреда. Когда можно:

1. Когда ревью еще не провели.
2. Когда в ветку еще ничего не вливали (обновленный dev)
3. Когда PR на этой ветке еще нет.

Когда нельзя:

1. Когда ревью провели. Комментарии привязываются к хешу коммитов. Если форснуть, то это уже новые коммиты, даже если в них ничего не менялось. Из-за этого весь прогресс ревью тупо слетает. В итоге ревьюверу нужно потратить время, чтобы определиться, где он оставлял ревью, а где нет.
2. Когда форсом можно ненароком ввести в заблуждение. После форса достаточно муторно посмотреть, что же в итоге изменилось. Можно, конечно, выдрать хеши и пойти в diff, чтобы посмотреть, что изменилось.

Лучше пусть будут лишние коммиты (коммиты лишними не бывают), так процесс выглядит более прозрачным и последовательным.

Работа с ветками (branch)

Основной принцип

В целом на таску (issue) заводим одну ветку. В одну ветку можно загнать несколько issue, если они связаны между собой.

От чего отпочковываться?

Все новые ветки создаются от dev. Но есть исключение: middlebranch. Если есть задача, в которой неизбежна поломка одной из частей (фронт или бек), то заводится middlebranch. Далее уже от этой ветки формируются ветки для задач и в нее же вливаются наработки через PR. Когда ветка middlebranch укомплектована и работоспособна до такой степени, что фронт или бек не конфликтуют, формируется PR для вливания в dev. Дальнейшие фиксы и фичи готовятся в штатном режиме через dev.

Обновление веток

Нужно внимательно следить за тем, чтобы ветка вовремя обновлялась (пока задача пилится, dev может измениться). Иначе можно случайно пропустить момент, когда обновления ломают новые наработки.

Работа с Issues

Где брать задачи

Следует нажать на Issues в навигационной панели Github и посмотреть задачи там. Если там задач нет, то обратиться к PM'у (@aroundblacksneverrelax), в крайнем случае к руководителю (@torinasakura).

Что делать, если нет задач

Если такая ситуация возникла, то нужно обратиться к PM'у (@aroundblacksneverrelax), в крайнем случае к руководителю (@torinasakura).

Как вести обсуждение задачи или Issue в Github

Что бы обсуждение было наиболее эффективным, следует соблюдать несколько простых правил и рекомендаций:

1. Используй цитирование. В Github не предусмотрена система тредов внутри Issue из-за этого в обсуждениях может происходить путаница. Что бы не запутаться мы используем инструмент цитирования — ">". Это позволяет сохранять нить обсуждения и «не распыляться» в обсуждении.
2. Пожалуйста, старайся писать грамотно. Ни в коем случае не претендую на великого грамотея и знатока русского языка и кроме этого я не сомневаюсь в личной грамотности членов команды, но кажется что этот пункт должен быть в данном списке. Если в данных предложениях есть ошибки - прошу написать в комментарии и исправить меня :)
3. Старайся четко формулировать вопросы и мысли, от этого может зависеть качество ответа на вопрос или качество обсуждения идеи. Если спрашивать не очень четко сформулировав вопрос или не очень внятно описав идею, есть высокая вероятность получить такой же невнятный ответ или пустой разговор. Очень хороший приём - обязательно перечитать свой текст перед тем как отправлять его.
4. Используй Markdown. В дополнении к предыдущему пункту, советую освоить Markdown. Он позволит твоей мысли быть четкой, ясной и понятной. Такой текст легче воспринимать.
5. Сдерживай себя, если вам хочется едко (или как говорят - токсично) пошутить в чей-либо адрес. Процесс совместной работы при помощи Github хотелось бы поставить хорошо и надолго, по этому тут не место. Если очень хочется отчебучить едкую неприличную шутку - это можно сделать в чате или в личном разговоре, Github - для дел и работы.

Как фильтровать Issues

Filtering issues and pull requests

Что за лейблы

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

• Priority — приоритет
• Scope — скоуп, т.е затрагиваемая «область» issue
• Type — тип issue, задача, баг, тест и т.п

Как понимать приоритеты

Все просто, приоритета у нас два:

• Normal — задача выполняется в обычном порядке (тот порядок, который сообщил тебе PM или руководитель) и в рабочем режиме.
• Critical — задача выполняется в неотложном порядке. Все задачи с приоритетом Normal откладываются в сторону. Как правило задачи с приоритетом Critical это какие-то супер приоритетные фичи или аварии.