Anatomi Repositori

Struktur repositori carbon-lang: dokumen desain, proposal, dan tempat keputusan dibuat.

Daftar isi

Topik ini memetakan struktur repositori carbon-language/carbon-lang di GitHub, tempat seluruh pekerjaan proyek Carbon berlangsung secara terbuka. Pembahasan mencakup berkas-berkas akar yang menjadi pintu masuk, folder-folder utama beserta perannya, perbedaan antara dokumentasi desain yang terus diperbarui dan arsip proposal yang merekam keputusan, serta cara menakar kebaruan sebuah dokumen. Setelah membacanya, lokasi sumber informasi untuk setiap jenis pertanyaan tentang Carbon dapat ditemukan dengan cepat dan sasarannya tepat.

Peta besar repositori#

Repositori carbon-lang menampung dua jenis isi yang berbeda fungsi, yaitu dokumen dan kode. Pada akar repositori terdapat berkas pengantar resmi berupa README.md yang menjelaskan definisi dan status proyek, CONTRIBUTING.md yang memuat panduan kontribusi, serta CODE_OF_CONDUCT.md yang menetapkan kode etik komunitas. Ketiganya menjadi rujukan pertama sebelum menyelami isi yang lebih dalam karena menautkan pembaca ke dokumen-dokumen yang lebih rinci.

Isi berupa kode dan dokumen lain dikelompokkan ke dalam folder tematik. Folder docs/ menyimpan dokumentasi yang sudah diterima, folder proposals/ mengarsipkan proposal yang telah disetujui, sedangkan folder toolchain/ menjadi rumah implementasi kompilator beserta alat pendukungnya yang saat ini menjadi fokus utama pengembangan. Folder examples/ memuat program contoh seperti hello_world.carbon dan sieve.carbon, folder testing/ menampung library khusus pengujian, folder common/ menyimpan library C++ bersama, folder core/ menyimpan library inti bahasa seperti prelude, sedangkan folder scripts/ memuat skrip pendukung pengembangan. Diagram berikut meringkas kedudukan folder-folder utama tersebut.

Folder utama repositori carbon-lang beserta perannya

Folder docs, tempat dokumentasi yang diterima#

Folder docs/ berisi dokumentasi resmi yang berlaku bagi proyek. Berkas docs/README.md menyebut isinya sebagai dokumentasi yang sudah diterima, yaitu dokumen yang telah melewati proses persetujuan dan dipelihara sebagai rujukan yang hidup. Isinya terbagi ke dalam beberapa subfolder dengan fungsi yang tegas, sehingga setiap jenis pertanyaan memiliki tempatnya sendiri.

Subfolder design/ memuat dokumen desain bahasa, dengan docs/design/README.md sebagai dokumen induk yang membahas struktur bahasa dari tipe primitif hingga kelas dan generics. Subfolder project/ menyimpan dokumen pengelolaan proyek, antara lain goals.md untuk tujuan, roadmap.md untuk peta jalan tahunan, milestones.md untuk tonggak jangka panjang, evolution.md untuk proses evolusi dan tata kelola, serta faq.md untuk pertanyaan yang sering diajukan. Adapun subfolder guides/ dan spec/ masih berstatus dokumen yang akan ditulis, sehingga isinya belum dapat diharapkan saat ini.

Kebaruan sebuah dokumen desain dapat ditakar dari penandanya. Dokumen induk desain diawali baris STATUS yang menyebut tanggal terakhir diperbarui beserta nomor proposal terakhir yang sudah tercakup, dan bagian pembukanya menegaskan bahwa banyak isinya masih bersifat provisional, yakni materi sementara yang belum diputuskan melalui proses Carbon. Kedua penanda itu menjelaskan mengapa dokumen desain tidak boleh dibaca sebagai spesifikasi final.

Folder proposals, arsip keputusan#

Folder proposals/ menyimpan teks lengkap proposal yang sudah diterima. Setiap perubahan penting pada bahasa maupun proyek melewati proses evolusi yang didokumentasikan pada docs/project/evolution.md, yaitu berupa satu pull request GitHub yang menambahkan dokumen proposal ke folder ini. Nama berkasnya mengikuti nomor pull request-nya dengan pola huruf p, enam digit, kemudian slug judul proposal. Dua contoh berikut diambil langsung dari folder tersebut.

