karawaci.kode

2026-10-04 · 10 min

Setup Repo Open Source Ramah Kontributor untuk Hacktoberfest

Bulan lalu saya ngobrol dengan tim tiga orang yang baru membuka tool internal mereka, sebuah CLI kecil untuk generate laporan, sebagai repo publik. Niatnya baik: biar komunitas ikut bantu. Lalu Oktober datang, repo diberi topic hacktoberfest, dan dalam seminggu notifikasi GitHub mereka berubah jadi kotak masuk yang tidak pernah kosong. Ada PR yang cuma mengganti satu kata di README, issue tanpa langkah reproduksi, dan satu PR yang mengubah file workflow CI. Yang terakhir itu yang bikin saya diminta datang.

Tulisan ini adalah versi rapi dari apa yang kami kerjakan di satu akhir pekan: cara setup repo open source GitHub supaya kontributor baru punya jalur yang jelas, dan maintainer tidak habis tenaga hanya untuk menyortir. Semua file konfigurasi di bawah bisa langsung disalin. Ganti saja org-kamu dan nama tim dengan milikmu.

Masalah sebenarnya: beban kerja maintainer, bukan jumlah PR

Banyak PR itu kabar baik. Masalahnya ada di biaya per PR. Tiap kali maintainer harus bertanya “versi berapa?”, “OS apa?”, “ini menutup issue yang mana?”, itu waktu yang hilang. Kalau dikali puluhan PR selama Oktober, tim kecil bisa kehilangan berhari-hari kerja hanya untuk percakapan bolak-balik.

Jadi tujuan setup ini sederhana:

  1. Pindahkan pertanyaan standar ke form. Kontributor menjawab sebelum issue dibuat, bukan setelahnya.
  2. Arahkan review ke orang yang tepat secara otomatis. Tidak ada lagi “siapa yang mau review ini?” di grup chat.
  3. Beri label tanpa tangan manusia. Maintainer bisa memfilter PR docs dan PR kode tanpa membuka satu per satu.
  4. Jalankan CI untuk kode orang asing tanpa membuka akses ke secrets.

Struktur folder akhirnya seperti ini:

.github/
├── CODEOWNERS
├── ISSUE_TEMPLATE/
│   ├── bug_report.yml
│   ├── feature_request.yml
│   └── config.yml
├── labeler.yml
├── pull_request_template.md
└── workflows/
    ├── ci.yml
    └── labeler.yml
CONTRIBUTING.md

1. GitHub issue forms YAML: pertanyaan wajib dijawab sebelum submit

Template issue versi lama berbasis Markdown hanya berupa teks contoh yang gampang dihapus. Issue forms berbeda: field-nya terstruktur, bisa diberi required, dan hasilnya selalu dalam format yang sama. Untuk maintainer, ini artinya bisa memindai issue dalam hitungan detik.

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Laporan bug
description: Laporkan perilaku yang tidak sesuai harapan.
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Terima kasih sudah melapor! Sebelum lanjut, coba cari dulu di daftar issue
        apakah masalah yang sama sudah pernah dilaporkan.
  - type: input
    id: version
    attributes:
      label: Versi
      description: Jalankan `report-cli --version` lalu tempel hasilnya.
      placeholder: "1.4.2"
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Sistem operasi
      options:
        - Linux
        - macOS
        - Windows
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Langkah reproduksi
      description: Langkah minimal yang bisa kami ikuti untuk melihat bug-nya.
      placeholder: |
        1. Jalankan `report-cli generate --month 2026-09`
        2. Buka file output
        3. Kolom total kosong
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Yang kamu harapkan
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Log atau pesan error
      description: Akan otomatis diformat sebagai blok kode, tidak perlu backtick.
      render: shell
  - type: checkboxes
    id: checks
    attributes:
      label: Checklist
      options:
        - label: Saya sudah mencari issue serupa dan tidak menemukan yang sama.
          required: true
        - label: Saya bersedia mengirim PR untuk memperbaikinya.

Beberapa detail yang terbukti membantu:

  • labels: ["bug", "needs-triage"] membuat semua issue baru langsung masuk antrean triage. Maintainer cukup memfilter label:needs-triage di jam triage.
  • render: shell pada field log menghindari log panjang yang merusak tampilan issue.
  • Checkbox “bersedia mengirim PR” sengaja tidak wajib. Ini sinyal untuk maintainer: issue mana yang bisa langsung ditandai good first issue dan diserahkan ke pelapornya.

