CONTRIBUTING.md

Для чего мы делаем код-ревью?

1. Для распространения инженерной культуры, стандартов и практик;
2. Для повышения качества написанного кода;
3. Для повышения осведомлённости членов команды об изменениях в проекте;
4. Для облегчения адаптации новых членов проекта.

Кто может делать код-ревью?

• Код-ревью это не "top-down", а "peer-to-peer" процесс, то есть каждый делает ревью кода каждому;
• Можно делать код-ревью в любом проекте, к которому есть доступ. Это помогает распространению культуры между проектами, а не только внутри замкнутой группы.

Ключевые идеи для автора

• Для код-ревью мы используем пулл-реквесты на гитхабе;
• Пулл-реквест должен быть минимально возможного размера. Автор должен облегчить другим членам команды ревью своего пулл-реквеста и описать что сделано и почему, предоставить максимум контекста. 1 PR = одно атомарное изменение;
• Пулл-реквест != задача. Одна задача может содержать несколько пулл-реквестов;
• К пулл-реквесту желательно добавить скриншот или гиф с результатом работы;
• Один пулл-реквест перед мёржем должен включать в себя одно логическое изменение. Например рефакторинг кода и реализация новой задачи должны быть разделены на 2 пулл-реквеста;
• При этом желательно как можно раньше открывать пулл-реквест с припиской [WIP] (work in progress), чтобы остальные члены команды могли как можно раньше начать следить за ходом работы;
• В случае WIP PR желательно добавить чеклист, чтобы члены команды могли видеть, что уже готово, а что нет;
• Код-ревью – асинхронный процесс и не стоит ожидать моментальной реакции. Будьте готовы одновременно работать над несколькими пулл-реквестами;
• На все комментарии в пулл-реквесте, содержащие вопрос/предложение, должны быть ответы;
• Мержит сам автор, но только после получения нужного количества апрувов;
• Пулл-реквест без апрувов не может быть вмёржен;
• Пулл-реквест с хотя бы одним статусом "request changes" не может быть вмёржен. Даже если вы не собираетесь исправлять предложение — ревьюер должен изменить статус и показать, что вы обсудили решение. Вы можете обратиться к третьему члену команды для "рассуждения" спора, но только в исключительных ситуациях;
• Пулл-реквест с упавшим статусом CI не может быть вмёржен;
• Будьте готовы поработать над пулл-реквестом: изменять, дополнять, закрывать за ненадобностью или из-за неверного решения, делить меньшие части;
• Исправления/дополнения существующего пулл-реквеста должны быть отправлены отдельным коммитом, без использования git commit --amend или git rebase -i. Так любой ревьюер может просмотреть только новые изменения, а не весь пулл-реквест;
• Перед мёржем пулл-реквеста стоит почистить историю, сделать рибейз над веткой master (git fetch origin && git rebase origin/master);
• Если пулл-реквест закрывается — всегда должна быть указана причина в комментарии (например, переоткрыто в другом/других PR, за ненадобностью и т.д.).

Ключевые идеи для ревьюера

• Ревью кода — ответственный процесс;
• Уважайте работу и время других членов команды;
• В идеале, код ревью это постоянный асинхронный процесс, которым нужно заниматься от 1 до десятков раз в день;
• Каждый комментарий должен иметь ясный позыв (исправление/предложение/блокер), а не выражение личного мнения;
• Если не понимаете кусок кода — не стесняйтесь задать вопрос прямо в пулл-реквесте;
• Не стесняйтесь задавать вопросы о работе кода, в том числе более опытным коллегам;
• Если вас попросили о ревью (assignee на гитхабе) – отдайте приоритет этому пулл-реквесту и будьте в 2 раза внимательнее обычного просмотра. В таком случае завершайте ревью только со статусом approved или request changes.
• В случае когда вы не уверены в апруве/реджекте – опишите это в комментарии и постарайтесь найти человека, способного принять решение;
• Не отправляйте approve для пулл-реквеста, пока вы не
  • понимаете, что он делает
  • понимаете, как он это делает
  • согласны с решением
• Если в ходе код-ревью у вас появились комментарии, требующие изменения или обсуждения с автором — завершайте ревью со статусом "request changes";
• Если вы заканчиваете ревью со статусом comment, это означает что вы не против мёржа пулл-реквеста в текущем виде;

Рекомендации

• Прочитайте описание пулл-реквеста до ревью. Постарайтесь понять бизнес задачу и контекст.
• Подумайте, какие изменения вы бы внесли? Посмотрите код — изменения совпадают? Если не совпадают — подумайте, почему. Какие-то изменения лишние или вы что-то не учли? Сделайте выводы, обсудите с автором.
• При любой возможности делите пулл-реквесты на более мелкие. В том числе при ревью — не стесняйтесь просить автора разбить PR на несколько, если это возможно.
• Будьте в меру придирчивы. Помните, что работающий код важнее, чем идеальный код.
• Ищите места для автоматизации. Если вы 3 раза пишите комментарий с одними изменениями — это повод для автоматизации проверки.