GitHub Flow и ветки
Привет! На прошлой неделе мы узнали, что такое Гит и отправили свой первый код в удаленный репозиторий. Теперь поговорим о best practices при работе с Гитом и научимся проходить код-ревью.
Как оформлять коммиты
Очень важно правильно оформлять коммиты, чтобы другим разработчикам (и тебе в будущем) было понятно, зачем сделаны изменения. Основные правила хорошо описал Василий Половнёв в своём блоге:
https://vasily.polovnyov.ru/posts/git-commit-messages.html
Существует много подходов к оформлению коммитов, тут важно выбрать какой-то один и придерживаться его. Мне, например, нравится такой:
https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716
Коммиты должны быть на английском, отвечать на вопрос "зачем было сделано изменение?". Напоминаю, что сам коммит должен быть атомарным, то есть одно глобальное изменение в коде → один коммит. Нельзя делать кучу всего, а потом перечислять все изменения через запятую в одном коммите. Потому что потом сложно будет в случае чего откатиться назад. Одно изменение → один коммит.
Файл REAMDE.md
Внутри любого репозитория обязательно должен быть файл REAMDE.md, в нем хранится информация о том, что тут хранится и как это запускать. Файл README.md содержит всю необходимую информацию о проекте (твоем коде), желательно на английском языке. Его удобно редактировать прямо в веб-интерфейсе GitHub'а, можно смотреть результат.
Нажми «карандашик»:
Затем оформи всё по красоте:
Затем нажми «Preview changes», чтобы посмотреть, что получилсь:
Файл не зря имеет расширение md, это означает MarkDown — специальный язык разметки, с помощью которого удобно форматировать и оформлять текст. Для быстрого ознакомления глянь ссылку: https://paulradzkov.com/2014/markdown_cheatsheet/
Для удобства можно использовать готовые шаблоны, например вот эти:
https://github.com/othneildrew/Best-README-Template
https://github.com/dbader/readme-template
Правильно оформленный ридми содержит краткое описание проекта (желательно со скриншотом), инструкцию по установке и запуску с примерами команд.
Пример хорошо оформленного REAMDE: https://github.com/LonamiWebs/Telethon
GitHub Workflow
👆— так называется способ работы с репозиторием, которого обычного придерживаются (или как-то модифицируют под себя) большинство разработчиков. В его основе лежит такой механизм работы с гитом, как ветвление. Ветки (branch) чаще всего создаются во время работы в команде, чтобы не мешать друг другу и работать каждый в своей ветке. А потом, после проверки работоспособности, сливать код в основную ветку.
Принцип здесь такой: основная ветка (master) всегда содержит стабильный, работающий код. Чтобы его не поломать, другие разработчики копируют этот код в безопасную область, которая называется "ветка", добавляют туда какой-то новый код, тщательно проверяют, и, если всё окей, добавляют стабильный код в master. Таким образом, много разработчиков могут работать параллельно над одним и тем же проектом, не мешать друг другу и ничего не поломать. Такой подход называется GitHub Flow, приглашаю к прочтению его официальное описание:
https://guides.github.com/introduction/flow/
А вот и перевод на русский:
https://habr.com/ru/post/346066/
На этой неделе мы будем использовать такой подход, чтобы сдавать домашку на проверку. В будущем у нас будет групповой проект и там раскроются все его прелести.
Как сдавать на проверку (Pull Request)
Создай приватный репозиторий на GitHub. Ты помнишь, что название репозиториев на GitHub'е принято оформлять в kebab-case 🍡. Пример: my-awesome-name
При создании репозитория нажми галочку "Add .gitignore" и выбери Python, это нужно для того, чтобы репозиторий не хранил ненужные временные файлы.
Пригласи проверяющего (меня) как коллаборатора в свой репозиторий: открой вкладку Settings, пройди в Collaborators, введи логин проверяющего и нажми Add collaborator. Как только проверяющий примет приглашение, он появится в списке коллабораторов и сможет проводить код-ревью.
Склонируй созданный репозиторий себе командой git clone адрес-репозитория и перейди в него командой cd имя-репозитория.
Создай новую ветку от мастера командой git checkout -b feat/new-feature , feat — это сокращение от feature (англ. "особенность", "функциональность"), так принято называть ветку, которая добавляет в проект какую-то новую функциональность. new-feature это название той функциональности, которую ты добавляешь в рамках домашней работы. Замени это слово на подходящее по смыслу.
Убедись, что находишься на новой ветке командой git status. Теперь ты делаешь задание. Когда всё будет готово, воспользуйся командой git diff. Она показывает, какие изменения будут зафиксированы. Внеси необходимые изменения, закоммить их, и запушь (то есть отправь на Гитхаб командой git push).
После того, как домашнее задание сделано и запушено в новую ветку, необходимо пройти код-ревью. Для этого зайди в браузере на Гитхаб и открой пулл-реквест: нажми кнопку New pull request и проверь направление стрелочки: она должна указывать из твоей ветки feat/имя-фичи на master:
Pull request (ПР) — это запрос на добавление новой функциональности к основной версии кода. После того, как он будет одобрен, весь код с новой ветки добавится в master, смерджится (англ. merge "сливать", "поглощать").
После открытия Pull request'а поставь своего проверяющего ревьюером. Нажми Reviewers справа и выбери никнейм. Если он появился и рядом загорелась желтая точка — всё сделано правильно. Остается только дождаться проверки. Ты получишь уведомление на почту, когда проверка будет сделана.
После замечаний ты исправляешь работу и заново вешаешь проверяющего ревьюером. Если сразу всё сделано правильно, то проверяющий мерджит ветку в мастер и тебе нужно сделать git pull, чтобы подтянуть изменения в свой локальный репозиторий. Ветку после этого можно удалить. Погугли и сделай это самостоятельно.
Можно идти отдыхать. Ура!
Иногда не получается смерджить изменения из дополнительной ветки в master. Например, когда вы с кем-то другим работали над одним куском кода и изменили его. Гит в таком случае не знает, какое изменение оставить, их же два. Это называется конфликтом слияния (merge conflict). В этом случае надо помочь Гиту и выбрать нужные версии кода, нужно открыть файл с конфликтом, найти этот конфликт (будет между ёлочками), в данном случае это 12345 и 54321, надо оставить что-то одно:
какой-то код
ещё какой-то код
<<<<<<< HEAD
12345
=======
54321
>>>>>>> feature
ещё какой-то код
Оставляем 12345 и удаляем все ненужные символы:
какой-то код
ещё какой-то код
12345
ещё какой-то код
Делаем коммит, готово. Конфликта больше нет.
Дополнительные штуки
Туториал по маркдауну: https://commonmark.org/help/tutorial
Третья глава книги https://git-scm.com/book/ru/v2 (Ветвление в Git)
Практика
Прежде, чем открывать следующий урок, убедись, что понимаешь всё вышепрочитанное хотя бы на уровне концепций. В качестве практики нужно будет выполнить задания из следующего урока и сдать на проверку, используя эти знания.