Lalu matikan issue kosong supaya semua orang lewat form, dan arahkan pertanyaan umum ke Discussions:

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Pertanyaan penggunaan
    url: https://github.com/org-kamu/report-cli/discussions
    about: Tanya cara pakai di Discussions, issue kami khususkan untuk bug dan fitur.

Ini salah satu perubahan paling berdampak. Pertanyaan “gimana cara install di Windows?” tidak lagi bercampur dengan laporan bug, dan maintainer tidak merasa bersalah menutup issue yang sebenarnya pertanyaan. Pertanyaannya memang punya tempat lain.

Untuk feature_request.yml, pakai pola yang sama dengan field “Masalah apa yang ingin diselesaikan” (wajib) dan “Alternatif yang sudah dicoba”. Pertanyaan pertama itu penting: kontributor baru sering datang membawa solusi, padahal maintainer perlu memahami masalahnya dulu.

2. CODEOWNERS GitHub: review otomatis ke orang yang tepat

Di tim kecil, semua orang cenderung me-review semuanya, dan akhirnya tidak ada yang merasa bertanggung jawab. CODEOWNERS memecah itu berdasarkan path.

# .github/CODEOWNERS
# Baris yang cocok PALING AKHIR yang menang, jadi aturan umum taruh di atas.

# Default: semua file direview maintainer inti
*                       @org-kamu/maintainers

# Dokumentasi boleh di-approve tim docs
/docs/                  @org-kamu/docs
*.md                    @org-kamu/docs

# File sensitif: CI dan aturan review itu sendiri
/.github/workflows/     @org-kamu/maintainers-senior
/.github/CODEOWNERS     @org-kamu/maintainers-senior

Dua hal yang sering terlewat:

  • Urutan itu penting. Kalau * ditaruh paling bawah, ia menimpa semua aturan di atasnya, dan seluruh repo jadi milik satu tim.
  • CODEOWNERS sendiri harus dilindungi. Kalau tidak, kontributor bisa mengubah daftar owner di PR yang sama dengan perubahan kodenya. Baris terakhir di atas memastikan perubahan file ini butuh approval maintainer senior.

Agar CODEOWNERS benar-benar jadi gerbang dan bukan sekadar saran, aktifkan di Settings → Rules → Rulesets (atau branch protection klasik) untuk branch main:

  • Require a pull request before merging, minimal 1 approval
  • Require review from Code Owners
  • Require status checks to pass, lalu pilih job test dari workflow CI di bawah

Tim/user yang disebut di CODEOWNERS harus punya akses write ke repo. Kalau tidak, GitHub mengabaikan baris tersebut tanpa banyak keluhan, dan kamu baru sadar saat PR ternyata bisa di-merge tanpa review mereka.

3. Template PR: kontributor tahu “selesai” itu seperti apa

Template PR yang baik bukan formulir birokrasi. Ia adalah definisi selesai yang ditulis dari sudut pandang reviewer.

<!-- .github/pull_request_template.md -->
## Ringkasan

<!-- Apa yang berubah dan kenapa. Satu-dua kalimat cukup. -->

Closes #

## Jenis perubahan

- [ ] Perbaikan bug
- [ ] Fitur baru
- [ ] Dokumentasi
- [ ] Refactor tanpa perubahan perilaku

## Checklist

- [ ] Saya sudah menjalankan `npm run lint` dan `npm test` di lokal
- [ ] Saya menambah atau memperbarui test bila perlu
- [ ] PR ini fokus pada satu perubahan (bukan gabungan beberapa hal)
- [ ] Saya sudah membaca CONTRIBUTING.md

## Catatan untuk reviewer

<!-- Bagian yang ingin kamu dapat masukan khusus, atau keputusan yang masih ragu. -->

Baris Closes # sengaja dibiarkan setengah jadi. Kontributor tinggal mengisi nomor issue, dan saat PR di-merge ke branch default, GitHub menutup issue tersebut otomatis. Satu pekerjaan administrasi maintainer hilang.

Checklist “fokus pada satu perubahan” juga bukan basa-basi. PR yang menggabungkan perbaikan typo, upgrade dependency, dan fitur baru adalah PR yang paling lama tertahan, karena tidak ada yang berani meng-approve sebagian.

4. Labeler otomatis: sortir PR tanpa membuka satu per satu

