Ревью кода системы средствами git

Бывает нужно оставить отзыв об исходном коде в репозитории в целом, например при приемке кода на поддержку от других разработчиков или подключаясь к новому проекту.
Процессы ревью в Github и аналогах построены вокруг вносимых изменений, а в нашем случае комментарии нужно дать к состоянию всего кода системы на момент комментирования.

Как это сделать средствами самого git: зафиксировать состояние в ветке для ревью, затем в merge request к этой ветке оставить свои замечания.

В общем суть метода уже изложена, ниже лишь немного подробностей.

Проблематика

Представьте ситуацию: вам передают репозиторий с кодом и просят вынести свое мнение о нем. Обычно в подобных случаях замечания составляются в отдельном документе/таске/страничке в конфлюенс и т.п., что не очень удобно так как:

1. Замечания могут устареть уже в процессе написания, так как разработка может продолжаться.
2. Сложно ссылаться на одельные участки кода, референсы вроде doubtful/bar.js:4 просто неудобны для постоянного переключения между документом и кодом.
3. В отрыве от кода документ затеряется с довольно высокой вероятностью.

Метод ревью кода системы

Итак, нам нужно проделать следующее: зафиксировать состояние в ветке для ревью, затем в merge request к этой ветке оставить свои замечания.
На примере подготовленного для заметки репозитория https://github.com/oktend/system-review-example ^[1] проделаем эти шаги:

1. Найдем состояние в репозитории для ревью (на момент ревью это был последний коммит в dev):
   https://github.com/oktend/system-review-example/commit/0514531a35edf19e7032eb49f45a98d019f83efe ^[2]
2. Ветвим от выбранного состояния ветку для нашего системного ревью, например "system-review/1march2020-goodman":
   https://github.com/oktend/system-review-example/tree/system-review/1march2020-goodman ^[3]
3. Создаем от вновь созданной ветки еще одну ветку, в которой будем собирать замечания, например "1march2020-goodman-issues":
   https://github.com/oktend/system-review-example/tree/system-review/1march2020-goodman-issues ^[4]
4. Вносим в эту ветку удобным нам способом наши замечания, как прямо в код, так и в отдельные документы.
5. Создаем merge request (может называться pull request) к ветке для ревью "system-review/1march2020-goodman-issues" -> "system-review/1march2020-goodman":
   https://github.com/oktend/system-review-example/pull/1/files ^[5]

Теперь наши ветки выглядят примерно так:

https://github.com/oktend/system-review-example/network ^[6]

Результат

В созданном merge request можно увидеть все собранные в ходе ревью замечания, даже обсудить их.
Состояние, для которого были выдвинуты замечания будет зафиксировано пока ветку явно не удалят.
Замечания можно делать как в отрыве от кода:
https://github.com/oktend/system-review-example/blob/c80b03710059b235347ec781bf08dca9c0e68f7d/review-1march2020-goodman.md ^[7]
так и в контексте кода:
https://github.com/oktend/system-review-example/blob/c80b03710059b235347ec781bf08dca9c0e68f7d/foo.js ^[8]
Замечания можно просматривать в веб-интерфейсе github (или аналогов), в IDE, или средствами самого git.
К ревью можно будет вернуться в будущем сохранив замечания и контекст, в котором они были выдвинуты.

Примечания

Вполне допускаю возможность, что переизобрел велосипед и что для подобных случаев есть лучший метод, тогда буду благодарен за указание на лучший путь.
Идею для этого метода придумал не я, а предложил один разработчик, если Артем изъявит желание, укажу как автора.

Автор: Алексей

Источник ^[9]