Правила работы с GitHub
Для более эффективной работы, мы в своей команде используем Github. Для нас GitHub это место где находится вся необходимая информация для работы и место где находится истина — код.
Github в нашей команде используют все: разработчики, дизайнеры, менеджеры, заказчики и все все все. Все находятся в одной среде и все всё видят. И это прекрасно. Но для того чтобы использовать GitHub эффективно, к нему надо привыкнуть и его надо освоить.
В этом кратком руководстве, мы собрали собственные командные практики работы с GitHub. Также здесь есть ссылки на официальные руководства GitHub для расширения кругозора.
Issues — это место где мы обсуждаем всю важную работу, от начала (создание issue) и до конца (закрытие issue).
Важно чтобы обсуждение по той или иной задаче/проблеме проходило внутри Issue. Это позволяет отследить историю в случае возникновения такой проблемы, а также даёт возможность просто делиться ссылкой на Issue или конкретный комментарий внутри Issue.
Сам по себе Issue не несёт никакого «смыслового окраса». Для этого, мы применяем лейблы.
Например:
- Issue с лейблом documents — это задача или проблема, которая относится к документации
- Issue с лейблом feature — означает что там лежит какая-то информация о фиче
- Issue с лейблом bug, ну ты понял
Поэтому очень желательно, чтобы Issues не оставались без лейблов. Список доступных лейблов доступен с правой стороны Issue, заголовок Labels:
Управление Лейблами на GitHub Docs
Markdown — это облегчённый язык разметки. Эта разметка позволяет сделать текст жирным или наклонным (италик).
Делать удобные для отображения списки:
- Раз
- Два
- Три
А также цитировать своих собеседников:
Привет! Всё готово к релизу, погнали?
Чел, сегодня пятница, какой релиз :|
Весь этот набор разметки, позволяет сделать самое главное: писать красивые и чётко сформулированные мысли в текстовом виде.
Это очень важно для командной работы. Потому что текст в Issues потеряется в самую последнюю очередь. А хорошо сформулированная мысль, позволит быстро донести суть до своих собеседников.
Поэтому важно ознакомиться с Основным синтаксисом письма и форматирования Markdown на GitHub Docs. Там же есть секция с продвинутыми практиками.
Все ветки git имеют начало - ветка может стартовать от какого-то коммита master, а может из коммита любой другой ветки. В любом случае есть стартовый "базовый" коммит.
Что делать, если вы стартовали/базировались с одного коммита, а пока работали, ветка, с которой вы "базировались", ушла дальше - появились в ней новые коммиты, напр. другие ПР были вмержены? Есть два пути:
- мерж
- ребейз
Разница между rebase и merge:
Из сравнения видно, что merge создает дополнительный коммит мержа, а так же делает картину метро в истории коммитов. Поэтому предпочтение отдается rebase - лишних коммитов нет, история коммитов линейная и красивая.
Ребейз, как следует из названия - это операция по изменению базиса вашей ветки. Т.е. изменить коммит, с которого вашего ветка стартовала. Нагляднее всего будет измученная картинка:
Т.к. обычно операция merge не вызывает сложностей, остановимся на rebase.
Его можно делать если:
- вы работаете один на ветке либо заранее договорились со всеми коллегами по ветке что будете это делать. Ведь эта операция перепишет историю коммитов для всех!
- до чьего либо ревью
В остальных случаях - только мерж.
Как его делать?
- В IDE
Cmd + 9(Ctrl + 9) для открытия панели git:
- Обновляем ветку от которой хотим провести ребейз. Например, ваша ветка базируется на мастере, значит нужно обновить локально мастер:
- Начинаем ребейз. Находясь на вашей рабочей ветке, кликаем по той ветке по которой хотим "перебазироваться":
-
Далее начинается операция по ребейзу - git проходится по истории коммитов вашей ветки и ветки от которой вы хотите перебазироваться и сравнивает есть ли конфликты. Если есть - высвечивает предлагая выбор что вы хотите внести в вашу ветку - изменения вашей ветки или изменения ветки с которой вы перебазируетесь. ВНИМАНИЕ:
yarn.lock,pnp.cjs,pnp.loader.mjsможете выбирать любое ЦЕЛИКОМ на ваш "вкус" - хоть с вашей ветки хоть с другой. Эти файлы генерируются командойyarnв корней проекта, поэтому даже если накосячите, всегда можно перегенерировать. -
После окончания ребейза вам высветиться такое:
- На этом этапе важно понимать - вы сделали ребейз только локально. Ваша локальная ветка перебазировалась. Однако ремоут, ваша ветка на сервере, все еще прежняя. Необходимо обновить и ее. Если вы попробуете просто
git push(или для продвинутыхCmd + Shift + K(Ctrl + Shift + K)) то вам высветится ошибка - необходимо принять ремоут изменения прежде чем пушить локал. Соответственно теперь наша цель - совместить/"переписать" изменения локальные на ремоут. Это можно сделать следующим образом:
-
git push --force-with-leaseили его эквивалент в IDECmd + Shift + K(Ctrl + Shift + K):
ВНИМАНИЕ: сделав это вы перетрете все хэши коммитов. Если вы это сделаете после чьего либо ревью - их комментарии перетрутся и история замечаний потеряется. Поэтому повторим - ребейз делаем только до чьего либо ревью.
Pull Requests позволяют вам сообщить другим об изменениях, которые вы внесли в ветку в репозитории на GitHub. После открытия Pull Request'а вы можете обсудить и просмотреть потенциальные изменения с коллегами и добавить последующие коммиты до того, как ваши изменения будут объединены в базовую ветку.
Из документации к Pull Request'ам на GitHub Docs
Создание Pull Request'а на Github Docs
Можно сразу после первых коммитов. Ежедневно, к концу рабочего дня должно коммититься текущее состояние вашей ветки. Если пр не готов к ревью - он отправляется в драфт (также по этой причине нет смысла использовать WIP в коммит месседжах: если работа в процессе - пр находится в драфте)
Это необходимо для прозрачности процесса, чтобы вовремя выявить недочеты при написании кода, пока кодовая база вокруг них не разрослась, они не остались незамеченными и не превратились в легаси.
В будущем такой подход также помогает при навигации по истории коммитов.
Указываем себя, как автора. Это позволит потом по PR делать фильтрацию и получает предсказуемые результаты.
Лида (ментора) или если таковой отсутствует - @torinasakura
У проектов могут быть настроены проверки проектов, которые выполняются при создании и обновлении Pull Request'а. В них можно получить всю необходимую информацию о выполнении тестов.
Можно, но только если от этого больше пользы, чем вреда. Когда можно:
- Когда ревью еще не провели.
- Когда в ветку еще ничего не вливали (обновленный dev)
- Когда PR на этой ветке еще нет.
Когда нельзя:
- Когда ревью провели. Комментарии привязываются к хешу коммитов. Если форснуть, то это уже новые коммиты, даже если в них ничего не менялось. Из-за этого весь прогресс ревью тупо слетает. В итоге ревьюверу нужно потратить время, чтобы определиться, где он оставлял ревью, а где нет.
- Когда форсом можно ненароком ввести в заблуждение. После форса достаточно муторно посмотреть, что же в итоге изменилось. Можно, конечно, выдрать хеши и пойти в diff, чтобы посмотреть, что изменилось.
Лучше пусть будут лишние коммиты (коммиты лишними не бывают), так процесс выглядит более прозрачным и последовательным.
«Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов.
Цитата из официального документа соглашения
Мы придерживаемся данного соглашения и требуем этого от всех разработчиков, членов нашей команды. Поэтому данное соглашение нужно изучить и соблюдать в своей работе.
Важно! Никакой кириллицы ни в коде, ни в комментариях к коммитам, ни в названиях бранчей быть не должно
Эффективная работа в GitHub для нас очень важна. Здесь протекает вся рабочая «жизнь» проектов над которыми мы работаем. Поэтому для нас важно, чтобы каждый соблюдал базовые правила работы с этим инструментом.
Вообще, у GitHub довольно обширная и полезная документация, с которой рекомендуется ознакомиться.
Если незнаком или мало опыта с Git, то вот полезный тур на русском языке по нему. Чёрт побери, Git!?! быстрая и понятная подсказка по Git'у. Или Интерактивная визуализация и учебник по Git.