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 -------------

---

Perkenalan

Prolice (Kontraksi PRIPI PR ) adalah alat manajemen rekayasa untuk menghapus dan mengukur data permintaan tarik dari repositori GitHub.

Untuk apa ini?

Berteriak ke Sourcelevel dan posting blog mereka yang luar biasa tentang metrik (sebagian besar yang diimplementasikan oleh aplikasi ini):

Banyak manajer teknik mempromosikan permintaan tarik sebagai bagian dari alur kerja pengembangan. Ini adalah praktik konsolidasi yang membawa banyak manfaat. Ini terdiri dari membandingkan perubahan cabang dengan cabang dasar repositori (secara konvensional disebut master).

Permintaan tarik menyediakan metrik yang bermanfaat dan dapat ditindaklanjuti. Namun, mengikuti metrik yang salah menyebabkan distorsi dan membawa lebih banyak kelemahan daripada manfaat. Manajer dapat menggunakan metrik permintaan tarik untuk memahami dinamika tim dan bertindak dengan tepat untuk memperbaiki perilaku sebelum semuanya keluar dari jalur.

Prolice bertujuan untuk mengumpulkan sampel permintaan tarik dari repositori target dan menganalisisnya, dengan tujuan membawa wawasan ke dalam alur kerja proyek kolektif dari waktu ke waktu.

Peringatan di depan

Sekali lagi berteriak ke posting blog Sourcelevel (serius, baca jika Anda belum):

Sebelum masuk ke metrik, saya ingin membuat penafian: jangan gunakan angka -angka ini untuk membandingkan individu .

Terkadang bug yang sulit ditemukan membutuhkan satu baris kode untuk diperbaiki, dan satu baris itu membutuhkan waktu seminggu. Saya telah menyaksikannya berkali -kali dalam karier saya.

Saya juga menyaksikan manajer teknik yang mendorong pengembang untuk membuka permintaan tarik dengan terlalu banyak perubahan yang tidak praktis untuk ditinjau. Mereka biasanya memperkuat bahwa dengan memberi tahu semua orang pengembang ini produktif, bahwa mereka melakukan pekerjaan keras ketika orang lain mengambil yang termudah.

Mengukur individu melalui permintaan tarik bahkan mungkin tidak adil. Seorang pengembang yang didedikasikan untuk mempertahankan basis kode warisan cenderung lebih lambat dari yang lain, yang bekerja pada proyek greenfield.

Itu sebabnya mengukur permintaan tarikan itu rumit. Manajer teknik tidak dapat menggunakan data permintaan tarik untuk menilai individu. Jika Anda melakukan permintaan tarik, maka Anda ingin tim Anda berkolaborasi. Dalam praktik ini, kolaborasi adalah nilai inti. Upaya pengembang tidak dapat diukur hanya dengan berapa banyak permintaan tarik yang terbuka atau digabungkan. Bahkan yang terburuk, upaya tidak mewakili ukurannya.

Masuk ke Aksi

Prasyarat

Hal pertama yang pertama, Anda harus membuat token akses pribadi. Ini adalah persyaratan satu kali dan tidak perlu lebih dari beberapa menit.

Token perlu membaca akses ke repositori dan menarik permintaan agar Prolice bekerja. Sesuatu seperti ini:

Penggunaan dasar

Dengan token akses pribadi Anda yang tersedia, dan setelah mengunduh biner dari bagian rilis, memohon prolice di dalam terminal pilihan favorit Anda - saat ini Linux dan MacOS (Darwin) didukung:

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

Misalnya, jika kami ingin mengukur metrik repositori resmi Rust ( Catatan : Default ini ke sampel 100 PR):

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

Metrik PR individu juga didukung:

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

Penggunaan lanjutan

Prolice memiliki beberapa bendera dan parameter opsional yang dapat digunakan untuk menyesuaikan verbositas dan ukuran sampelnya:

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]

Catatan tentang penggunaan lanjutan

Hasil Prolice dapat disalurkan ke file. Piping (atau tidak adanya TTY) secara otomatis terdeteksi oleh aplikasi, yang akan mematikan semua log dan pesan, bahkan jika pengguna tidak menyediakan bendera ini sebagai bagian dari perintah. Ini berguna untuk mendapatkan hasil mentah yang dapat dimasukkan ke dalam proses lain.

Misalnya:

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

akan menghasilkan file results.json dengan konten berikut (pada saat penulisan readme ini):

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

Metrik yang didukung

Apa artinya setiap metrik "" (alias mengapa sangat berharga untuk diukur) dapat dicetak sebagai bagian dari hasil analisis dengan melewati bendera --print-legends . Namun, itu dapat mencemari terminal dengan verbositas yang berlebihan; Jadi untuk referensi, ini adalah makna masing -masing metrik:

