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

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

Lead time

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

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

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

Contribution

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

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

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

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

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

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

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, участие в ревью и полученные ревью. С их помощью можно определить бутылочные горлышки, типовые замечания, распределение нагрузки код ревью и качество пулл реквестов/код ревью.

• Настраивается как обычный гитхаб-экшн. Самый выгодный вариант запускать его с определенным интервалом, тогда статистика будет актуальной, а используемое время небольшим.