actions/labeler memberi label pada PR berdasarkan file yang diubah. Dengan ini, maintainer bisa membuka daftar PR, filter label:documentation, dan me-review semua PR docs sekaligus dalam satu sesi. Mengelompokkan pekerjaan sejenis seperti ini jauh lebih hemat energi daripada berpindah konteks tiap PR.

Konfigurasi untuk labeler v5:

# .github/labeler.yml
documentation:
  - changed-files:
      - any-glob-to-any-file: ["docs/**", "**/*.md"]

ci:
  - changed-files:
      - any-glob-to-any-file: [".github/**"]

dependencies:
  - changed-files:
      - any-glob-to-any-file: ["package.json", "package-lock.json"]

core:
  - changed-files:
      - any-glob-to-any-file: ["src/**"]

Dan workflow-nya:

# .github/workflows/labeler.yml
name: Labeler

on:
  pull_request_target:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v5

Ya, ini memakai pull_request_target, event yang akan saya peringatkan di bagian berikutnya. Di sini aman karena workflow tidak melakukan checkout dan tidak menjalankan kode dari PR. Labeler hanya membaca daftar file yang berubah lewat API, lalu memasang label. Event pull_request_target dibutuhkan karena memasang label adalah operasi write, dan token dari event pull_request biasa pada PR dari fork hanya punya akses read.

Label ci di atas punya fungsi tambahan: setiap PR yang menyentuh .github/ langsung terlihat mencolok di daftar PR. Ini PR yang harus dibaca paling teliti.

5. pull_request_target aman vs berbahaya: CI untuk PR dari fork

Ini bagian yang paling sering salah, dan dampaknya paling besar. Ringkasnya:

pull_requestpull_request_target
Kode yang dijalankanMerge commit dari PRKode dari branch base (main)
Secrets repo (PR dari fork)Tidak tersediaTersedia
GITHUB_TOKEN (PR dari fork)Read-onlyBisa write
Cocok untukBuild, lint, test kode kontributorLabel, komentar, triage tanpa menjalankan kode PR

Pola yang berbahaya terlihat seperti ini, dan sayangnya masih sering ditemukan:

# JANGAN DITIRU
on: pull_request_target

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - run: npm ci && npm test

Workflow ini mengambil kode dari fork kontributor lalu menjalankannya dengan secrets dan token write. Siapa pun bisa membuka PR yang mengubah script test di package.json atau menambah postinstall yang membaca environment variable, lalu mengirim isinya ke server mereka. Kontributor tidak perlu di-merge. Cukup membuka PR.

Pola yang aman untuk CI adalah pull_request biasa dengan permission minimal:

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ci-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm test

Kenapa beberapa baris itu ada:

  • permissions: contents: read di level workflow membatasi token, bahkan untuk push dari maintainer sendiri. Tambah permission per job hanya kalau memang perlu.
  • concurrency dengan cancel-in-progress membatalkan run lama saat kontributor push commit baru. Kontributor baru sering push lima kali berturut-turut untuk memperbaiki lint. Tanpa ini, menit CI terbuang untuk commit yang sudah usang.
  • timeout-minutes mencegah job yang hang (misalnya test yang menunggu input) menghabiskan menit sampai batas default yang jauh lebih panjang.
  • persist-credentials: false memastikan token tidak tertinggal di konfigurasi git lokal runner untuk step-step berikutnya.

Satu jebakan lagi yang tidak ada hubungannya dengan event: script injection. Jangan pernah menaruh input dari kontributor langsung di run:

# Rentan: judul PR bisa berisi perintah shell
- run: echo "Judul: ${{ github.event.pull_request.title }}"

# Aman: lewatkan sebagai environment variable
- run: echo "Judul: $PR_TITLE"
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}

Ekspresi ${{ }} disubstitusi sebelum shell berjalan, jadi judul PR seperti "; curl ... ; echo " ikut dieksekusi. Lewat env, isinya diperlakukan sebagai data biasa.

Terakhir, cek Settings → Actions → General bagian approval untuk workflow dari fork. GitHub menyediakan opsi agar workflow dari kontributor pertama kali (atau semua kolaborator luar) harus di-approve manual sebelum jalan. Untuk repo yang ikut Hacktoberfest, pilihan yang lebih ketat masuk akal. Satu klik “Approve and run” jauh lebih murah daripada menit CI yang dihabiskan PR spam.