AmountOfParticipants

Jumlah orang yang tidak authoring yang berpartisipasi dalam diskusi PR. Partisipasi yang lebih besar dapat memperkaya diskusi dan menghasilkan kode kualitas yang lebih tinggi.

AmountOfReviewers

Jumlah orang yang tidak authoring yang telah mengambil sikap pada hasil PR, baik dengan menyetujui atau meminta perubahan. Ini mengukur jumlah peserta yang secara efektif memutuskan nasib PR.

Attachments

Lampiran dapat berupa apa saja mulai dari tangkapan layar tambahan hingga file PDF tertanam. Sangat berguna untuk PRS yang memiliki komponen visual yang terkait dengannya.

AuthorCommentaryToChangesRatio

Kode yang baik harus jelas; Tetapi PR yang baik juga dapat memasukkan komentar tambahan tentang apa yang ingin dicapai, bagaimana hal itu dilakukan dan/atau mengapa ia melakukannya dengan cara yang dipilih.

Komentar ramping dapat membuat PR yang ambigu, menggeser beban pemahaman ke pengulas dan mengkonsumsi waktu ekstra darinya. Di sisi lain, terlalu banyak komentar dapat mencemari PR dengan suara yang tidak dibutuhkan, untuk efek yang sama.

PullRequestsDiscussionSize

Mirip dengan rasio Komentar terhadap Perubahan, ini mengukur jumlah total komentar dalam PR, tetapi terlepas dari siapa mereka berasal. Sebaliknya dengan posting media sosial, terlalu banyak keterlibatan dalam permintaan tarik menyebabkan inefisiensi. Mengukur jumlah komentar dan reaksi untuk setiap permintaan tarik memberikan gambaran tentang bagaimana tim berkolaborasi. Kolaborasi sangat bagus, dan dukungannya adalah sesuatu yang diinginkan. Namun, setelah tingkat tertentu, diskusi memperlambat pengembangan.

Diskusi yang terlalu besar mungkin menunjukkan sesuatu yang salah: mungkin tim tidak selaras, atau mungkin persyaratan perangkat lunak tidak cukup tepat. Dalam kasus apa pun, misalignment dalam diskusi bukanlah kolaborasi; Mereka membuang -buang waktu. Dalam skenario yang berlawanan, memiliki hampir nol keterlibatan berarti tinjauan kode bukan bagian dari kebiasaan tim.

Singkatnya, metrik ini harus mencapai 'nomor ideal' berdasarkan ukuran dan distribusi tim. Itu tidak bisa terlalu banyak, dan itu tidak bisa terlalu sedikit juga.

PullRequestFlowRatio

Rasio aliran permintaan tarik adalah jumlah dari permintaan tarik yang dibuka dalam satu hari dibagi dengan jumlah permintaan tarikan tertutup pada hari yang sama. Metrik ini menunjukkan apakah tim bekerja dalam proporsi yang sehat. Menggabungkan permintaan tarik dan digunakan untuk produksi adalah hal yang baik, karena menambah nilai bagi pengguna akhir. Namun, ketika tim menutup lebih banyak permintaan tarik daripada terbuka, segera permintaan tarikan antrian kelaparan, yang berarti mungkin ada hiatus dalam pengiriman. Idealnya, yang terbaik adalah memastikan tim menggabungkan permintaan tarik dalam rasio sedekat mereka terbuka; Semakin dekat ke 1: 1, semakin baik.

PullRequestLeadTime

Metrik waktu utama memberikan gambaran tentang berapa kali (biasanya dalam beberapa hari) permintaan tarikan untuk digabungkan atau ditutup. Untuk menemukan nomor ini, tanggal dan waktu untuk setiap permintaan tarik saat dibuka dan kemudian digabungkan diperlukan. Formulanya mudah: rata -rata sederhana untuk perbedaan tanggal. Menghitung metrik ini di semua repositori dalam suatu organisasi dapat memberi tim gagasan yang lebih jelas tentang dinamika mereka.

PullRequestSize

Sejumlah besar perubahan per PR memaksakan ketegangan pada pengulas, yang melihat perhatiannya terhadap detail mengurangi lebih besar yang didapat oleh changelog. Ironisnya, pengembang cenderung menggabungkan permintaan tarikan yang lebih lama lebih cepat daripada yang lebih pendek, karena lebih sulit untuk melakukan ulasan menyeluruh ketika ada terlalu banyak hal yang terjadi. Terlepas dari seberapa teliti ulasannya, PRS besar mengarah ke waktu untuk bergabung, dan kualitas turun.

