Berkontribusi pada Zoo Code

Zoo Code adalah proyek yang digerakkan oleh komunitas, dan kami sangat menghargai setiap kontribusi. Untuk menyederhanakan kolaborasi, kami beroperasi dengan dasar Pendekatan Masalah-Dulu, yang berarti semua Pull Request (PR) harus terlebih dahulu ditautkan ke Masalah GitHub. Harap tinjau panduan ini dengan cermat.

Daftar Isi

• Sebelum Anda Berkontribusi
• Menemukan & Merencanakan Kontribusi Anda
• Proses Pengembangan & Pengajuan
• Ekspektasi Pull Request
• Kontribusi Berbantuan AI
• Hukum

Sebelum Anda Berkontribusi

1. Kode Etik

Semua kontributor harus mematuhi Kode Etik kami.

2. Peta Jalan Proyek

Peta jalan kami memandu arah proyek. Sejajarkan kontribusi Anda dengan tujuan-tujuan utama ini:

Keandalan Utama

• Pastikan pengeditan diff dan eksekusi perintah secara konsisten andal.
• Kurangi titik gesekan yang menghalangi penggunaan rutin.
• Jamin kelancaran operasi di semua lokal dan platform.
• Perluas dukungan yang kuat untuk berbagai penyedia dan model AI.

Pengalaman Pengguna yang Ditingkatkan

• Sederhanakan UI/UX untuk kejelasan dan intuitivitas.
• Terus tingkatkan alur kerja untuk memenuhi harapan tinggi yang dimiliki pengembang untuk alat yang digunakan sehari-hari.

Memimpin dalam Kinerja Agen

• Tetapkan tolok ukur evaluasi (eval) yang komprehensif untuk mengukur produktivitas dunia nyata.
• Permudah semua orang untuk menjalankan dan menafsirkan eval ini dengan mudah.
• Kirimkan perbaikan yang menunjukkan peningkatan yang jelas dalam skor eval.

Sebutkan keselarasan dengan area-area ini di PR Anda.

3. Bergabunglah dengan Komunitas Zoo Code

• Discord: Bergabunglah dengan Discord kami.
• Reddit: Bergabunglah dengan Reddit kami.

Menemukan & Merencanakan Kontribusi Anda

Jenis Kontribusi

• Perbaikan Bug: Mengatasi masalah kode.
• Fitur Baru: Menambahkan fungsionalitas.
• Dokumentasi: Meningkatkan panduan dan kejelasan.

Pendekatan Masalah-Dulu

Semua kontribusi dimulai dengan Masalah GitHub menggunakan template ramping kami.

• Periksa masalah yang ada: Cari di Masalah GitHub.
• Buat masalah menggunakan:
  • Penyempurnaan: Template "Permintaan Penyempurnaan" (bahasa sederhana yang berfokus pada manfaat pengguna).
  • Bug: Template "Laporan Bug" (repro minimal + yang diharapkan vs aktual + versi).
• Ingin mengerjakannya? Beri komentar "Mengklaim" pada masalah tersebut dan kirim DM ke tim inti di Discord untuk ditugaskan. Penugasan akan dikonfirmasi di utas.
• PR harus menautkan ke masalah. PR yang tidak tertaut dapat ditutup.

Memutuskan Apa yang Akan Dikerjakan

• Periksa halaman GitHub Issues untuk melihat issues.
• Untuk dokumentasi, kunjungi Dokumentasi Zoo Code.

Melaporkan Bug

• Periksa laporan yang ada terlebih dahulu.
• Buat bug baru menggunakan template "Laporan Bug" dengan:
  • Langkah-langkah reproduksi yang jelas dan bernomor
  • Hasil yang diharapkan vs aktual
  • Versi Zoo Code (wajib); penyedia/model API jika relevan
• Masalah keamanan: Laporkan secara pribadi melalui saran keamanan.

Proses Pengembangan & Pengajuan

Pengaturan Pengembangan

1. Fork & Klon:

git clone https://github.com/YOUR_USERNAME/Zoo-Code.git

2. Instal Ketergantungan:

pnpm install

3. Debugging: Buka dengan VS Code (F5).

