Правила работы с GitHub

Для более эффективной работы, мы в своей команде используем Github. Для нас GitHub это место где находится вся необходимая информация для работы и место где находится истина — код.

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

В этом кратком руководстве, мы собрали собственные командные практики работы с GitHub. Также здесь есть ссылки на официальные руководства GitHub для расширения кругозора.

НАВИГАЦИЯ

• Работа с Issues

Отдельно про Markdown

Markdown — это облегчённый язык разметки. Эта разметка позволяет сделать текст жирным или наклонным (италик).

Делать удобные для отображения списки:

• Раз
• Два
• Три

А также цитировать своих собеседников:

Привет! Всё готово к релизу, погнали?

Чел, сегодня пятница, какой релиз :|

Весь этот набор разметки, позволяет сделать самое главное: писать красивые и чётко сформулированные мысли в текстовом виде.

Это очень важно для командной работы. Потому что текст в Issues потеряется в самую последнюю очередь. А хорошо сформулированная мысль, позволит быстро донести суть до своих собеседников.

Поэтому важно ознакомиться с Основным синтаксисом письма и форматирования Markdown на GitHub Docs. Там же есть секция с продвинутыми практиками.

Работа с Rebase

Все ветки git имеют начало - ветка может стартовать от какого-то коммита master, а может из коммита любой другой ветки. В любом случае есть стартовый "базовый" коммит.

Что делать, если вы стартовали/базировались с одного коммита, а пока работали, ветка, с которой вы "базировались", ушла дальше - появились в ней новые коммиты, напр. другие ПР были вмержены? Есть два пути:

• мерж
• ребейз

Разница между rebase и merge:

Из сравнения видно, что merge создает дополнительный коммит мержа, а так же делает картину метро в истории коммитов. Поэтому предпочтение отдается rebase - лишних коммитов нет, история коммитов линейная и красивая.

Ребейз, как следует из названия - это операция по изменению базиса вашей ветки. Т.е. изменить коммит, с которого вашего ветка стартовала. Нагляднее всего будет измученная картинка:

Т.к. обычно операция merge не вызывает сложностей, остановимся на rebase.

Его можно делать если:

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

В остальных случаях - только мерж.

Как его делать?

1. В IDE Cmd + 9 (Ctrl + 9) для открытия панели git:

2. Обновляем ветку от которой хотим провести ребейз. Например, ваша ветка базируется на мастере, значит нужно обновить локально мастер:

3. Начинаем ребейз. Находясь на вашей рабочей ветке, кликаем по той ветке по которой хотим "перебазироваться":

4. Далее начинается операция по ребейзу - git проходится по истории коммитов вашей ветки и ветки от которой вы хотите перебазироваться и сравнивает есть ли конфликты. Если есть - высвечивает предлагая выбор что вы хотите внести в вашу ветку - изменения вашей ветки или изменения ветки с которой вы перебазируетесь. ВНИМАНИЕ: yarn.lock, pnp.cjs, pnp.loader.mjs можете выбирать любое ЦЕЛИКОМ на ваш "вкус" - хоть с вашей ветки хоть с другой. Эти файлы генерируются командой yarn в корней проекта, поэтому даже если накосячите, всегда можно перегенерировать.

5. После окончания ребейза вам высветиться такое:

6. На этом этапе важно понимать - вы сделали ребейз только локально. Ваша локальная ветка перебазировалась. Однако ремоут, ваша ветка на сервере, все еще прежняя. Необходимо обновить и ее. Если вы попробуете просто git push (или для продвинутых Cmd + Shift + K (Ctrl + Shift + K)) то вам высветится ошибка - необходимо принять ремоут изменения прежде чем пушить локал. Соответственно теперь наша цель - совместить/"переписать" изменения локальные на ремоут. Это можно сделать следующим образом:

• git push --force-with-lease или его эквивалент в IDE Cmd + Shift + K (Ctrl + Shift + K):

ВНИМАНИЕ: сделав это вы перетрете все хэши коммитов. Если вы это сделаете после чьего либо ревью - их комментарии перетрутся и история замечаний потеряется. Поэтому повторим - ребейз делаем только до чьего либо ревью.

Работа с Pull Request

Pull Requests позволяют вам сообщить другим об изменениях, которые вы внесли в ветку в репозитории на GitHub. После открытия Pull Request'а вы можете обсудить и просмотреть потенциальные изменения с коллегами и добавить последующие коммиты до того, как ваши изменения будут объединены в базовую ветку.

Из документации к Pull Request'ам на GitHub Docs

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

Создание Pull Request'а на Github Docs

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

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

Это необходимо для прозрачности процесса, чтобы вовремя выявить недочеты при написании кода, пока кодовая база вокруг них не разрослась, они не остались незамеченными и не превратились в легаси.

В будущем такой подход также помогает при навигации по истории коммитов.

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

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

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

Лида (ментора) или если таковой отсутствует - @torinasakura

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

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

Можно ли форсить ветку (push --force)?

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

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

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

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

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

Conventional Commits или Соглашение о коммитах

«Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов.

Цитата из официального документа соглашения

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

Важно! Никакой кириллицы ни в коде, ни в комментариях к коммитам, ни в названиях бранчей быть не должно

Post Scriptum

Эффективная работа в GitHub для нас очень важна. Здесь протекает вся рабочая «жизнь» проектов над которыми мы работаем. Поэтому для нас важно, чтобы каждый соблюдал базовые правила работы с этим инструментом.

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

Если незнаком или мало опыта с Git, то вот полезный тур на русском языке по нему. Чёрт побери, Git!?! быстрая и понятная подсказка по Git'у. Или Интерактивная визуализация и учебник по Git.