Template permintaan fitur yang menjadi changelog

Template permintaan fitur adalah formulir dengan empat pertanyaan: apa yang sedang dicoba dilakukan orang tersebut, apa yang menghalanginya, apa yang dicobanya sebagai gantinya, dan bagaimana dia ingin diberi tahu saat selesai. Semua yang lain yang biasanya muncul di formulir tersebut, pemilih prioritas, estimasi usaha, skor nilai bisnis, ditujukan untuk tim yang menerima permintaan, dan diisi dengan salah oleh yang mengirimnya.

Permintaan yang rapi adalah tes yang salah untuk sebuah template. Yang benar: enam bulan kemudian, saat fiturnya dirilis, bisakah seseorang menemukan permintaannya, memahaminya, dan memberi tahu orang yang menulisnya? Kebanyakan template dirancang untuk penerimaan. Ini dirancang untuk hari lingkarannya ditutup.

Apa yang harus dicakup template permintaan fitur?

Harus mencakup tujuan, penghalang, solusi sementara, dan cara kembali ke peminta. Empat kolom, dalam urutan itu, masing-masing menjawab pertanyaan yang akan ditanyakan tim nanti.

Yang dengan sengaja hilang: solusi yang diusulkan sebagai kolom wajib (diterima sebagai komentar, salah sebagai kerangka), pemilih prioritas (semua yang mengirim memilih tinggi), dan estimasi usaha atau nilai apa pun (tugas tim, setelah triase). Template yang meminta solusi mendapatkan permintaan untuk tombol; template yang meminta tujuan mendapatkan permintaan untuk hasil, dan tentang hasil itulah entri changelog ditulis.

Templatenya

Ini template issue GitHub yang kami gunakan, sebagai formulir. Tempel ke .github/ISSUE_TEMPLATE/feature_request.yml dan itu akan dirender sebagai formulir terstruktur di halaman issue baru. Permintaan yang diajukan melaluinya mendarat sebagai issue dengan kolom yang sama dengan yang diajukan dari widget umpan balik, yang penting untuk bagian berikutnya.

name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
  - type: textarea
    id: goal
    attributes:
      label: What are you trying to do?
      description: >-
        The outcome, not the button. "Export a month of invoices as one
        PDF" beats "add a PDF export".
    validations:
      required: true
  - type: textarea
    id: blocker
    attributes:
      label: What stops you today?
      description: >-
        Where the product runs out. An error, a missing option, a limit.
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: What do you do instead?
      description: >-
        The spreadsheet, the script, the manual step. "Nothing, I gave
        up" is a valid answer.
  - type: input
    id: contact
    attributes:
      label: How should we tell you when it ships?
      description: >-
        An email address, or leave blank to be notified only on this
        issue.

Dua detail melakukan pekerjaannya. labels: ["feature-request"] berarti permintaan diklasifikasi saat dibuat alih-alih menunggu seseorang mentriasenya. Dan kolom terakhir ada karena “kami akan memberi tahumu” adalah janji, dan janji butuh alamat.

Label apa yang harus dibawa permintaan fitur?

Permintaan fitur harus membawa satu label untuk apa itu, satu untuk seberapa mendesak, dan satu untuk dari mana asalnya. Tiga label, tiga sumbu, dan masing-masing dibaca oleh pembaca yang berbeda.

Widget menerapkan dua sumbu pertama dan from-widget saat mengajukan pengiriman sebagai issue; from-form dan from-support adalah saran untuk permintaan yang datang lewat jalur lain. Label widget adalah: jenis (bug atau feature-request, diputuskan pengklasifikasi hanya dari pesannya), prioritas (laporan kerusakan yang tenang dan spesifik adalah tinggi; duplikat dari sesuatu yang sudah ditanyakan adalah rendah; apa pun yang bahkan mengisyaratkan masalah keamanan adalah bug dan tinggi, apa pun kata-katanya), dan from-widget. Ketiga sumbu yang sama berlaku untuk permintaan yang datang secara manual melalui template di atas, dan itulah intinya: permintaan adalah permintaan, di mana pun ia masuk.

Satu konvensi lagi: widget menghapus alamat email pengirim dari badan issue sebelum mengajukannya, karena issue-nya hidup di repositori yang mungkin publik, dan menggantinya dengan referensi pengiriman. Alamatnya tetap di luar issue; pengirim mengikuti hasilnya di widget itu sendiri. Lakukan hal yang sama dengan kolom kontak jika tracker Anda terlihat oleh orang di luar tim.

