PRolice

        ooooooooo.   ooooooooo.             oooo   o8o
        `888   `Y88. `888   `Y88.           `888   `"'
         888   .d88'  888   .d88'  .ooooo.   888  oooo   .ooooo.   .ooooo.
         888ooo88P'   888ooo88P'  d88' `88b  888  `888  d88' `"Y8 d88' `88b
         888          888`88b.    888   888  888   888  888       888ooo888
         888          888  `88b.  888   888  888   888  888   .o8 888    .o
        o888o        o888o  o888o `Y8bod8P' o888o o888o `Y8bod8P' `Y8bod8P'
        ------------ What you gonna do when they come for you -------------

---

Введение

Prolice (сокращение PR-полиции ) является инструментом управления инженерным управлением для отказа и измерения данных запроса на вытягивание из репозитории GitHub.

Для чего это?

Выкрикивая Sourcelevel и их отличный пост в блоге о метрик (большинство из которых реализованы этим приложением):

Многие инженерные менеджеры продвигают запросы на привлечение в рамках рабочего процесса разработки. Это консолидированная практика, которая приносит много преимуществ. Он состоит в сравнении изменений ветви с базовой ветвью хранилища (обычно называемого мастером).

Запросы на вытягивание предоставляют полезные и действенные показатели. Тем не менее, следуя неправильным показателям вызывают искажения и приносят больше недостатков, чем льготы. Менеджеры могут использовать показатели запросов на привлечение, чтобы понять динамику команды и действовать соответствующим образом для правильного поведения, прежде чем все выйдет из пути.

Prolice стремится собрать образец запросов на притяжение из целевого репозитория и проанализировать их, с целью представить представление о рабочем процессе коллективного проекта с течением времени.

Предупреждение

Снова выкрикивая в блог -пост Sourcelevel (серьезно, прочитайте его, если вы еще этого не сделали):

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

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

Я также стал свидетелем того, как инженерные менеджеры поощряли разработчиков открывать запросы на привлечение с слишком большим количеством изменений, которые непрактично в обзоре. Обычно они усиливают это, рассказывая всем, что эти разработчики продуктивны, что они делают тяжелую работу, когда другие берут самые простые.

Измерение людей с помощью запросов на притяжение может быть даже несправедливым. Разработчик, посвященный поддержанию устаревшей кодовой базы, имеет тенденцию быть медленнее, чем другой, который работает над проектом Greenfield.

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

Попасть в действие

Предварительные условия

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

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

Основное использование

С вашим личным токеном доступа доступно и загрузите бинарник из раздела релизов, вызовете пролис внутри вашего любимого терминала - в настоящее время Linux и MacOS (Darwin) поддерживаются:

prolice --owner < owner > --repository < repository > --github-token < github-token >

Например, если мы хотим измерить официальные показатели хранилища Rust ( примечание : это по умолчанию образец из 100 PRS):

prolice --owner rust-lang --repository rust --github-token < github-token >

Индивидуальные показатели PR также поддерживаются:

prolice --owner rust-lang --repository rust --pr-number 32000 --github-token < github-token > 

Расширенное использование

PLICE 's имеет несколько флагов и дополнительных параметров, которые можно использовать для регулировки его сложности и размера образца:

prolice --help

USAGE:
    prolice [FLAGS] [OPTIONS] --owner < owner > --repository < repository > --sample-size < sample-size > --github-token < github-token >

FLAGS:
    -h, --help                 Prints help information
    -m, --include-merge-prs    Marks merge-PRs as valid targets for analysis (by default these are
                               excluded). Valid only for whole Repository analysis ; for individual
                               PR analysis this flag is ignored
    -l, --print-legends        Prints the metrics ' legends before sending the operation results to
                               stdout.
    -s, --silent-mode          Marks the operation as silent, which turns off all logging and
                               printing to stdout, with the sole exception of the analysis results.
                               This makes it useful for piping just the results, without the added
                               ' noise ' . (NOTE: piping is automatically detected, which activates
                               silent-mode without having to explicitly add the flag to the command)
    -V, --version              Prints version information