TestToCodeRatio

Sebagai aturan praktis, setidaknya setengah dari PR harus terdiri dari tes bila memungkinkan.

TimeToMerge

Secara umum, permintaan tarik terbuka dengan beberapa pekerjaan yang sedang berlangsung, yang berarti bahwa mengukur permintaan tarikan waktu tidak menceritakan keseluruhan cerita. Waktu untuk bergabung adalah berapa banyak waktu yang dibutuhkan untuk komit pertama cabang untuk mencapai cabang target. Dalam praktiknya, matematika itu sederhana: itu adalah cap waktu komitmen tertua dari cabang dikurangi cap waktu komitmen gabungan.

Waktu untuk menggabungkan biasanya berguna sementara dibandingkan dengan tuntun permintaan tarik. Ambil contoh berikut:

• Tarik Permintaan Waktu Timbal = 3 Hari
• Waktu untuk bergabung = 15 hari

Dalam skenario di atas, permintaan tarik membutuhkan waktu rata -rata 3 hari untuk digabungkan (yang cukup bagus); Tetapi waktu untuk bergabung adalah 15 hari. Yang berarti bahwa pengembang bekerja rata -rata 12 hari (15 - 3) sebelum membuka permintaan tarik.

Catatan: Metrik ini dibuat agak usang jika pengembang bekerja pada cabang WIP sebelum meremas semua perubahan menjadi satu komit yang kemudian digunakan sebagai basis untuk PR (ini akan membuat waktu untuk bergabung secara efektif sama dengan waktu tunggu permintaan tarik). Namun, metrik masih tetap sangat berguna untuk menggabungkan PRS (misalnya, penggabungan berkembang menjadi master): PRS mengatakan akan memiliki waktu tunggu permintaan tarikan yang sangat singkat (mereka tidak mendapatkan review ulang yang menyeluruh), tetapi mengukur terhadap tanggal komit pertama (waktu untuk menggabungkan) akan memberi tahu berapa lama fitur untuk mendapatkan tunjangan yang cukup layak untuk merge.

---

Mengkompilasi prolice menggunakan cargo

Prolice ditulis dengan karat. Mengkompilasi aplikasi untuk penggunaan di platform host semudah menggunakan cargo build yang jelas:

cargo build --release

Prolice kompilasi silang menggunakan cargo-make (Linux ke macOS)

Mari kita mulai bagian ini terlebih dahulu dengan sedikit kata pengantar dari posting blog yang luar biasa ini:

Saya benci kompilasi silang

Ada jutaan cara untuk merusak sistem operasi yang sedang Anda kerjakan dan menyusun kompilasi adalah salah satunya. Biasanya dimulai dengan gagasan tidak bersalah untuk mendapatkan satu rantai build yang Anda butuhkan untuk program kecil untuk dijalankan di Linksys WRT 1900 ACS (OpenWRT dan ARMV7).

Menggali di sekitar Anda menemukan beberapa cuplikan berbeda di Reddit atau beberapa masalah dalam proyek GitHub di mana orang acak memposting beberapa baris bash yang terlihat seperti sedikit informasi yang tidak Anda butuhkan.

Menjalankan pesta kemudian dapat menyebabkan salah satu hal berikut:

• Buat rantai bangunan yang berfungsi (sangat tidak mungkin)
• Buat rantai build yang gagal setelah 80% dari bangunan Anda
• Tambahkan penambang bitcoin lokal sambil berpura -pura benar -benar membuat rantai bangunan yang berfungsi

Setelah merasakan rasa sakit ini pada tingkat pribadi, kompilasi silang telah tersedia pada tingkat yang relatif bebas rasa sakit dengan target yang ditentukan di dalam proyek ini cargo-makefile.toml .

Tentu saja, jika dikompilasi hanya untuk mesin host, tetap dengan cargo build yang jelas selalu menjadi pilihan pertama. Tapi seandainya tujuannya adalah untuk menyusun dari Linux ke MacOS (Darwin) dari awal, di samping toolchain karat normal yang Anda perlukan untuk menginstal cargo-make seperti ini:

cargo install --force cargo-make

Setelah itu, langkah -langkah kompilasi benar -benar dirawat untuk Anda dengan memohon:

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

Ini akan membuat dan menempatkan, setelah proses selesai, biner terkompresi di:

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

Namun, perhatikan bahwa Linux-to-Darwin yang kompilasi silang membutuhkan Docker, jadi sekali lagi Anda dapat menghemat beberapa MBS dengan tetap menggunakan binari membangun untuk mesin host Anda hanya dengan memohon cargo build tua yang polos.