Работа с Git-репозиториями
Git и GitHub — очень мощные инструменты для взаимодействия нескольких человек. Они относительно сложные и требуют определённого уровня понимания и дисциплины. Но взамен мы получаем удобную работу и отличный результат.
Как внести изменения в master
Создать ветку
Основная ветка master
всегда защищена от прямых коммитов. Это нужно для того, чтобы все изменения проходили ревью, а автоматизированные скрипты развёртывания не отрабатывали, пока порция изменений не отполирована. Поэтому, чтобы начать что-то менять, создайте собственную ветку:
# Становимся в master git checkout master # Убеждаемся, что мы на последней версии git pull origin master --fast-forward # Отбранчёвываемся git checkout -b feat-42-support-spi
По конвенции имя топик-ветки строится из трёх частей:
- Префикс
feat
,fix
,tweak
,chore
,test
,doc
в зависимости от типа изменений - (опционально) Номер issue, которую закрывает ветка
- Мнемоника о сути изменений
Накоммитить
Когда ветка готова, можно делать изменения и коммитить, делать изменения и коммитить. Из уважения ревьюверов в будущем очень важно делать коммиты гранулярными и с понятными сообщениями. Чтобы ревьювер хорошо понимал, что и зачем сделано, и где нужно уделить особое внимание. Особенно важно выделять в отдельные коммиты результаты массовой механической обработки файлов: массовые переименовывания, автоформатирование кода и т.п.
Пример хорошего лога:
- 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
Итак, изменения готовы, можно открывать 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), чтобы она не засоряла репозиторий.
Всё готово, можно выдохнуть.