OPTIONS:
    -G, --github-token <github-token>
            Sets the personal access token under which to perform the PR analysis

    -L, --log-level <log-level>
            Overrides the logging verbosity for the whole application [default: INFO] [possible
            values: INFO, DEBUG, TRACE, WARN, ERROR, OFF]

    -O, --owner <owner>                  The owner of the repository under scrutiny
    -P, --pr-number <pr-number>
            A specific pull-request to be selected as target for the analysis.

    -R, --repository <repository>        The repository under scrutiny
    -S, --sample-size <sample-size>
            The amount of PRs that will be fetched as sample for the analysis (unless a specific PR
            number is selected as individual target) [default: 100]

Примечания об продвижении использования

Результаты PLOLICE могут быть переданы в файл. Приложение (или любое отсутствие TTY) автоматически обнаруживается приложением, которое отключает все журналы и сообщения, даже если пользователь не предоставит эти флаги как часть команды. Это полезно для получения необработанных результатов, которые могут быть поданы в другой процесс.

Например:

prolice --owner rust-lang --repository rust --github-token < github-token > >> results.json

Получит файл results.json со следующим содержимым (на момент написания этой README):

{
  "score" : [
    {
      "AmountOfParticipants" : 4
    },
    {
      "AmountOfReviewers" : 1
    },
    {
      "Attachments" : 1
    },
    {
      "AuthorCommentaryToChangesRatio" : 31.138690476190472
    },
    {
      "PullRequestsDiscussionSize" : 4065
    },
    {
      "PullRequestFlowRatio" : 1.9121686296350902
    },
    {
      "PullRequestLeadTime" : 1
    },
    {
      "PullRequestSize" : 255
    },
    {
      "TestToCodeRatio" : 0.42988095238095236
    },
    {
      "TimeToMerge" : 4
    }
  ]
}

Поддерживаемые метрики

То, что каждый показатель «означает» (так же, почему он полезен для измерения), может быть напечатано как часть анализа «результаты», передавая флаг --print-legends . Тем не менее, это может загрязнять терминал чрезмерной условности; Итак, для справки, это значение каждого показателя:

AmountOfParticipants

Количество неавторизованных людей, участвующих в дискуссии PR. Большое участие может обогатить обсуждение и создать более качественный код.

AmountOfReviewers

Количество неавторизованных людей, которые выступили с результатом PR, либо одобрив, либо запрашивая изменения. Это измеряет количество участников, которые эффективно определяют судьбу PR.

Attachments

Вложения могут быть чем угодно, от добавленных скриншотов до встроенных файлов PDF. Особенно полезно для тех PR, которые имеют визуальный компонент, связанный с ним.

AuthorCommentaryToChangesRatio

Хороший код должен быть самостоятельным; Но хороший пиар также может включать в себя дополнительный комментарий о том, чего он стремится достичь, как он это делает, и/или почему он делает это выбранным способом.

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

PullRequestsDiscussionSize

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

Дискуссии, которые становятся слишком большими, могут указывать на что -то не так: возможно, команда не выровнена, или, возможно, требования к программному обеспечению недостаточно точны. В любом случае, смещение в дискуссиях не является сотрудничеством; Они пустая трата времени. В противоположном сценарии почти нулевое взаимодействие означает, что обзор кода не является частью привычек команды.

Таким образом, этот показатель должен достичь «идеального числа» на основе размера и распространения команды. Это не может быть слишком много, и это тоже не может быть слишком мало.

PullRequestFlowRatio

Коэффициент потока запроса на вытягивание - это сумма открытых запросов на вытяжение в день, разделенную на сумму закрытых запросов на притяжение в тот же день. Этот показатель показывает, работает ли команда в здоровой пропорции. Объединение запросов на тягу и развертывание на производство - это хорошо, поскольку он добавляет ценность конечному пользователю. Тем не менее, когда команда закрывает больше запросов на притяжение, чем открывается, вскоре умирает очередь запроса на тягу, что означает, что в доставке может быть перерыв. В идеале лучше всего убедиться, что команда объединяет запросы на то, что они близки, как они открываются; Чем ближе к 1: 1, тем лучше.

