Git и GitHub — очень мощные инструменты для взаимодействия нескольких человек. Они относительно сложные и требуют определённого уровня понимания и дисциплины. Но взамен мы получаем удобную работу и отличный результат.

Основная ветка master всегда защищена от прямых коммитов. Это нужно для того, чтобы все изменения проходили ревью, а автоматизированные скрипты развёртывания не отрабатывали, пока порция изменений не отполирована. Поэтому, чтобы начать что-то менять, создайте собственную ветку:

# Становимся в master
git checkout master
 
# Убеждаемся, что мы на последней версии
git pull origin master --fast-forward
 
# Отбранчёвываемся
git checkout -b feat-42-support-spi

По конвенции имя топик-ветки строится из трёх частей:

1. Префикс feat, fix, tweak, chore, test, doc в зависимости от типа изменений
2. (опционально) Номер issue, которую закрывает ветка
3. Мнемоника о сути изменений

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

Пример хорошего лога:

• chore(quaddisplay): format old code with prettier
• feat(quaddisplay): support for hardware SPI along with software
• tweak(quaddisplay): obsolete constructors

Сообщение коммита строится из трёх частей:

• Префикс feat, fix, tweak, chore, test, doc в зависимости от типа изменений
• (опционально) Скоуп, если репозиторий большой или монореп
• Суть изменений, без артиклей, скупым языком

Суммарно сообщение должно быть до 72 символов. Если этого мало, пишите подробности в body сообщения

После любого коммита можно и даже нужно пушить в облако, чтобы не потерять работу в случае катастрофы и всегда иметь к ней доступ:

git push origin

Когда код готов, его нужно подготовить к pull request’у (далее PR). Пока вы работали над веткой, master мог уехать вперёд. Стоит перебазироваться на самый свежий master.

# Переходим на master
git checkout master
 
# Убеждаемся, что мы на последней версии
git pull origin master --fast-forward
 
# Возвращаемся в свою ветку
git checkout -
 
# Перебазируемся, т.е. делаем так будто мы отбранчевались секунду назад
git rebase master

Не всегда получается сразу выстроить идеальный лог изменений. Сейчас лучший момент для того, чтобы исправить сообщения, склеить несколько коммитов в один или изменить их порядок:

# Открываем интерактивный редактор для уточнения коммитов этой ветки
git rebase --autostash --interactive master

После использования git rebase нельзя просто пушнуть изменения. Git выдаст ошибку о том, что вы пытаетесь переписать историю в облаке, что может доставить неприятности коллегам. По конвенции автор ветки — царь и бог этой ветки, поэтому может и должен пушнуть её силком:

git push origin --force

Итак, изменения готовы, можно открывать PR. Это делается через веб-интерфейс GitHub, на странице репозитория. Жмите «Create Pull Request», но не сохраняйте тут же. Сначала убедитесь, что заголовок корректен. Он должен быть написан на человеческом языке, т.к. предназначен для ваших коллег. Представьте, что он как есть пойдёт в changelog или отчёт о том, что команда сделала за квартал: вот такого уровня понятность должна быть.

Далее, заполните тело PR. Если это PR с потолка, кратко объясните зачем он создан, что и как решает, на что стоит отдельно обратить внимание. Если PR — это изменения для закрытия issue, достаточно просто написать:

Closes #42

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

Выберите одного-двух коллег и в рамках интерфейса GitHub PR позовите их на ревью. Дождитесь обратной связи в рамках интерфейса GitHub.

Если коллеги требуют изменений (request changes), обсудите при необходимости и далее вносите фиксы отдельными коммитами. Фиксите, коммитьте, пушайте, фиксите, коммитьте, пушайте. Когда работа над конкретным замечанием выполнена, нажимайте кнопку Resolve, чтобы замечание свернулось.

Как только вы исправили все замечания, используйте кнопку «обновить» рядом с аватаркой ревьювера, чтобы позвать его вновь на ревью исправлений.

Повторяем до победного.

Итогом работы с ревьюверами должен быть таким:

• Все замечания зарезолвлены
• От всех ревьюверов получены аппрувы

Финальный аккорд: ещё раз причесать лог изменений, чтобы склеить/улучшить коммиты сделанные в рамках ревью:

# Открываем интерактивный редактор для уточнения коммитов этой ветки
git rebase --autostash --interactive master
 
# Насильно пушаем
git push origin --force

После всех процедур, кнопка Merge становится зелёной. Предпочтительная стратегия вмёрживания — Merge. Для текстового контента допускается использовать Squash & Merge.

В любом случае, после нажатия на мёрж, удаляем топик-ветку (Delete merged branch), чтобы она не засоряла репозиторий.

Всё готово, можно выдохнуть.