Code Review — простой способ измерения и анализа04.06.2024 08:45

Рассмотрим такую спорную, но при этом полезную вещь как измерение метрик код ревью. Не секрет, что это один из неотъемлемых этапов в процессе разработки и возникающие проблемы могут в конечном итоге сказаться на расходах компании и удовлетворении от работы в команде. Чтобы этого не было, необходимо вовремя понимать есть ли проблемы, определять причины, находить решения и проверять их эффективность. В части этих вопросов нам и может помочь статистика. Можно найти как отдельные приложения сфокусированные на метриках, так и гитхаб-экшны. В данной статье речь пойдет о гитхаб-экшне Pull request analytics action.

Важное уточнение: метрики призваны помочь человеку в анализе ситуации. Преимуществами являются отсутствие личного фактора и необходимости вручную тратить много времени на анализ, а также способность работать с большим количеством данных ретроспективно на любом временном промежутке и отобразить это визуально. В то же время есть недостатки: далеко не всё можно перевести в метрики, более того в некоторых случаях метриками можно манипулировать. Поэтому никакая статистика не может заменить традиционные фидбэк-сессии, ретро и прочие процедуры, но при этом дополняет и упрощает их. Таким образом, с помощью комбинации двух методов можно получить наиболее полную картину.

Lead time

Первое, что можно замерить — это lead time. Любая команда заинтересована, чтобы пулл реквесты проходили ревью без задержек. Но если эти заминки есть, то необходимо понять на каком этапе и почему они происходят. Сейчас учет ведется от открытия ПРа до следующих стадий: запрос ревью, проведенное ревью, аппрув, влитие. Отдельно считается сумма пребывания ПР-а в виде черновика. Можно вывести среднее арифметическое значение, выбранный персентиль или медиану. Также есть опция установить собственные пороги и увидеть разбивку по ним для этих стадий.

Пример таблицы Lead time

Пример: в команде могут быть собственные требования за сколько ПР должен быть проверен. Допустим хорошим результатом для вас являются 6 часов, приемлемым 24 часа, а все что выше нежелательным. В таком случае необходимо перечислить эти пороговые значения и вы всегда будете видеть какая сейчас ситуация. Немного с другой стороны можно увидеть ситуацию, если выставить персентиль. Например, вы хотите видеть за сколько проходит ревью 90% ПРов. Устанавливаете персентиль в параметрах и вы увидите результаты команды.

Пример среза времени ревью

Только с помощью этих таблиц сделать выводы о причинах не получится. Необходимо интерпретация человека. Здесь на помощь могут прийти отсортированные списки самых зависших на стадиях ПР-ов. Перейдя по ссылкам можно будет проанализировать что это были за ПР-ы и почему они висели так долго.

Contribution

Здесь можно увидеть наиболее общие данные. Они могут частично помочь с ответами на вопросы из lead time. Ключевые параметры, которые достойны внимания — размер пулл реквестов, количество комментариев и проведенных ревью. Как правило большие ПР-ы неохотно берут на проверку, потому что труднее держать фокус и в целом потребуется больше времени. Также это может повлечь большее количество замечаний в разных областях, что застопорит весь ПР. Большое количество замечаний может быть одной из причин большого промежутка между проведенным ревью и аппрувом. Количество проведенных ревью призвано показать распределение нагрузки по проверке внутри команды.

Пример таблицы contribution

Анализ дискуссий

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

Поэтому первое, что можно посмотреть — это как много открывается дискуссий и запрашивается изменений. Если их количество слишком большое, вероятно увеличится и время от открытия до аппрува. Также можно обратить внимание на количество комментариев. Если их количество сильно отличается от количества открытых дискуссий, то вероятно в дискуссиях возникает недопонимание. Наиболее комментируемые ПРы можно вывести в отсортированным списке и проанализировать их самостоятельно.

Пример таблицы для анализа ПР-ов

Пример списка в котором указано название ПР-а и в скобках количество комментариев

Насколько верно были оставлены комментарии также можно замерить. Для этого надо в открытой дискуссии ставить реакцию лайк/дизлайк. Даже если мнения разделились — это может быть показателем, что есть разное понимание решений. Что с этим делать уже зависит от команды.