Bagaimana permintaan fitur menjadi entri changelog?

Permintaan fitur menjadi entri changelog ketika pull request menutup issue-nya dan entri yang disusun dari pull request itu menautkan kembali. Mekanismenya adalah kata kunci penutupan milik GitHub sendiri: PR yang deskripsinya mengatakan Fixes #142 menutup issue 142 saat merge. Jika entri changelog Anda disusun dari pull request yang di-merge, drafnya bisa membawa nomor issue-nya, dan entrinya tahu siapa yang meminta.

Itulah alasan mengapa template meminta tujuan alih-alih solusi. Saat entri ditulis, tujuan adalah kalimat yang dibutuhkan penulis: “Sekarang Anda bisa mengekspor satu bulan faktur sebagai satu PDF” adalah entri changelog. “Menambahkan ekspor PDF” adalah pesan commit. Alat changelog yang menyusun dari pull request bisa melakukan pengumpulan dan tautannya; formulasinya masih membutuhkan seseorang, dan orang itu membutuhkan tujuannya.

Apa yang terjadi saat dirilis?

Peminta diberi tahu, dengan tautan ke entri. Dalam setup kami itu otomatis untuk permintaan yang masuk melalui widget: komentar yang mengatakan “Shipped — ” dengan tautan ke entri yang diterbitkan, diposting di issue begitu seseorang menyetujui entrinya, sementara widget menampilkan entri yang sama kepada pengirimnya. Issue yang diajukan manual dari template ini tidak mendapat komentar otomatis; tutup lingkaran itu sendiri, dengan aturan yang sama. Komentarnya sengaja diposting saat persetujuan bukan saat merge: komentar yang mengatakan sesuatu itu live sebelum benar-benar live adalah janji yang rusak dengan stempel waktu. Setiap permintaan diberi tahu paling banyak sekali; persetujuan kedua dari entri yang sama tidak menghasilkan komentar kedua.

Jika Anda melakukan ini secara manual, aturan yang sama berlaku. Jangan tutup lingkaran dari pull request. Tutup dari entri yang diterbitkan, dan tutup sekali. Feed dan widget membawa entri yang sama kepada semua orang yang tidak meminta, yang merupakan kebanyakan orang; komentarnya untuk yang meminta.

Mengapa kebanyakan template permintaan fitur gagal

Mereka dirancang untuk memudahkan triase dan berhasil, dengan mengorbankan satu momen yang penting bagi peminta. Template dengan dua belas kolom menerima lebih sedikit permintaan, dan yang diterimanya berasal dari orang-orang dengan kesabaran untuk mengisi dua belas kolom, yang bukan populasi yang sama dengan yang membutuhkan fiturnya. Template dengan empat kolom, salah satunya “bagaimana kami menghubungimu”, menerima lebih banyak permintaan dan bisa menghormati semuanya.

FAQ

Haruskah template permintaan fitur menanyakan prioritas? Tidak. Tanyakan solusi sementara sebagai gantinya. “Saya mengekspor ke spreadsheet dan mengetik ulang setiap Jumat” mengatakan lebih banyak tentang prioritas daripada dropdown yang diatur tinggi oleh pengirim.

Haruskah peminta mengusulkan solusi? Bisa, di teks bebas. Jangan jadikan itu sebagai kerangka. Permintaan yang ditulis sebagai solusi lebih sulit digabungkan satu sama lain dan lebih sulit diubah menjadi entri changelog.

Haruskah permintaan fitur muncul di roadmap publik? Setelah direncanakan, ya: label di issue yang sama menempatkannya di kolom direncanakan, dan peminta bisa melihat bagaimana pergerakannya. Artikel roadmap publik adalah mekanismenya.

Bagaimana cara menangani duplikat? Tautkan permintaan baru ke issue yang ada dan beri label prioritas rendah; jangan tutup. Setiap duplikat adalah satu orang lagi untuk diberi tahu saat dirilis. Dengan komentar otomatis Changeloop, orang itu hanya diberi tahu jika pull request juga menyebut issue mereka (Fixes #142, fixes #187).

Di mana template seharusnya berada? Di repositori yang akan menerima pull request, sehingga kata kunci penutupannya berfungsi. Permintaan di tracker terpisah harus ditautkan secara manual saat merge, dan itulah langkah yang dilewatkan.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Dokumentasi developer, Perbandingan alat changelog