text Contoh nama berkas proposal yang sudah diterima

proposals/p000024-generics-goals.md
proposals/p000253-2021-roadmap.md

Prosesnya dimulai dari pull request berstatus draft. Ketika penulisnya menandainya siap ditinjau, proposal dikirim sebagai RFC, yakni request for comments atau permintaan komentar, kepada seluruh komunitas, dan seorang Carbon lead ditugaskan meninjau. Perdebatan yang menghalangi persetujuan dipindahkan ke issue GitHub tersendiri agar tercatat, kemudian diputuskan oleh para lead. Setelah konsensus komunitas tercapai dan tinjauan selesai, pull request digabungkan sehingga dokumen proposalnya masuk ke folder ini.

Isi folder hanya mencakup proposal yang diterima. Proposal yang ditolak atau ditunda tidak pernah masuk ke dalamnya, sehingga teks lengkapnya hanya dapat dibaca melalui pull request aslinya yang berstatus tertutup. Aturan ini menjadikan folder proposals/ sebagai arsip keputusan yang sudah tuntas, sedangkan riwayat perdebatannya tersimpan pada pull request dan issue terkait.

Membaca dokumen dengan status yang tepat#

Dua jenis dokumen pada repositori menuntut pembacaan yang berbeda. Dokumen desain pada docs/design/ bersifat hidup dan terus disunting mengikuti keputusan terbaru, sedangkan dokumen proposal pada proposals/ merupakan rekaman keputusan pada satu titik waktu yang tidak diubah setelah digabungkan. Kesalahan yang lazim adalah mengutip proposal lama sebagai desain yang berlaku, padahal dokumen desainnya sudah direvisi melampauinya.

Dokumen desain juga menandai bagian yang tertinggal. Apabila sebuah keputusan belum sempat diterapkan ke dokumen desain, penulis proposal meninggalkan komentar TODO yang menyertakan tautan balik ke proposal sumbernya, misalnya komentar yang menunjuk proposal p005366 tentang penulisan nama impl dalam lingkup kelas. Pola ini menjadikan ketidaksesuaian terlihat jelas, bukan tersembunyi di balik teks yang tampak rapi.

Untuk pertanyaan praktis sehari-hari, docs/project/faq.md menjadi titik masuk yang ringkas karena menjawab pertanyaan seperti tempat bertanya, cara keputusan dibuat, dan lisensi proyek. Apabila jawabannya belum tersedia di sana, dokumen tujuan pada docs/project/goals.md dan dokumen proses pada docs/project/evolution.md melengkapi gambaran. Dengan kebiasaan memeriksa status dokumen terlebih dahulu, risiko mengutip materi yang sudah usang dapat ditekan sejak awal.

Ringkasan#

Repositori carbon-lang memisahkan dokumentasi yang diterima pada docs/, arsip keputusan pada proposals/, dan implementasi kompilator pada toolchain/.
Dokumen desain bersifat hidup dan menandai kebaruannya lewat baris STATUS serta komentar TODO, sedangkan proposal merupakan rekaman keputusan yang tidak berubah lagi.
Proposal dikemas sebagai pull request bernomor enam digit, hanya yang diterima yang masuk folder proposals/, dan yang ditolak tetap terbaca melalui pull request tertutupnya.
Folder docs/project/ memuat dokumen pengelolaan seperti goals.md, roadmap.md, milestones.md, evolution.md, dan faq.md.

Referensi#

README — Proyek Carbon Language — Pintu masuk resmi proyek yang memuat definisi, status, dan tautan dokumentasinya.
Docs — Proyek Carbon Language — Peta dokumentasi resmi beserta pembagian subfolder design, project, guides, dan spec.
Language design — Proyek Carbon Language — Dokumen desain induk yang memuat baris STATUS dan catatan provisional pada pembukanya.
Project — Proyek Carbon Language — Indeks dokumen pengelolaan proyek pada folder docs/project/.
Proposals — Proyek Carbon Language — Aturan folder proposal beserta pola penamaan berkas p######-slug.md.
Evolution and governance — Proyek Carbon Language — Proses proposal, peran komunitas, dan struktur tata kelola Carbon.