Последнее, что можно вывести — это причины дискуссий. Для этого требуется сформировать список возможных и добавлять [[название лейбла]] в открывающий дискуссию комментарий. Таким образом можно будет определить наиболее повторяющиеся проблемы. Исходя из проблем будет проще найти решение.

Reviewers

Рассмотреть процесс можно не только со стороны человека открывающего ПР, но и со стороны человека, который его проводит ревью. Здесь также можно посмотреть количество запрошенных изменений, открытых дискуссий и оставленных комментариев. Если оставлять реакции лайк/дизлайк в открывающем дискуссию комментарии, то можно увидеть насколько верно/неверно она была открыта. Также есть разбивка насколько большие ПР-ы ревьюит человек. В конечном итоге данная информация должна помочь увидеть распределение нагрузки по ревью в команде, а также насколько часто и верно открываются дискуссии.

Пример таблицы участия в ревью

Другие вспомогательные возможности

Коротко перечислю наиболее полезные возможности:

Многие не хотят видеть разбивку по каждому разработчику, им важна только статистика по команде. Используйте total в параметре SHOW_USERS для этого. Если хочется исключить конкретных людей, например уволенных, из отображения, укажите их в HIDE_USERS.
Можно фильтровать ПРы по лейблам с помощью параметров EXCLUDE_LABELS и INCLUDE_LABELS
Для более точных результатов проставьте переменную с праздниками и рабочими часами в параметры CORE_HOURS_START, CORE_HOURS_END и HOLIDAYS.
Чтобы сохранять отчет в одном issue используйте execution outcome равный existing-issue. Если обновление отчета будет регулярным, то лучше проставить ISSUE_TITLE, чтобы не было длинной цепочки изменений заголовка.

Как все это настроить

Настраивается как обычный гитхаб-экшн. В качестве триггера можно выбрать что угодно, но наиболее оптимальным на мой взгляд является вариант schedule. Он позволит вам с одной стороны всегда поддерживать отчет актуальным, а с другой не будет съедать много ресурсов. Другим удобным вариантом является ручной запуск, в случае если отчет постоянно не нужен и требуется разная настройка.

Обязательно надо установить токен. В зависимости от условий можно использовать как автоматически сгенерированный GITHUB_TOKEN, так и токен организации. Первый наиболее удобный если нужна статистика по одному репозиторию, а объем не превышает 5000 запросов. Второй разрешает собирать данные со всех репозиториев организации, а лимит 15000 запросов.

Выберите репозитории по которым хотите собирать статистику. Установите за какой период вам нужна статистика (или за какое количество ПРов).

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

name: "PR Analytics"
on:
  schedule:
    - cron: "0 23 * * 1,2,3,4,5"
jobs:
  create-report:
    name: "Create report"
    runs-on: ubuntu-latest
    steps:
      - name: "Runs script for analytics"
        uses: AlexSim93/pull-request-analytics-action@v2
        with:
          GITHUB_TOKEN: ${{ secrets.SET_YOUR_TOKEN }}
          LABELS: "Report"
          GITHUB_OWNER_FOR_ISSUE: "set-your-owner"
          GITHUB_REPO_FOR_ISSUE: "set-your-repo"
          GITHUB_OWNERS_REPOS: "set-your-owner/set-your-repo"
          CORE_HOURS_START: "9:00"
          CORE_HOURS_END: "19:00"
          TIMEZONE: "Europe/Moscow"
          ISSUE_TITLE: "Report"
          REPORT_DATE_START: '01/01/2024'
          TOP_LIST_AMOUNT: 5
          EXECUTION_OUTCOME: new-issue

Полное описание параметров можно увидеть в соответствующей таблице

Заключение

Коротко пробежимся по основным пунктам:

Pull request analytics action — это инструмент, который отображает статистику. Она может показать процесс под другим углом, подсветить проблемные места или показать, что их нет, но интерпретация при этом остается за человеком.
Основные метрики, которые можно увидеть — это lead-time, contribution, участие в ревью и полученные ревью. С их помощью можно определить бутылочные горлышки, типовые замечания, распределение нагрузки код ревью и качество пулл реквестов/код ревью.
Настраивается как обычный гитхаб-экшн. Самый выгодный вариант запускать его с определенным интервалом, тогда статистика будет актуальной, а используемое время небольшим.