Pedoman Menulis Kode

• Satu PR terfokus per fitur atau perbaikan.
• Ikuti praktik terbaik ESLint dan TypeScript.
• Tulis komitmen yang jelas dan deskriptif yang merujuk pada masalah (mis., Memperbaiki #123).
• Sediakan pengujian menyeluruh (npm test).
• Rebase ke cabang main terbaru sebelum pengajuan.

Mengajukan Pull Request

• Mulailah sebagai PR Draf jika mencari umpan balik awal.
• Jelaskan perubahan Anda dengan jelas mengikuti Templat Pull Request.
• Tautkan masalah di deskripsi/judul PR (mis., "Memperbaiki #123").
• Sediakan tangkapan layar/video untuk perubahan UI.
• Tunjukkan jika pembaruan dokumentasi diperlukan.

Kebijakan Pull Request

• Harus merujuk pada Masalah GitHub yang ditugaskan. Untuk ditugaskan: beri komentar "Mengklaim" pada masalah tersebut dan kirim DM ke tim inti di Discord. Penugasan akan dikonfirmasi di utas.
• PR yang tidak tertaut dapat ditutup.
• PR harus lulus tes CI, selaras dengan peta jalan, dan memiliki dokumentasi yang jelas.

Proses Peninjauan

• Triase Harian: Pemeriksaan cepat oleh pengelola.
• Tinjauan Mendalam Mingguan: Penilaian komprehensif.
• Iterasi dengan cepat berdasarkan umpan balik.

Ekspektasi Pull Request

Pull Request harus dapat ditinjau, diuji, dan dapat dipelihara. Sebelum membuka PR, pastikan bahwa:

• Perubahan dibatasi pada masalah, bug, atau peningkatan tertentu.
• Anda dapat menjelaskan apa yang dilakukan perubahan dan mengapa hal itu benar.
• Anda telah menguji perubahan secara lokal jika memungkinkan.
• Anda bersedia merespons umpan balik ulasan dan melakukan perubahan tindak lanjut yang wajar.
• PR tidak mengharuskan pengelola untuk menulis ulang, mendesain ulang, atau mengambil alih kepemilikan implementasi secara substansial sebelum dapat digabungkan.

Pengelola dapat menutup PR yang tidak lengkap, terlalu luas, tidak aktif, tidak selaras dengan arah proyek, atau yang menciptakan beban ulasan atau pemeliharaan yang tidak proporsional. Menutup PR bukan merupakan penilaian terhadap kontributor; itu adalah keputusan pengelola bahwa perubahan tersebut tidak dapat diterima dalam bentuknya saat ini.

Kontribusi Berbantuan AI

Penggunaan alat AI diperbolehkan, tetapi kontributor tetap sepenuhnya bertanggung jawab atas kiriman mereka.

Jika Anda menggunakan alat AI untuk membantu membuat PR, Anda harus:

• Meninjau dan memahami setiap perubahan yang berarti.
• Mampu menjelaskan implementasi dan pertukaran dengan kata-kata Anda sendiri.
• Menguji perubahan sendiri. Jika pengujian tidak praktis di lingkungan Anda, jelaskan alasannya dalam deskripsi PR dan uraikan bagaimana peninjau dapat memverifikasi perubahan tersebut.
• Memverifikasi bahwa kode yang dihasilkan benar, diperlukan, dan kompatibel dengan lisensi proyek.
• Pertimbangkan untuk mengungkapkan bantuan AI dalam deskripsi PR ketika hal itu secara material membentuk kode, pengujian, atau desain — ini membantu peninjau memberikan umpan balik yang lebih baik.

Jangan mengirimkan perubahan yang dihasilkan AI yang tidak Anda pahami atau tidak dapat Anda pertahankan melalui ulasan. Pengelola dapat menutup PR yang tampaknya sebagian besar dibantu AI tetapi tidak memiliki verifikasi manusia, alasan yang jelas, atau tindak lanjut ulasan.

Hukum

Dengan berkontribusi, Anda setuju bahwa kontribusi Anda akan dilisensikan di bawah Lisensi Apache 2.0, sesuai dengan lisensi Zoo Code.