6. Hacktoberfest maintainer: siapkan label dan jam triage

Bagian teknis di atas membuat alur rapi. Bagian ini soal manusianya.

Siapkan label sebelum Oktober. Dalam beberapa edisi terakhir, Hacktoberfest mengenali label hacktoberfest-accepted untuk PR yang diterima, serta invalid dan spam untuk PR yang tidak dihitung. Aturan persisnya bisa berubah tiap tahun, jadi cek halaman resmi hacktoberfest.com. Yang pasti, label spam yang sudah tersedia membuat maintainer bisa menutup PR asal-asalan dalam dua klik tanpa harus menulis penjelasan panjang.

Kurasi good first issue. GitHub menampilkan issue berlabel good first issue di halaman contribute repo, dan kontributor baru memang mencarinya. Pilih tiga sampai lima issue yang lingkupnya jelas, tulis file mana yang perlu diubah, dan cara mengetes hasilnya. Satu issue yang dideskripsikan dengan baik menarik PR yang baik.

Tulis CONTRIBUTING.md yang pendek. Cukup tiga bagian: cara menjalankan project di lokal (perintah persis, bukan “install dependencies”), konvensi branch dan commit, dan apa yang terjadi setelah PR dibuka, termasuk perkiraan kapan maintainer akan merespons. Kalimat seperti “kami me-review PR setiap Selasa dan Jumat” mengurangi komentar “ada update?” secara drastis.

Tetapkan jam triage, bukan triage sepanjang hari. Tim tiga orang tadi akhirnya membagi jadwal: satu orang memegang triage per hari kerja, dengan slot tetap di pagi hari. Di luar slot itu, notifikasi repo publik dimatikan. Tanpa batas seperti ini, open source pelan-pelan memakan jam kerja produk utama, dan itulah alasan paling umum repo yang baru dibuka akhirnya diarsipkan lagi.

Pakai saved replies. GitHub punya fitur saved replies di pengaturan akun. Siapkan beberapa: “terima kasih, tapi PR ini terlalu kecil untuk diterima”, “tolong pisahkan PR ini jadi dua”, “issue ini butuh langkah reproduksi”. Nada tetap ramah, dan maintainer tidak perlu merangkai kalimat yang sama berulang kali.

Trade-off yang perlu diakui

Issue forms bisa terasa kaku. Beberapa pelapor bug yang berpengalaman merasa field wajib itu berlebihan. Jaga jumlah field wajib tetap sedikit, idealnya hanya yang benar-benar dibutuhkan untuk reproduksi.

CODEOWNERS bisa jadi bottleneck. Kalau @org-kamu/maintainers-senior hanya berisi satu orang yang sedang cuti, semua PR yang menyentuh workflow tertahan. Pastikan tiap tim di CODEOWNERS berisi minimal dua orang.

Approval manual untuk workflow fork menambah langkah. Kontributor yang tulus harus menunggu sampai maintainer mengklik approve sebelum melihat hasil CI. Ini harga yang wajar, tapi sebutkan di CONTRIBUTING.md supaya mereka tidak bingung kenapa CI tidak langsung jalan.

Labeler tidak memahami isi perubahan. PR yang mengubah README.md dan src/ sekaligus dapat dua label. Ini tetap berguna untuk filter, tapi jangan jadikan label otomatis satu-satunya dasar prioritas.

Verdict

Kalau kamu hanya punya waktu satu akhir pekan sebelum Hacktoberfest, urutkan seperti ini:

  1. Audit workflow yang memakai pull_request_target. Pastikan tidak ada yang melakukan checkout kode PR. Ini satu-satunya item yang menyangkut keamanan, jadi kerjakan paling awal.
  2. Issue forms + blank_issues_enabled: false. Dampaknya langsung terasa di hari pertama.
  3. CODEOWNERS + ruleset di main. Review jadi punya pemilik yang jelas.
  4. Template PR dan labeler. Pelengkap yang membuat triage lebih cepat.
  5. Label Hacktoberfest, good first issue, dan jadwal triage. Bagian non-teknis yang menentukan apakah tim masih betah jadi maintainer di bulan November.

Repo open source yang ramah kontributor bukan repo yang menerima semua PR. Ia adalah repo yang membuat kontributor tahu apa yang diharapkan, dan membuat maintainer bisa bilang “tidak” dengan sopan tanpa kehabisan tenaga.

Ditulis oleh Ayu Pratiwi