Бывает нужно оставить отзыв об исходном коде в репозитории в целом, например при приемке кода на поддержку от других разработчиков или подключаясь к новому проекту.
Процессы ревью в Github и аналогах построены вокруг вносимых изменений, а в нашем случае комментарии нужно дать к состоянию всего кода системы на момент комментирования.
Как это сделать средствами самого git: зафиксировать состояние в ветке для ревью, затем в merge request к этой ветке оставить свои замечания.
В общем суть метода уже изложена, ниже лишь немного подробностей.
Проблематика
Представьте ситуацию: вам передают репозиторий с кодом и просят вынести свое мнение о нем. Обычно в подобных случаях замечания составляются в отдельном документе/таске/страничке в конфлюенс и т.п., что не очень удобно так как:
- Замечания могут устареть уже в процессе написания, так как разработка может продолжаться.
- Сложно ссылаться на отдельные участки кода, референсы вроде doubtful/bar.js:4 просто неудобны для постоянного переключения между документом и кодом.
- В отрыве от кода документ затеряется с довольно высокой вероятностью.
Метод ревью кода системы
Итак, нам нужно проделать следующее: зафиксировать состояние в ветке для ревью, затем в merge request к этой ветке оставить свои замечания.
На примере подготовленного для заметки репозитория https://github.com/oktend/system-review-example проделаем эти шаги:
- Найдем состояние в репозитории для ревью (на момент ревью это был последний коммит в dev):
https://github.com/oktend/system-review-example/commit/0514531a35edf19e7032eb49f45a98d019f83efe - Ветвим от выбранного состояния ветку для нашего системного ревью, например "system-review/1march2020-goodman":
https://github.com/oktend/system-review-example/tree/system-review/1march2020-goodman - Создаем от вновь созданной ветки еще одну ветку, в которой будем собирать замечания, например "1march2020-goodman-issues":
https://github.com/oktend/system-review-example/tree/system-review/1march2020-goodman-issues - Вносим в эту ветку удобным нам способом наши замечания, как прямо в код, так и в отдельные документы.
- Создаем merge request (может называться pull request) к ветке для ревью "system-review/1march2020-goodman-issues" -> "system-review/1march2020-goodman":
https://github.com/oktend/system-review-example/pull/1/files
Теперь наши ветки выглядят примерно так:
https://github.com/oktend/system-review-example/network
Результат
В созданном merge request можно увидеть все собранные в ходе ревью замечания, даже обсудить их.
Состояние, для которого были выдвинуты замечания будет зафиксировано пока ветку явно не удалят.
Замечания можно делать как в отрыве от кода:
https://github.com/oktend/system-review-example/blob/c80b03710059b235347ec781bf08dca9c0e68f7d/review-1march2020-goodman.md
так и в контексте кода:
https://github.com/oktend/system-review-example/blob/c80b03710059b235347ec781bf08dca9c0e68f7d/foo.js
Замечания можно просматривать в веб-интерфейсе github (или аналогов), в IDE, или средствами самого git.
К ревью можно будет вернуться в будущем сохранив замечания и контекст, в котором они были выдвинуты.
Примечания
Вполне допускаю возможность, что переизобрел велосипед и что для подобных случаев есть лучший метод, тогда буду благодарен за указание на лучший путь.
Идею для этого метода придумал не я, а предложил один разработчик, если Артем изъявит желание, укажу как автора.