PullRequestLeadTime

Метрика времени выполнения дает представление о том, сколько раз (обычно в дни) запросы на то, чтобы быть объединены или закрыты. Чтобы найти этот номер, необходима дата и время для каждого запроса на привлечение при открытии, а затем объединены. Формула проста: простое среднее значение для разницы дат. Расчет этой метрики во всех репозиториях в организации может дать команде более четкое представление об их динамике.

PullRequestSize

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

TestToCodeRatio

Как правило, по крайней мере, половина пиара должна содержаться из тестов, когда это возможно.

TimeToMerge

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

Время слияния обычно полезно при сравнении с временем выполнения запроса на вытяжение. Возьмите следующий пример:

• Время выполнения запроса на вытягивание = 3 дня
• Время слияния = 15 дней

В приведенном выше сценарии запрос на тягу занял среднее время 3 дня, чтобы быть объединенным (что довольно хорошо); Но время слияния составило 15 дней. Это означает, что разработчики работали в среднем 12 дней (15 - 3), прежде чем открыть запрос на тягу.

Примечание. Этот показатель сделан несколько устаревшим, если разработчики работают над ветвями WIP, прежде чем раздавить все изменения в единый коммит, который впоследствии используется в качестве базы для PR (это заставит время, чтобы слияние эффективно равным временю выполнения запроса на вытяжение). Тем не менее, метрика по-прежнему остается невероятно полезной для PRS Merge (например, Merge Goss Into Master): сказали, что PRS будет иметь очень короткое время для запроса на тягу (они не получат тщательного повторного обзора), но измерение против даты первого коммита (время для объединения) скажет, сколько времени потребуется, чтобы функции были накапливаются в вежан, достойный слияния в одну из больших филиалов.

---

Компиляция PLOLICE с использованием cargo

Пролис написан в ржавчине. Сбор приложения для использования в хост-платформе так же просто, как и использование обычного cargo build :

cargo build --release

Пролис перекрестной компилирование с использованием cargo-make (Linux в macOS)

Давайте сначала начнем этот раздел с небольшим предисловием из этого удивительного блога:

Я ненавижу Cross Compling

Существуют миллионы способов разрушить операционную систему, над которой вы работаете, и Cross Compling является одним из них. Обычно он начинается с невинной идеи привлечь эту одну цепочку сборки, которая вам нужна для небольшой программы для работы на Linksys Wrt 1900 ACS (OpenWRT и ARMV7).

Копание вокруг вас найдите несколько различных фрагментов на Reddit или некоторых проблемах в проекте GitHub, где случайный человек опубликовал несколько строк удара, которые выглядят как только не хватающая информация, которая вам нужна.

Запуск удара может затем вызвать одну из следующих вещей:

• Создайте рабочую цепочку сборки (очень маловероятно)
• Создайте цепочку сборки, которая терпит неудачу после 80% вашей сборки
• Добавьте местный майнер биткойнов, притворяясь, что действительно создает рабочую цепочку сборки

Почувствовав эти боли на личном уровне, кросс-компиляция была доступна на относительно безболезненного уровня целями, определенными внутри грузоподобного cargo-makefile.toml этого проекта. Томл.

Конечно, если составлять только для хост-машины, придерживаться простых старого cargo build -это всегда первый выбор. Но предположить, что цель состояла в том, чтобы компилировать от Linux в MacOS (Darwin) с нуля, в дополнение к обычным инструментам Rust вам необходимо установить cargo-make в качестве этого:

cargo install --force cargo-make

После этого, шаги компиляции полностью позаботятся о вас, вызывая:

cargo make --makefile cargo-makefile.toml release-darwin

Это создаст и поместит после завершения процесса, сжатый бинарник в:

<your_dir>/target/release/out/prolice_x86_64-apple-darwin.zip

Принимайте во внимание , однако, что перекрестная компиляция Linux-to-Darwin требует Docker, поэтому вы снова можете спасти себя в нескольких MBS, придерживаясь строительства двоичных файлов для вашей хост-машины, просто вызывая простую старую cargo build .